Reading the Response

The `.csvx` package

POST /v1/generate-dataset returns a ZIP archive when the request sends Accept: application/x-csvx. Without that header it returns JSON. See Content negotiation. The archive contains:

File	Contains
`manifest.json`	A description of the generated data: the tables, their columns and keys, and the CSV settings. See manifest.json.
`schema.json`, `schema.xml` or `schema.yaml`	A Velocity schema of the generated tables, columns and keys. One file, named by the request's `schemaFormat`. See The schema file.
`tables/<name>.csv`	One CSV file for each table, written with the settings in `csvFormat`. See Reading the CSV.

The request's schemaFormat, Json, Xml or Yaml, sets the format and file extension of the schema file. The default is Json. See Building a Request. The schemaFormat property in manifest.json records the format used.

The schema's name property is the request's schemaName, or "dataset" when that is unset or blank. The schemaName property in manifest.json records the name used.

The schema file

The schema file is a Velocity schema. A Velocity schema defines the structure of a database, including its tables, columns and constraints, in a vendor-independent format. Velocity can create the tables in a database from the schema file, ready for the CSV data to be imported. See Managing Schemas in the Velocity documentation for the schema format and the operations that use it.

The schema contains a table for each generated table, a column for each column in the table's CSV, a primary key constraint for each table with a primaryKey, and a foreign key constraint for each Reference field. Every column in a primary key is declared not null, and every other column allows nulls. The catalog property of the JSON response contains the same schema, in JSON.

manifest.json

Property	Type	Description
`schemaVersion`	`string`	The request contract version.
`seed`	`integer?`	The seed used to generate the data, including a random seed for a request that set none.
`generatedAt`	`string` (ISO 8601)	When the data was generated.
`tables`	`TableManifest[]`	One entry for each generated table.
`totalLogicalBytes`	`integer`	Sum of every table's `logicalBytes`.
`schemaFormat`	`"Json"` / `"Xml"` / `"Yaml"`	Format of the schema file in the package: `schema.json`, `schema.xml` or `schema.yaml`.
`schemaName`	`string`	Name of the generated schema: the request's `schemaName`, or `"dataset"` when that is unset or blank. The same as the `name` in the schema file.
`csvFormat`	`CsvFormatManifest`	The settings every table's CSV was written with. See Reading the CSV.

Each TableManifest:

Property	Type	Description
`name`	`string`	Table name, as given in the request.
`file`	`string`	Path of the table's CSV file in the package, e.g. `"tables/customer.csv"`.
`rowCount`	`integer`	Number of rows generated.
`logicalBytes`	`integer`	Uncompressed size in bytes of this table's CSV.
`columns`	`ColumnManifest[]`	The table's columns, in the same order as the CSV header.
`primaryKey`	`string[]?`	Columns that form the table's primary key, in key order, from the request's `primaryKey`. Absent when the table has none.
`foreignKeys`	`ForeignKeyManifest[]`	One entry for each foreign key from the table's `Reference` fields. A bridge table has two. Empty when the table has none.

Each ColumnManifest:

Property	Type	Description
`column`	`string`	Column name.
`dataType`	`string`	The data type of the column. See Data types.
`size`	`integer?`	Length of a text column. Absent when the column uses the default length of its data type. See Column widths.
`precision`	`integer?`	Total number of digits of a numeric column. Absent when the column has none.
`scale`	`integer?`	Number of digits after the decimal point of a numeric column. Absent when the column has none.

Each ForeignKeyManifest:

Property	Type	Description
`columns`	`string[]`	The referencing columns in this table, in key order. One column unless the reference sets `foreignKey`.
`targetTable`	`string`	The referenced table.
`targetColumns`	`string[]`	The referenced columns in that table, in the same order as `columns`.

The schema file declares the same keys as constraints.

Example package

This request generates a customer table with a primary key, and an orders table that references it, with the schema file in YAML:

{
  "seed": 42,
  "schemaFormat": "Yaml",
  "tables": [
    {
      "name": "customer",
      "rowCount": 3,
      "primaryKey": ["id"],
      "fields": [
        {
          "type": "Number",
          "mode": "Sequential",
          "start": 1,
          "unique": true,
          "map": { "value": { "column": "id", "dataType": "Integer" } }
        },
        {
          "type": "Person",
          "countries": [{ "country": "us" }],
          "map": { "firstName": { "column": "first_name", "dataType": "VarChar" } }
        }
      ]
    },
    {
      "name": "orders",
      "rowCount": 3,
      "fields": [
        {
          "type": "Reference",
          "targetTable": "customer",
          "targetColumn": "id",
          "map": { "value": { "column": "customer_id", "dataType": "Integer" } }
        },
        {
          "type": "Number",
          "mode": "Real",
          "min": 1,
          "max": 999,
          "scale": 2,
          "map": { "value": { "column": "amount", "dataType": "Decimal" } }
        }
      ]
    }
  ]
}

With Accept: application/x-csvx, the package contains manifest.json, schema.yaml, tables/customer.csv and tables/orders.csv.

manifest.json:

{
  "schemaVersion": "1.0",
  "seed": 42,
  "generatedAt": "2026-10-07T18:06:42.1472817+00:00",
  "tables": [
    {
      "name": "customer",
      "file": "tables/customer.csv",
      "rowCount": 3,
      "logicalBytes": 45,
      "columns": [
        { "column": "id", "dataType": "Integer" },
        { "column": "first_name", "dataType": "VarChar" }
      ],
      "primaryKey": ["id"],
      "foreignKeys": []
    },
    {
      "name": "orders",
      "file": "tables/orders.csv",
      "rowCount": 3,
      "logicalBytes": 44,
      "columns": [
        { "column": "customer_id", "dataType": "Integer" },
        { "column": "amount", "dataType": "Decimal", "precision": 5, "scale": 2 }
      ],
      "foreignKeys": [
        { "columns": ["customer_id"], "targetTable": "customer", "targetColumns": ["id"] }
      ]
    }
  ],
  "totalLogicalBytes": 89,
  "schemaFormat": "Yaml",
  "schemaName": "dataset",
  "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": "\u0022",
    "fieldDelimiter": ",",
    "escapeCharacter": "\u0022",
    "encoding": "Utf8"
  }
}

schema.yaml:

schema:
  name: dataset
  tables:
    - name: customer
      columns:
        - name: id
          type: integer
          notNull: true
        - name: first_name
          type: varchar
          size: 255
      constraints:
        - type: primarykey
          name: pk_customer
          primaryKey:
            keyColumns:
              - id
    - name: orders
      columns:
        - name: customer_id
          type: integer
        - name: amount
          type: decimal
          precision: 5
          scale: 2
      constraints:
        - type: foreignkey
          name: fk_orders_customer_id
          foreignKey:
            deleteRule: noaction
            updateRule: noaction
            sourceColumns:
              - customer_id
            lookupSchema: dataset
            lookupTable: customer
            lookupColumns:
              - id

The first_name column has no size in manifest.json, because the field sets no length, and the schema declares the default length of a varchar. The amount column has the precision and scale from the field's min, max and scale, in both files.

tables/orders.csv:

customer_id,amount
1,720.4
3,675.8
2,912.38

The manifest and the schema

The column and key information in manifest.json is also in the schema file:

`manifest.json`	Schema file
`column` of a column entry	Column `name`
`dataType` of a column entry, such as `VarChar`	Column `type`, such as `varchar`
`size`, `precision` and `scale` of a column entry	Column `size`, `precision` and `scale`. The schema also includes the default width of a data type, such as `size: 255` for a `varchar` column, where the column entry has no `size`.
`primaryKey`	Primary key constraint, and `notNull: true` on each key column
`foreignKeys`	Foreign key constraints

The column and key values in both files are identical. The files are used for different purposes:

The schema file is used to create the database tables. Its format is set by schemaFormat, and its structure is the Velocity schema format.
manifest.json describes the files in the package. It is always JSON and has the same structure for every schemaFormat. It contains information the schema file does not: each table's CSV file path, row count and size, and the settings the CSV was written with. Its column entries list each column's name and data type in the same order as the CSV header, using the same data type names as a request's map, so the CSV can be read without parsing the schema file.

POST /v1/generate-table returns no schema, so the columns of its response are the only column type information for that endpoint.

Reading the CSV

csvFormat records the settings every table's CSV was written with. Every property is always present. A property the request did not set contains its default, so the CSV can be read using the manifest alone. See CSV formatting for what each setting does.

Each CsvFormatManifest:

Property	Type	Description
`dateFormat`	`string`	Format string of `Date` values.
`dateTimeFormat`	`string`	Format string of `DateTime` values.
`timeFormat`	`string`	Format string of `Time` values.
`timestampFormat`	`string`	Format string of `Timestamp` values.
`lineTerminator`	`string`	The characters that end each row, including the header row.
`quoteCharacter`	`string`	The single character that quotes a value containing the delimiter, the quote character or a line break.
`fieldDelimiter`	`string`	The single character that separates values within a row.
`escapeCharacter`	`string`	The single character written before the quote character, and before itself, within a quoted value.
`encoding`	`"Utf8"` / `"Utf8Bom"` / `"Utf16"` / `"Utf16BigEndian"`	Character encoding of the CSV files in the package. In a JSON response, where the CSV text is always UTF-8, it is the encoding the request specified.

For a request with no csvFormat, the value is:

"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"
}

The values are JSON strings, so a line feed is written as \n and a double quote as \" or \u0022. A JSON parser returns the characters themselves.

The property names are the same as in the request's csvFormat, so this object can be sent as the csvFormat of another request to write the CSV the same way.

totalLogicalBytes, and each table's logicalBytes, is the uncompressed size of the generated data, the same value as the X-Alchemy-Generated-Bytes response header. It is measured as UTF-8 for every encoding, so the same data has the same size in every encoding, and a UTF-16 file in the package is larger than its logicalBytes.

The JSON response

The default response of POST /v1/generate-dataset, with no Accept header, is a DatasetResponse. It contains each table's columns and CSV text, and a catalog that contains the same schema as the package's schema.json file:

Property	Type	Description
`schemaVersion`	`string`	The request contract version.
`seed`	`integer?`	The seed used to generate the data, including a random seed for a request that set none.
`totalLogicalBytes`	`integer`	The same as in `manifest.json`.
`cost`	`number?`	The amount charged. See What the call cost below.
`currency`	`string?`	ISO 4217 code of the currency of `cost`.
`tables`	`TableResponse[]`	One entry for each generated table.
`csvFormat`	`CsvFormatManifest`	The settings each table's `csv` text was written with, the same as `csvFormat` in `manifest.json`. See Reading the CSV.
`catalog`	`object`	The Velocity schema for the generated tables and columns, the same as the `schema.json` file of a `.csvx` package, named by the request's `schemaName` (`"dataset"` if unset). It is a complete schema document, so it can be saved to a file and used as a Velocity schema file. See The schema file and Schema format and `Accept`.

Each TableResponse:

Property	Type	Description
`name`	`string`	Table name.
`rowCount`	`integer`	Number of rows generated.
`columns`	`ColumnManifest[]`	The table's columns, with the same properties as the column entries in `manifest.json`.
`csv`	`string`	The table's data as CSV text, the same data as the table's CSV file in a `.csvx` package.

The response to the request in Getting Started:

{
  "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 }
          ]
        }
      ]
    }
  }
}

Column widths

A column has a length, or a precision and scale, when the field that produces it determines one. These are the size, precision and scale of the column entry, and the same widths are declared in the schema. For example, a coordinate written to six decimal places has a scale of 6 and a precision of 9, decimal(9,6). Both coordinate columns have the same precision and scale, sized for the largest coordinate value, so columns with the same kind of value have the same width. A string with a maximum length has that length. A Word or Sentence string has a length that fits its largest count of the language's longest word or sentence. A prefix or postfix adds its own length.

A Number field has a width in the same way. With precision set, the column has that precision, and a value with more digits is rejected. Without it, the width is calculated from scale, min and max, or from a list of values. A field that produces unrounded values has no fixed width. Mapped to a Decimal column, which requires one, the request is rejected, and the error identifies the column and the setting to add. Mapped to another data type, the field generates as normal.

Which width applies depends on the data type of the column. A precision and scale apply to a decimal column and a length applies to a text column. A column of a type that has neither uses that type's default.

map has no width settings, because the width comes from the field's own settings. When a field's settings do not determine a width, the column uses the default width of its data type.

Schema format and `Accept`

schemaFormat applies only to the .csvx package. It sets the format of the schema file, schema.json, schema.xml or schema.yaml, and manifest.json records the format used in its schemaFormat property. In the JSON response, catalog is always JSON, and the response has no schemaFormat property.

schemaName applies to both. It is catalog.schema.name in the JSON response, and the name property in the schema file of a .csvx package. The JSON response has no separate schemaName property.

The schema has the same tables, columns and name in both responses. Only the format differs.

A request with a custom schema name:

{
  "seed": 1,
  "schemaName": "billing_export",
  "tables": [ /* ... */ ]
}

The schema name is then "billing_export" in both responses. The schema file is still named schema.json, schema.xml or schema.yaml, as set by schemaFormat.

The generate-table response

POST /v1/generate-table uses the same content negotiation. The default response is JSON with name, rowCount, columns, the table's data as a csv string, and cost and currency. With Accept: text/csv, the response is the CSV data only, including the header row, written with the request's csvFormat or the defaults. See POST /v1/generate-table.

What the call cost

Both generation endpoints report the amount charged in the response. The same amount is also listed by GET /v1/account/history.

Where	Contains
`cost` in the JSON body	The amount charged.
`currency` in the JSON body	ISO 4217 code of the currency of the amount, which is the currency the account is billed in.
`X-Alchemy-Cost` header	The same amount, written with a `.` decimal point.
`X-Alchemy-Currency` header	The same currency code.

The headers are on every successful response, including a .csvx package and a CSV response, which have no JSON body. The body properties are only in JSON responses.

The amount is in the account's currency. A request that is rejected is not charged, and its response contains no amount. See Getting Started for what the cost depends on, and GET /v1/account/balance for the remaining balance.

Content negotiation

Both generation endpoints select the response format from the Accept header:

Endpoint	Default (no `Accept` header, or an unrecognized type)	Alternative
`POST /v1/generate-dataset`	`DatasetResponse` (JSON)	`.csvx` package, with `Accept: application/x-csvx`
`POST /v1/generate-table`	`TableResponse` (JSON)	CSV, with `Accept: text/csv`

When the Accept header lists both of an endpoint's types, standard HTTP content negotiation applies: the q= quality values determine the type, and on a tie the type listed first is used.

Table of Contents