Project Integration

Drafta provides an API that enables users to create projects, generate data, and download it seamlessly. Projects are organized within project groups, allowing structured management of generated data.

Available Resources

• Project Group: Organizes multiple projects.
• Project: Defines the schema used for generating data.
• Data: Represents generated datasets.
• Provider: Manages custom data sources.

API Key Authentication

All API requests require an API key for authentication. You can find your API key in Settings → Integration → Project API Access Token.

Example Usage

Request:

GET /project-group
Authorization: Bearer YOUR_API_KEY

Project Groups

A project group must be created before creating a project. It serves as a container for organizing multiple projects.

Creating a Project Group

Request (POST /project-group):

{
  "name": "data-analysis"
}

Response:

{
  "id": "abc123",
  "name": "data-analysis",
  "created_at": "2025-02-20T12:00:00Z"
}

Retrieving a Project Group

You can retrieve a project group using either its ID or name. The response will include the list of projects within the specified group.

Request (GET /project-group/:id or /project-group/:name):

• To retrieve by ID: /project-group/abc123
• To retrieve by name: /project-group/data-analysis

{
  "id": "abc123",
  "name": "data-analysis",
  "projects": [
    {
      "id": "cda123",
      "name": "segmentation",
      "created_at": "2024-01-15T08:00:00Z",
      "updated_at": "2025-02-01T10:00:00Z"
    },
    {
      "id": "fgh456",
      "name": "sales-analysis",
      "created_at": "2024-02-01T09:30:00Z",
      "updated_at": "2025-01-20T11:15:00Z"
    },
    {
      "id": "ijk789",
      "name": "modeling",
      "created_at": "2023-12-10T14:45:00Z",
      "updated_at": "2025-02-10T12:00:00Z"
    }
  ]
}

Project Management

Projects define the schema used for generating data. Each project belongs to a project group, which helps in organizing related projects.

Creating a Project

To create a new project, send a request to the API:

Request (POST /project):

Include the following parameters:

• project_group_id: The ID of the project group (required).
• name: The name of the project (required).
• data: A string representing the schema in YAML format (optional).

{
  "project_group_id": "abc123",
  "name": "modeling"
}

Response:

{
  "id": "xyz456",
  "name": "modeling",
  "project_group_id": "abc123",
  "created_at": "2025-02-20T12:34:56Z"
}

Retrieving a Project

To retrieve a project, use the following endpoints:

• /project/:id (by ID)
• /project/:group_name/:project_name (by group name and project name, e.g., /project/data-analysis/modeling)

Request (GET /project/xyz456 or /project/data-analysis/modeling):

{
  "id": "xyz456",
  "name": "modeling",
  "project_group_id": "abc123",
  "data": "...",
  "created_at": "2025-02-20T12:34:56Z"
}

Updating a Project

To update an existing project, send a request to the same endpoint used for retrieving the project, but with the PUT method. You can update the data field, and optionally specify the format of the schema.

Request (PUT /project/:id or /project/:group_name/:project_name)

Include the following parameters:

• data (required): The updated schema string.
• format (optional): The format of the schema. Accepted values are:
  • yaml (default)
  • json_schema
  • json_parquet
  • sql

If the format is not yaml, the provided schema will be converted to yaml format as part of the update. This essentially functions as an "import" of the schema in the specified format, with the result stored as yaml.

Data Generation

Once a project is created, users can generate data based on predefined schemas.

Generating Data

To generate data based on a project’s schema, send a request to the API:

Request (POST /data/:project_id)

Include the following parameters:

• entity_name (required): The name of the table or object in the schema.
• count (required): The number of rows to generate.
• format (optional): The format of the generated data. Accepted values are:
  • json (default)
  • csv
  • parquet
• webhook_url (optional): A URL to send a webhook notification when the data generation is complete.

Example request body:

{
  "entity_name": "UserProfile",
  "count": 1000,
  "format": "json",
  "webhook_url": "https://example.com/webhook"
}

Response

{
  "id": "gen789",
  "status": "pending"
}

Checking Generation Status

To check the status of a data generation job, send a request to the API:

Request (GET /data/:data_processing_id/status)

Example request:

GET /data/gen789/status

Response

{
  "id": "gen789",
  "status": "completed",
  "data": {
    "UserProfile": "https://example.com/data/user_profile.json"
  }
}

Job Status Values

The possible status values for a job are:

• pending: The job has been created but has not yet started.
• processing: The job is currently being processed.
• completed: The job has been successfully completed.
• failed: The job has failed.

Providers

A provider is a custom data source that you can define and use within your projects to generate specific types of data. Providers are useful when you need to customize data generation.

You can create multiple providers at once by sending an array of provider definitions to the POST /provider endpoint.

Request (POST /provider)

[
  {
    "name": "CustomUserData",
    "data": ["user1", "user2", "user3"]
  },
  {
    "name": "CustomOrderData",
    "data": ["order1", "order2", "order3"]
  }
]

Response:

[
  {
    "id": "provider123",
    "name": "CustomUserData"
  },
  {
    "id": "provider124",
    "name": "CustomOrderData"
  }
]

This request creates two data providers, CustomUserData and CustomOrderData, which can then be used in projects.

CRUD Operations

You can perform CRUD (Create, Read, Update, Delete) operations on each provider:

• Create: Use the POST /provider endpoint to create one or more new providers.
• Read: Use the GET /provider/:id to retrieve a provider’s details.
• Update: Use the PUT /provider/:id to update an existing provider’s data.
• Delete: Use the DELETE /provider/:id to remove a provider.