Create projection columns (JSON split)

This page documents the canonical HTTP contract for this endpoint.

Returns an object with columns and operation_run. Column creation is immediate; values for existing rows are populated by a durable asynchronous projection backfill. Poll operation_run.operation_run_id with Get operation run. Admission is not proof that backfill has finished. Progress belongs to the operation receipt; do not infer it from a column status flag.

The HTTP model accepts items[].materialize, but initial backfill admission is attempted after creation regardless of that value. items[].isHidden is ignored when all items use the same source column and preserved when they use different source-column IDs. Projection creation does not consume normal enrichment-run credits. If backfill admission fails after columns were created, the route returns 503 with columnIds; inspect those IDs before retrying column creation.

Path parameters

table_idrequired
string
Target table ID.

Name	Type	Description
table_idrequired	string	Target table ID.

Body parameters

itemsrequired
array
Projection definitions to create. At least one new projection is required. An empty array returns 400.
items[].keyrequired
string
Requested destination column key. Existing or repeated keys are suffixed to make them unique when possible.
items[].labelrequired
string
Destination column label.
items[].sourceColumnIdrequired
string
Source JSON column ID.
items[].pathrequired
string
JSON path/key to extract.
items[].dataType · optional
string
Destination data type (default text).
items[].format · optional
object
Optional projection value-format configuration; preserved by both HTTP adapter paths.
items[].isHidden · optional
boolean
Whether the created projection column is hidden. Ignored for single-source requests and preserved for requests using different source-column IDs.
items[].materialize · optional
boolean
Accepted, but currently ignored by the HTTP handler; the initial backfill is enqueued after creation regardless of this value.
afterColumnId · optional
string
Optional insertion anchor (place after column).
beforeColumnId · optional
string
Optional insertion anchor (place before column).

Name	Type	Description
itemsrequired	array	Projection definitions to create. At least one new projection is required. An empty array returns 400.
items[].keyrequired	string	Requested destination column key. Existing or repeated keys are suffixed to make them unique when possible.
items[].labelrequired	string	Destination column label.
items[].sourceColumnIdrequired	string	Source JSON column ID.
items[].pathrequired	string	JSON path/key to extract.
items[].dataType	string	Destination data type (default text).
items[].format	object	Optional projection value-format configuration; preserved by both HTTP adapter paths.
items[].isHidden	boolean	Whether the created projection column is hidden. Ignored for single-source requests and preserved for requests using different source-column IDs.
items[].materialize	boolean	Accepted, but currently ignored by the HTTP handler; the initial backfill is enqueued after creation regardless of this value.
afterColumnId	string	Optional insertion anchor (place after column).
beforeColumnId	string	Optional insertion anchor (place before column).

Errors

Status	Meaning
401	Invalid API key or missing auth.
403	Missing columns:write scope or table access denied.
400	The referenced source column ID was not found in the table.
404	Table not found.
409	A projection key conflicted during insertion.
422	The projection request body does not match the request model.
503	Columns were created but backfill admission failed; inspect returned columnIds before retrying.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables/67bd8c39c7d3e80f0a95b560/columns/projections" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d '{
      "items":[
        {"key":"person_name","label":"Person Name","sourceColumnId":"67bd8cd8c7d3e80f0a95b58f","path":"person_name"},
        {"key":"school_domain","label":"School Domain","sourceColumnId":"67bd8cd8c7d3e80f0a95b58f","path":"school_domain"}
      ]
    }'

Request body

json

{
    "items": [
      {
        "key": "person_name",
        "label": "Person Name",
        "sourceColumnId": "67bd8cd8c7d3e80f0a95b58f",
        "path": "person_name",
        "dataType": "text"
      },
      {
        "key": "school_domain",
        "label": "School Domain",
        "sourceColumnId": "67bd8cd8c7d3e80f0a95b58f",
        "path": "school_domain",
        "dataType": "text"
      }
    ]
  }

Response example

json

{
  "columns": [
    {
      "id": "67be11b2c7d3e80f0a95b9a1",
      "key": "person_name",
      "label": "Person Name",
      "kind": "projection",
      "dataType": "text",
      "origin": "api",
      "status": "idle",
      "config": { "sourceColumnId": "67bd8cd8c7d3e80f0a95b58f", "path": "person_name" }
    },
    {
      "id": "67be11b2c7d3e80f0a95b9a2",
      "key": "school_domain",
      "label": "School Domain",
      "kind": "projection",
      "dataType": "text",
      "origin": "api",
      "status": "idle",
      "config": { "sourceColumnId": "67bd8cd8c7d3e80f0a95b58f", "path": "school_domain" }
    }
  ],
  "operation_run": {
    "operation_run_id": "oprun_example",
    "operation_id": "research_table.materialize_projection",
    "operation_type": "command",
    "source": "workflow_runtime_v2",
    "lifecycle_revision": 1,
    "status": "queued"
  }
}