Generating data from the API

Sending the generation request

To generate data for an existing database:

POST /api/v1/generate_tasks

Request body

This method expects a JSON object as the request body with the following parameters:

{
  "workspace": string,
  "database": string,
  "format": string,
  "connection": string,
  "entity": string,
  "overrides": object
}

Where:

workspace	The name of the workspace in which the database resides.
database	The name of the database for which to generate data.
format	(Optional) The format of the generated data. Allows values are "sql", "sqlite", "postgres-optimized", "csv", or "jsonl". If you provide a connection, then do not provide a format.
connection	(Optional) The name of the target database connection to insert the generated data into. If you provide a format, then do not provide a connection. When you provide a connection, the target database and all of the tables must already exist.
entity	(Optional) The name of a table to generate. When provided, Fabricate only generates data for that table, and the generated data is provided as plain text instead of a .zip file.
overrides	(Optional) Overrides to the database, entity, and field settings. For more information, go to #overrides.

Overriding the database configuration

The overrides parameter is a JSON object that allows you to override the settings for the database, entity, and fields.

The overrides parameter uses the following format:

{
  "variables": {
    "<variable_name>": string
  },
  "entities": {
    "<entity_name>": entity
  }
}

Where:

variables	List of variables to override the configured variables. For each variable, the key is the variable name, and the value is the variable value to apply.
entities	A list of tables with configuration overrides. For information about the available entity attributes, go to Entity (table) attributes.

Be sure to set the Content-Type request header to "application/json".

Returns

The response is a JSON object representing a data generation task. For example:

{
  "id": string,
  "database_id": string,
  "completed": boolean,
  "error": string,
  "progress": number,
  "created_at": string,
  "updated_at": string,
  "data_url": string,
  "content_type": string
}

Where:

id	The UUID of the task.
database_id	The UUID of the database that the task was generated for.
completed	Whether the data generation task completed.
error	If an error occurred, a string that describes the error.
progress	The progress of the task, as a number between 0 and 1.
created_at	The date and time the task was created.
updated_at	The date and time the task was most recently updated.
data_url	If the task is completed, the URL from which to download the generated data. If the request included the entity parameter, the data is provided as plain text. Otherwise, the data is provided as a .zip file.
content-type	The content type of the generated data. You can use this value to determine whether the file is a .zip file.

Example

For an example, go to generate-data.js in the fabricate-api-examples GitHub repository.

Get the status of a data generation task

To check the status of a data generation task:

GET /api/v1/generate_tasks/:id

Where:

id	The UUID of the data generation task to get

The response is a JSON object in the same format as the response from the POST /api/v1/generate_tasks endpoint.

Loading the generated data into your database

The download_url field in the response from GET /api/v1/generate_tasks/:id contains a URL to download the generated data.

Depending on the format of the data, to load it into your database, use the appropriate method:

PostgreSQL

The data is provided as a zip file.

To load the data into your database, unzip it and then run the following command:

psql -U <username> -d <database> -f path/to/dir/load.sql