Getting Started

API keys and usage

Subscribe at yndigoblue.com to get an API key. Send the key in the X-Api-Key header of every request. See Authentication below.

Each request that generates data is billed against the credits on your subscription. The cost depends on the complexity of the request, not only the size of the result. Purchased credits do not expire, and remain on your account until you use them.

The response to each generation request includes its cost. See What the call cost.

Authentication

Every request includes your API key in the X-Api-Key header.

curl -X POST https://api.alchemy.example/v1/generate-dataset \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ ... }'

Your first request

A request is a DatasetRequest, which contains an optional seed and one or more tables. Each table contains the fields that generate its columns. This request generates a customer table of 5 rows, with a sequential ID and a first and last name from US name data:

{
  "seed": 42,
  "tables": [
    {
      "name": "customer",
      "rowCount": 5,
      "fields": [
        {
          "type": "Number",
          "mode": "Sequential",
          "start": 1,
          "map": {
            "value": { "column": "id", "dataType": "Integer" }
          }
        },
        {
          "type": "Person",
          "countries": [{ "country": "us" }],
          "firstNameCaseOutput": "Proper",
          "lastNameCaseOutput": "Proper",
          "map": {
            "firstName": { "column": "first_name", "dataType": "VarChar" },
            "lastName": { "column": "last_name", "dataType": "VarChar" }
          }
        }
      ]
    }
  ]
}

Send it to POST /v1/generate-dataset:

curl -X POST https://api.alchemy.example/v1/generate-dataset \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

By default the response is JSON, a DatasetResponse containing each table's columns and its data as CSV text. To receive a .csvx package instead, a zip file containing a manifest and one CSV file per table, send Accept: application/x-csvx:

curl -X POST https://api.alchemy.example/v1/generate-dataset \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-csvx" \
  -o dataset.csvx \
  --data @request.json

The JSON response to the request above:

{
  "schemaVersion": "1.0",
  "seed": 42,
  "totalLogicalBytes": 116,
  "cost": 0.0001,
  "currency": "USD",
  "tables": [
    {
      "name": "customer",
      "rowCount": 5,
      "columns": [
        { "column": "id", "dataType": "Integer" },
        { "column": "first_name", "dataType": "VarChar" },
        { "column": "last_name", "dataType": "VarChar" }
      ],
      "csv": "id,first_name,last_name\n1,Rumualdo,Husong\n2,Paralee,Dembicki\n3,Narcisa,Zoucha\n4,Meshelle,Mcclemens\n5,Kaycee,Hanshaw\n"
    }
  ],
  "csvFormat": {
    "dateFormat": "yyyy-MM-dd",
    "dateTimeFormat": "yyyy-MM-dd HH:mm:ss",
    "timeFormat": "HH:mm:ss",
    "timestampFormat": "yyyy-MM-dd HH:mm:ss zzz",
    "lineTerminator": "\n",
    "quoteCharacter": "\"",
    "fieldDelimiter": ",",
    "escapeCharacter": "\"",
    "encoding": "Utf8"
  },
  "catalog": {
    "schema": {
      "name": "dataset",
      "tables": [
        {
          "name": "customer",
          "columns": [
            { "name": "id", "type": "integer" },
            { "name": "first_name", "type": "varchar", "size": 255 },
            { "name": "last_name", "type": "varchar", "size": 255 }
          ]
        }
      ]
    }
  }
}

Every response includes a schema: catalog in the JSON response, and a schema.* file in a .csvx package. See Reading the Response for the schema format in a .csvx package, and for setting the schema name with schemaName.

The same seed produces the same data. Sending this request again returns the same five names in the same order.

Generating a single table

To generate one table without the dataset structure or .csvx packaging, use POST /v1/generate-table. Its request has the properties of a single table at the top level, rather than in a tables array. The response contains the table's columns and its data as CSV text in JSON, or the CSV data alone when the request sends Accept: text/csv:

curl -X POST https://api.alchemy.example/v1/generate-table \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "seed": 42,
    "name": "customer",
    "rowCount": 5,
    "fields": [
      { "type": "Number", "mode": "Sequential", "start": 1,
        "map": { "value": { "column": "id", "dataType": "Integer" } } }
    ]
  }'

Sample output:

id
1
2
3
4
5

Next

• Building a Request for the full structure of DatasetRequest and TableRequest, and how a field's map sets column names and data types.
• Endpoints for every endpoint.
• Field Reference for every field type and its settings.