Custom Data API

Everything the UI does is available over the API. Base path /core/custom-data; see Authentication for tokens. Scopes: agents:read to read, agents:manage to write, custom_data:manage to author stored queries.

Tables

List

GET /core/custom-data/tables

Get one

GET /core/custom-data/tables/{name}

Includes live_rows, tombstoned_rows and last_changed_at.

Create

POST /core/custom-data/tables

{
  "name": "plans",
  "schema": {
    "type": "object",
    "required": ["plan_id"],
    "properties": {
      "plan_id":       { "type": "string", "x-key": true },
      "name":          { "type": "string", "description": "Customer-facing plan name" },
      "monthly_price": { "type": "number" },
      "region":        { "type": "string", "enum": ["EU", "US", "APAC"] },
      "available":     { "type": "boolean" }
    }
  }
}

The schema is a restricted subset of JSON Schema: a flat object, scalar types only (string, number, integer, boolean), an optional format of date or date-time on strings, and exactly one property marked "x-key": true, which must also be in required. 409 if the name is taken.

Update the schema

PATCH /core/custom-data/tables/{name}

Same body. The row key cannot move once the table has rows — 400 if you try.

Delete

DELETE /core/custom-data/tables/{name}

Removes the table and every row for good. The one place data is truly erased.

Rows

Query

POST /core/custom-data/tables/{name}/query

{
  "filters": [
    { "property": "region", "op": "eq", "value": "EU" },
    { "property": "monthly_price", "op": "lte", "value": 50 }
  ],
  "order": [{ "property": "monthly_price", "direction": "asc" }],
  "limit": 20
}

Operators: eq, neq, gt, gte, lt, lte, in, contains, starts_with. Filters address declared properties only, and comparisons use the declared types — a price compares as a number, a date as a date. A filter value that can’t be read as its column’s type matches nothing rather than failing the request, so one unusable value doesn’t discard your other filters. limit defaults to 20, maximum 500.

Get one row

GET /core/custom-data/tables/{name}/rows/{row_key}

{ "found": true, "record": { "plan_id": "pro-eu", "name": "Pro" } }

Always wrapped — found is false rather than a 404, so absent and deleted are indistinguishable to the caller.

Replace everything

POST /core/custom-data/tables/{name}/replace

{ "rows": [ { "plan_id": "pro-eu", "name": "Pro", "monthly_price": 49 } ] }

Full-state. Rows absent from rows are deleted. Returns counts:

{ "received": 900, "written": 3, "unchanged": 897, "tombstoned": 0,
  "live_before": 900, "live_after": 900, "warnings": [] }

Rows absent from rows are tombstoned, not erased: send a correct snapshot and they return.

Add or update

POST /core/custom-data/tables/{name}/upsert

Same body. Never deletes.

Delete rows

POST /core/custom-data/tables/{name}/delete-rows

{ "keys": ["legacy-eu", "legacy-us"] }

Marks them deleted. They return if the same keys appear in a later write.

Claim a row

POST /core/custom-data/tables/{name}/claim

{
  "filters": [{ "property": "used", "op": "eq", "value": false }],
  "order":   [{ "property": "pct", "direction": "asc" }],
  "patch":   { "used": true }
}

Takes one matching row, applies patch, returns it. Concurrent callers never receive the same row. { "found": false } when nothing is available — a 200, not an error. patch may only set declared properties and may not touch the row key.

Stored queries

GET    /core/custom-data/tables/{name}/queries
PUT    /core/custom-data/tables/{name}/queries/{query_name}
POST   /core/custom-data/tables/{name}/queries/dry-run
POST   /core/custom-data/tables/{name}/queries/{query_name}/enabled
POST   /core/custom-data/tables/{name}/queries/{query_name}/run
DELETE /core/custom-data/tables/{name}/queries/{query_name}

Authoring (PUT, dry-run, enabled, DELETE) needs custom_data:manage. Listing and running need only the table’s read scope. Saving:

{
  "sql": "SELECT s.name FROM stores s, args a WHERE s.region = a.region",
  "params": [{ "name": "region", "type": "string" }],
  "row_limit": 5
}

A query that fails validation is still saved, with status: "broken" and a validation_error. Only validated queries can be enabled. Running:

{ "args": { "region": "EU" } }

Arguments are bound as data, never inserted into the SQL text.

Tool schema

GET /core/custom-data/tables/{name}/tool-schema

Returns every agent tool the table produces — the generated lookup and search pair, plus one per enabled stored query — as complete tool definitions ready to drop into an agent’s tools.

Errors

Status	Meaning
`400`	Malformed request, or a schema/row that breaks the profile
`403`	Missing scope
`404`	No such table, row or query
`409`	A table with that name already exists
`503`	The read couldn’t complete — retryable

503 is worth handling separately from 500: the request was well formed and the same request may succeed on retry.

Getting Started

Agents

Knowledge Bases

Telephony

Web Widgets

Email

Campaigns

Conversations

Evaluation & Metrics

Agent Assist

Workflows

Custom Data

Anyreach in Claude

Organizations & Billing

Tables

List

Get one

Create

Update the schema

Delete

Rows

Query

Get one row

Replace everything

Add or update

Delete rows

Claim a row

Stored queries

Tool schema

Errors

​Tables

​List

​Get one

​Create

​Update the schema

​Delete

​Rows

​Query

​Get one row

​Replace everything

​Add or update

​Delete rows

​Claim a row

​Stored queries

​Tool schema

​Errors

Tables

List

Get one

Create

Update the schema

Delete

Rows

Query

Get one row

Replace everything

Add or update

Delete rows

Claim a row

Stored queries

Tool schema

Errors