Skip to main content

Reference Primitives

List, retrieve, create, and delete reference primitives: named, versioned lookup tables (code-to-label maps) referenceable from schema fields and dialect config.

A reference primitive is a named, versioned lookup table: a small dataset of rows (for example a code-to-label map like US to United States, or a tax-code table) that schema fields and resolution rules can reference. Defining the table once as a primitive lets every schema that needs it point at a single source of truth instead of duplicating the mapping.

Each primitive carries a data_schema (the column definitions for its rows) and a set of entries (the rows themselves). Entries are versioned: creating a primitive writes version 1, and the primitive tracks a current_version_number so consumers can detect when the lookup data changes. These primitive endpoints are mounted under the dialects resource at /v1/dialects/primitives and are organization-scoped.

The list and create endpoints operate on the collection. GET /v1/dialects/primitives returns every primitive in your workspace with its column schema and version metadata, but without the entry rows, keeping the listing lightweight. POST /v1/dialects/primitives creates a primitive together with its initial entry snapshot in one call.

The per-id endpoints operate on a single primitive. GET /v1/dialects/primitives/{id} resolves the current version and returns its entries inline alongside the column schema, so you see the live lookup rows. DELETE /v1/dialects/primitives/{id} removes the primitive and all of its versions.

Reference primitives are organization-scoped and shared across schemas. The list response omits the entries rows for compactness: fetch a single primitive by ID to see its current version entries inline.
GET/v1/dialects/primitives

List Response

Response fields

dataarrayArray of reference primitive objects.
data[].idstringReference primitive UUID.
data[].namestringDisplay name. Unique per workspace.
data[].descriptionstring | nullOptional description of the lookup table.
data[].data_schemaarrayColumn definitions: array of { name, type }.
data[].current_version_numberintegerCurrent version number of the entry snapshot.
data[].versions_countintegerTotal number of versions for this primitive.
data[].created_atstringISO 8601 creation timestamp.
data[].updated_atstringISO 8601 last update timestamp.
data[].links.selfstringURL to fetch this primitive by ID.

Response

{
  "data": [
    {
      "id": "p1a2b3c4-e5f6-7890-abcd-ef1234567890",
      "name": "Country Codes",
      "description": "ISO 3166-1 alpha-2 code to country name.",
      "data_schema": [
        { "name": "code", "type": "string" },
        { "name": "label", "type": "string" }
      ],
      "current_version_number": 1,
      "versions_count": 1,
      "created_at": "2024-11-01T09:00:00.000Z",
      "updated_at": "2024-11-01T09:00:00.000Z",
      "links": {
        "self": "/v1/dialects/primitives/p1a2b3c4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ]
}

Get Reference Primitive

Retrieve a single primitive by ID. The response resolves the current version and includes its entries array inline, so you see the live lookup rows alongside the column schema. Each entry object has keys matching the data_schema column names.

GET/v1/dialects/primitives/{id}

Response

{
  "id": "p1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "name": "Country Codes",
  "description": "ISO 3166-1 alpha-2 code to country name.",
  "data_schema": [
    { "name": "code", "type": "string" },
    { "name": "label", "type": "string" }
  ],
  "current_version_number": 1,
  "entries": [
    { "code": "US", "label": "United States" },
    { "code": "DE", "label": "Germany" },
    { "code": "JP", "label": "Japan" }
  ],
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-01T09:00:00.000Z",
  "links": {
    "self": "/v1/dialects/primitives/p1a2b3c4-e5f6-7890-abcd-ef1234567890"
  }
}

Create Reference Primitive

Create a primitive together with its initial version 1 entry snapshot. Provide a name (unique per workspace), a data_schema describing the entry columns, and the entries rows. The entries array may be empty if you want to seed the table later. The response returns the new primitive with its entries inline.

POST/v1/dialects/primitives

Request body

{
  "name": "Country Codes",
  "description": "ISO 3166-1 alpha-2 code to country name.",
  "data_schema": [
    { "name": "code", "type": "string" },
    { "name": "label", "type": "string" }
  ],
  "entries": [
    { "code": "US", "label": "United States" },
    { "code": "DE", "label": "Germany" }
  ]
}

Response

{
  "id": "p1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "name": "Country Codes",
  "description": "ISO 3166-1 alpha-2 code to country name.",
  "data_schema": [
    { "name": "code", "type": "string" },
    { "name": "label", "type": "string" }
  ],
  "current_version_number": 1,
  "entries": [
    { "code": "US", "label": "United States" },
    { "code": "DE", "label": "Germany" }
  ],
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-01T09:00:00.000Z",
  "links": {
    "self": "/v1/dialects/primitives/p1a2b3c4-e5f6-7890-abcd-ef1234567890"
  }
}

Delete Reference Primitive

Delete a primitive and all of its versions. This is permanent. Schema fields and resolution rules that referenced the primitive will no longer resolve against it, so confirm nothing depends on the lookup before deleting.

DELETE/v1/dialects/primitives/{id}

Response

{
  "deleted": true,
  "id": "p1a2b3c4-e5f6-7890-abcd-ef1234567890"
}

Errors

Error responses

400validation_errorMissing or invalid name, data_schema, or entries in the request body.
401unauthorizedMissing or invalid API key.
404not_foundNo reference primitive with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

List & Create Dialects
Manage Dialect
List Schemas