{ "components": { "headers": { "Location": { "description": "Where to read what this answer is about: the object created, the job started or stopped, or the approval a held request waits on.", "example": "/v1/runs/job_7ce41c00e1adaf70bca52a112ceca028", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests per window of the bucket closest to its limit: your key's, your workspace's or your instance's. Sent once the key is checked.", "example": 600, "schema": { "minimum": 0, "type": "integer" } }, "RateLimit-Policy": { "description": "The bucket's limit and window in seconds, `;w=`. Before the key is checked: the per-address limit, `120;w=60`.", "example": "600;w=60", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests left in the current window of that same bucket.", "example": 598, "schema": { "minimum": 0, "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "example": 42, "schema": { "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "The id of this request; also the error's `request_id`. Quote it when reporting an issue.", "example": "req_1888ee34e3fa99e71430e3072c54c339", "schema": { "type": "string" } } }, "schemas": { "Account": { "description": "The member who owns the calling token.", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member's email address.", "examples": [ "priya.raman@northbeam.io" ] }, "id": { "description": "The member's user id.", "examples": [ "user_8ca9b929ed7fa6a7b845bae69edb9f29" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member's display name; null when unset.", "examples": [ "Priya Raman" ] }, "object": { "description": "Always `account`.", "enum": [ "account" ], "examples": [ "account" ], "type": "string" }, "role": { "description": "The member's live role in the token's workspace (`owner`, `admin`, `editor`, `viewer`); `admin` for a super-admin token. New roles may be added.", "examples": [ "admin" ], "type": "string" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The token's workspace; null for a super-admin token.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ] } }, "required": [ "object", "id", "name", "email", "role", "workspace_id" ], "type": "object" }, "AccountResponse": { "properties": { "data": { "$ref": "#/components/schemas/Account", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "ActionParameters": { "description": "An action's parameters: everything needed to create a field from it.", "properties": { "action": { "description": "The action's id.", "examples": [ "email_finder" ], "type": "string" }, "input_schema": { "description": "A JSON Schema of the inputs' fixed values.", "examples": [ { "required": [ "domain" ] } ], "type": "object" }, "inputs": { "description": "The action's inputs.", "examples": [ [ { "accepts": { "field": true, "template": false, "value": true }, "description": "The company's website domain.", "example": "northbeam.io", "key": "domain", "label": "Company domain", "one_of_groups": [ 1 ], "required": false, "type": "template" } ] ], "items": { "properties": { "accepts": { "description": "Which bindings the input takes: a field, a fixed value or a template.", "examples": [ { "field": true, "template": false, "value": true } ], "properties": { "field": { "description": "Whether a field can feed the input.", "examples": [ "company_domain" ], "type": "boolean" }, "template": { "description": "Whether a template with `{field}` slots can feed the input.", "type": "boolean" }, "value": { "description": "Whether a fixed value can feed the input.", "type": "boolean" } }, "required": [ "field", "template", "value" ], "type": "object" }, "default": { "description": "The value used when the input is left out.", "examples": [ 10 ] }, "depends_on": { "description": "Inputs whose values its live choices need first.", "examples": [ [ "object" ] ], "items": { "type": "string" }, "type": "array" }, "description": { "description": "What the input is for.", "examples": [ "The company's website domain." ], "type": "string" }, "enum": { "description": "The allowed values of an `enum` input.", "examples": [ [ "valid", "catch_all" ] ], "items": { "type": "string" }, "type": "array" }, "example": { "description": "One value the input accepts.", "examples": [ "northbeam.io" ] }, "format": { "description": "A finer format of the type.", "examples": [ "hostname" ], "type": "string" }, "key": { "description": "The input's key in a field's `inputs`.", "examples": [ "domain" ], "type": "string" }, "label": { "deprecated": true, "description": "Deprecated: use `name`, which holds the same text.", "examples": [ "Company domain" ], "type": "string", "x-sunset": "2027-02-01" }, "name": { "description": "The input's name, as a form shows it.", "examples": [ "Company domain" ], "type": "string" }, "one_of_groups": { "description": "The `requires.one_of` groups this input belongs to, by index.", "examples": [ [ 1 ] ], "items": { "type": "integer" }, "type": "array" }, "options": { "description": "`dynamic` when the input's choices come from the connected account.", "examples": [ "dynamic" ], "type": "string" }, "properties_from": { "description": "For an object input: the live field list its keys come from.", "examples": [ "properties" ], "type": "string" }, "required": { "description": "Whether the field cannot work without it. Inputs in a `one_of` group are satisfied by the group.", "examples": [ false ], "type": "boolean" }, "type": { "description": "The value's type: `string`, `number`, `integer`, `boolean`, `enum`, `array`, `object`, `template` and more as they are added.", "examples": [ "template" ], "type": "string" } }, "required": [ "key", "type", "required", "accepts" ], "type": "object" }, "type": "array" }, "key_source": { "deprecated": true, "description": "Deprecated: use `key_sources`. `appenda`, `own` or `either` (both).", "enum": [ "appenda", "own", "either" ], "examples": [ "either" ], "type": "string", "x-sunset": "2027-02-01" }, "key_sources": { "description": "Whose keys the action can run on: `appenda` (Appenda's keys, spending credits) and `own` (a key the workspace connects). New values can appear.", "examples": [ [ "appenda", "own" ] ], "items": { "enum": [ "appenda", "own" ], "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "outputs": { "description": "The values the action returns.", "examples": [ [ "email", "status" ] ], "items": { "type": "string" }, "type": "array" }, "outputs_from": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "For actions whose outputs follow the caller's schema: the input that holds it.", "examples": [ { "input": "schema" } ] }, "provider": { "description": "The integration's id.", "examples": [ "leadmagic" ], "type": "string" }, "requires": { "description": "Alternatives: each `one_of` group lists sets of inputs, one of which must be given.", "examples": [ { "one_of": [ [ [ "first_name", "last_name" ], [ "full_name" ] ] ] } ], "properties": { "one_of": { "description": "Each group's alternatives.", "examples": [ [ [ [ "first_name", "last_name" ], [ "full_name" ] ] ] ], "items": { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, "type": "array" } }, "type": "object" }, "schema_digest": { "description": "A digest of the inputs, changing with every version.", "examples": [ "5e1f0c2a9b7d" ], "type": "string" }, "schema_version": { "description": "The parameters' version; name it when you create a field.", "examples": [ 2 ], "type": "integer" } }, "required": [ "schema_version", "inputs", "outputs", "key_source", "key_sources" ], "type": "object" }, "ActionParametersResponse": { "properties": { "data": { "$ref": "#/components/schemas/ActionParameters", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "AggregateExpression": { "description": "Arithmetic over aggregates: a number, an aggregate, or two expressions joined by an operator. At most 8 levels and 8 aggregates.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "number", "description": "The kind of expression: a number, an aggregate, or two expressions with an operator." }, "value": { "description": "A constant number.", "examples": [ 1.5 ], "maximum": 1.7976931348623157e+308, "minimum": -1.7976931348623157e+308, "type": "number" } }, "required": [ "kind", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "field_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The field the aggregate reads; null for a count of records.", "examples": [ "fld_5e8f73060c995895e07dfe7f6f6edd23" ] }, "json_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 6901 pointer to a scalar JSON value.", "examples": [ "/company/size" ] }, "kind": { "const": "aggregate", "description": "The kind of expression: a number, an aggregate, or two expressions with an operator." }, "operation": { "description": "What to compute: `count`, `count_non_empty`, `count_distinct`, `sum`, `average`, `min`, `max` or `median`.", "enum": [ "count", "count_non_empty", "count_distinct", "sum", "average", "min", "max", "median" ] } }, "required": [ "kind", "operation" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "binary", "description": "The kind of expression: a number, an aggregate, or two expressions with an operator." }, "left": { "$ref": "#/components/schemas/AggregateExpression", "description": "The left side.", "examples": [ { "kind": "number", "value": 2 } ] }, "operator": { "description": "The arithmetic: `add`, `subtract`, `multiply` or `divide`.", "enum": [ "add", "subtract", "multiply", "divide" ] }, "right": { "$ref": "#/components/schemas/AggregateExpression", "description": "The right side.", "examples": [ { "kind": "number", "value": 100 } ] } }, "required": [ "kind", "operator", "left", "right" ], "type": "object" } ] }, "AggregateGroup": { "additionalProperties": false, "properties": { "field_id": { "description": "The field to group by.", "examples": [ "fld_4ac9744e5c4b96172195f7f2f070a486" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "found_by": { "description": "On a waterfall's merged column: one group per step that found the result, keyed by the step's column id; rows no step answered are blank.", "type": "boolean" }, "json_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 6901 JSON pointer; a group path may end in /- to unnest one array.", "examples": [ "/company/size" ] }, "time_bucket": { "anyOf": [ { "enum": [ "day", "week", "month", "quarter", "year" ], "type": "string" }, { "type": "null" } ], "description": "For a date field, group by `day`, `week`, `month`, `quarter` or `year`; null for each value." } }, "required": [ "field_id" ], "type": "object" }, "AggregateMetric": { "oneOf": [ { "additionalProperties": false, "properties": { "expression": { "description": "For a calculated metric, the arithmetic over aggregates.", "examples": [ "{first_name} & \" \" & {last_name}" ], "type": "null" }, "field_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The field the metric reads; null for a count of records.", "examples": [ "fld_5e8f73060c995895e07dfe7f6f6edd23" ] }, "json_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 6901 pointer to a scalar JSON value.", "examples": [ "/company/size" ] }, "label": { "description": "The name shown for the metric.", "examples": [ "Pipeline value" ], "type": "string" }, "operation": { "description": "What to compute: `count`, `count_non_empty`, `count_distinct`, `sum`, `average`, `min`, `max` or `median`.", "enum": [ "count", "count_non_empty", "count_distinct", "sum", "average", "min", "max", "median" ] } }, "required": [ "operation", "label" ], "type": "object" }, { "additionalProperties": false, "properties": { "expression": { "$ref": "#/components/schemas/AggregateExpression", "description": "For a calculated metric, the arithmetic over aggregates.", "examples": [ "{first_name} & \" \" & {last_name}" ] }, "field_id": { "description": "The field the metric reads; null for a count of records.", "examples": [ "fld_5e8f73060c995895e07dfe7f6f6edd23" ], "type": "null" }, "json_path": { "description": "A pointer into a JSON field's value, such as `/company/size`; null for other fields.", "examples": [ "/company/size" ], "type": "null" }, "label": { "description": "The name shown for the metric.", "examples": [ "Pipeline value" ], "type": "string" }, "operation": { "const": "calculated", "description": "What to compute: `count`, `count_non_empty`, `count_distinct`, `sum`, `average`, `min`, `max` or `median`." } }, "required": [ "operation", "label", "expression" ], "type": "object" } ] }, "AggregateOrder": { "oneOf": [ { "additionalProperties": false, "properties": { "by": { "const": "group", "description": "Sort the result rows by the group key or by a metric." }, "direction": { "description": "The order: `asc` (smallest first) or `desc` (largest first).", "enum": [ "asc", "desc" ] }, "metric_index": { "description": "With `by: metric`, which metric to sort by, from 0.", "examples": [ 1 ], "type": "null" } }, "required": [ "by", "direction" ], "type": "object" }, { "additionalProperties": false, "properties": { "by": { "const": "metric", "description": "Sort the result rows by the group key or by a metric." }, "direction": { "description": "The order: `asc` (smallest first) or `desc` (largest first).", "enum": [ "asc", "desc" ] }, "metric_index": { "description": "With `by: metric`, which metric to sort by, from 0.", "examples": [ 1 ], "maximum": 7, "minimum": 0, "type": "integer" } }, "required": [ "by", "direction", "metric_index" ], "type": "object" } ] }, "AggregateRequest": { "additionalProperties": false, "properties": { "spec": { "$ref": "#/components/schemas/AggregateSpec", "description": "What to compute." } }, "required": [ "spec" ], "type": "object" }, "AggregateResponse": { "properties": { "data": { "$ref": "#/components/schemas/AggregateResult", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "AggregateResult": { "properties": { "rows": { "description": "The result rows.", "items": { "properties": { "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The group key, or null for records with no value.", "examples": [ "Meeting booked" ] }, "series": { "description": "The row's series key, present only when the request split groups into series.", "examples": [ "Enterprise" ], "type": "string" }, "values": { "description": "One value per metric, in order; null where there is none.", "examples": [ [ 1250000 ] ], "items": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maxItems": 8, "type": "array" } }, "required": [ "group", "values" ], "type": "object" }, "maxItems": 100, "type": "array" }, "truncated": { "description": "Whether more result rows exist than were returned.", "examples": [ false ], "type": "boolean" } }, "required": [ "rows", "truncated" ], "type": "object" }, "AggregateSeries": { "additionalProperties": false, "properties": { "field_id": { "description": "The field that splits each group into series.", "examples": [ "fld_4ac9744e5c4b96172195f7f2f070a486" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "json_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 6901 JSON pointer; a group path may end in /- to unnest one array.", "examples": [ "/company/size" ] }, "limit": { "anyOf": [ { "maximum": 100, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": 6, "description": "How many series to keep, 1 to 100.", "examples": [ 5 ] } }, "required": [ "field_id" ], "type": "object" }, "AggregateSource": { "additionalProperties": false, "properties": { "kind": { "const": "table", "description": "Where the records come from. Only `table` exists today." }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "kind", "table_id" ], "type": "object" }, "AggregateSpec": { "additionalProperties": false, "description": "Bounded analytical result, not a pageable collection: limit defaults to 50 and caps the top 100 returned group/series rows; truncated indicates omitted groups. Field, source, metric and grouping compatibility are validated against the table schema.", "properties": { "filter": { "anyOf": [ { "$ref": "#/components/schemas/FilterSpec" }, { "$ref": "#/components/schemas/PublicFilter" }, { "type": "null" } ], "description": "Only the records this filter keeps; null or omitted keeps every record." }, "group_by": { "anyOf": [ { "$ref": "#/components/schemas/AggregateGroup" }, { "type": "null" } ], "description": "The field to group by, or null for one total." }, "limit": { "default": 50, "description": "How many result rows to return, 1 to 100. Defaults to 50.", "examples": [ 50 ], "maximum": 100, "minimum": 1, "type": "integer" }, "metrics": { "description": "What to compute for each group, up to 8.", "items": { "$ref": "#/components/schemas/AggregateMetric" }, "maxItems": 8, "minItems": 1, "type": "array" }, "order": { "anyOf": [ { "$ref": "#/components/schemas/AggregateOrder" }, { "type": "null" } ], "description": "How to order the result rows, or null for group order." }, "series": { "anyOf": [ { "$ref": "#/components/schemas/AggregateSeries" }, { "type": "null" } ], "description": "How each group splits into series." }, "source": { "$ref": "#/components/schemas/AggregateSource", "description": "Where the records come from." } }, "required": [ "source", "metrics" ], "type": "object" }, "ApiKeyPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/ApiKeySummary" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "ApiKeySummary": { "properties": { "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the key stops working, or null if it never expires.", "examples": [ "2027-10-21T14:03:12.000Z" ] }, "id": { "description": "The key's id.", "examples": [ "ak_6d024656917ac2cb714ebd17b5244270" ], "type": "string" }, "last_four": { "description": "The key's last four characters.", "examples": [ "x7Qa" ], "type": "string" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the key was last used, or null.", "examples": [ "2026-10-21T13:58:02.000Z" ] }, "max_credits_per_day": { "anyOf": [ { "maximum": 100000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "The key's own daily credit limit, or null for none.", "examples": [ 500 ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The key's name, or null for a key created without one.", "examples": [ "CRM sync" ] }, "paused_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the key was paused for spending far more than usual (its runs are refused with `key_paused` until an admin un-pauses it), or null.", "examples": [ null ] }, "prefix": { "description": "The key's visible prefix.", "examples": [ "appenda_sk_live_" ], "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the key was revoked, or null.", "examples": [ null ] }, "role": { "description": "The role the key acts with.", "examples": [ "admin" ], "type": "string" }, "type": { "description": "`api-user` acts as its creator, with their current role, in one workspace; `super-admin` acts as an Admin in every workspace. `personal` is deprecated.", "enum": [ "api-user", "super-admin", "personal" ], "type": "string" } }, "required": [ "id", "type", "prefix", "last_four", "role", "created_at", "expires_at", "revoked_at" ], "type": "object" }, "Approval": { "description": "A request held for an approver: an API user token whose role requires approval sent it. It runs once when another member who can grant approvals approves it, and only if nothing it depends on changed since; otherwise it goes `stale` and must be sent again. A held list import runs only at its quoted price and before the quote expires. Chunked CSV imports are never held; they are refused with `403 approval_required`.", "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the held request finished running, or null.", "examples": [ null ] }, "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When an approver decided, or null.", "examples": [ null ] }, "decided_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The approver, or null.", "examples": [ null ] }, "expires_at": { "description": "When the held request expires undecided.", "examples": [ "2026-10-28T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "id": { "description": "The held request's id.", "examples": [ "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f" ], "pattern": "^apr_[0-9a-f]{32}$", "type": "string" }, "operation_id": { "description": "The held operation (for example `createRecords` or `createJob`).", "examples": [ "createJob" ], "type": "string" }, "request": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "The stored request that will run (null once decided). Never holds a secret.", "examples": [ { "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ] }, "requester_id": { "description": "The member who sent the request.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ], "type": "string" }, "result": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "The run's outcome: its HTTP status and, when small, its body (an enrichment run: its job).", "examples": [ null ] }, "status": { "description": "The held request's state: `pending` waits for a decision; `approved` is running; `succeeded` and `failed` carry the result; `rejected`, `stale`, `expired` and `cancelled` ran nothing.", "enum": [ "pending", "approved", "succeeded", "failed", "rejected", "stale", "expired", "cancelled" ], "type": "string" }, "summary": { "description": "What will run, for the approver: the operation and its target and, for a run, its rows and most credits.", "examples": [ { "maximum_credits": 500, "operation_id": "createJob", "rows": 500, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ], "type": "object" } }, "required": [ "id", "status", "operation_id", "requester_id", "summary", "request", "result", "decided_by", "created_at", "expires_at", "decided_at", "completed_at" ], "type": "object" }, "ApprovalDecision": { "additionalProperties": false, "description": "An optional reason, kept in the approval's audit trail.", "examples": [ { "reason": "Over this month's budget for this table." } ], "properties": { "reason": { "description": "Why, in words.", "examples": [ "Over this month's budget for this table." ], "maxLength": 500, "type": "string" } }, "type": "object" }, "ApprovalHeld": { "description": "The request is held for an approver and nothing ran yet. Poll the approval named in the `Location` header.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "expires_at": { "description": "When the held request expires undecided.", "examples": [ "2026-10-28T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "id": { "description": "The approval holding this request; poll it at the `Location` header.", "examples": [ "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f" ], "type": "string" }, "object": { "const": "approval", "description": "Always `approval`.", "type": "string" }, "status": { "description": "The held request's state; `pending` until an approver decides.", "enum": [ "pending", "approved", "succeeded", "failed", "rejected", "stale", "expired", "cancelled" ], "type": "string" } }, "required": [ "object", "id", "status", "expires_at" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "ApprovalPage": { "description": "One page: 50 items by default, at most 100; follow `meta.next_cursor` until it is `null`.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/Approval" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "ApprovalResponse": { "properties": { "data": { "$ref": "#/components/schemas/Approval", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "AutoRunConfig": { "additionalProperties": false, "description": "Auto-run settings for new records, with finite budgets. They stay on until you turn them off. Only an Admin or Owner who can manage the team and integrations can set them.", "properties": { "expires_at": { "deprecated": true, "description": "Deprecated and ignored: auto-run stays on until you turn it off.", "examples": [ "2026-11-20T00:00:00.000Z" ], "format": "date-time", "type": "string" }, "field_ids": { "description": "The enrichment fields new records run, up to 10.", "examples": [ [ "fld_1e57b877a78db86124936f976015f646" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "max_credits_per_batch": { "description": "The most credits one batch of new records may spend.", "examples": [ 100 ], "maximum": 10000000, "minimum": 0, "type": "integer" }, "max_credits_per_day": { "description": "Must be at least max_credits_per_batch.", "examples": [ 1000 ], "maximum": 100000000, "minimum": 0, "type": "integer" }, "max_rows_per_batch": { "description": "The most new records one batch may run, 1 to 100.", "examples": [ 50 ], "maximum": 100, "minimum": 1, "type": "integer" }, "max_rows_per_day": { "description": "Must be at least max_rows_per_batch.", "examples": [ 500 ], "maximum": 1000000, "minimum": 1, "type": "integer" }, "trigger": { "const": "new_records", "description": "Only newly created records. Existing records are never backfilled.", "type": "string" }, "view_id": { "description": "The view a new record must enter to run.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "trigger", "view_id", "field_ids", "max_rows_per_batch", "max_credits_per_batch", "max_rows_per_day", "max_credits_per_day" ], "type": "object" }, "AutoRunGrant": { "description": "The auto-run settings, bound to this view and these field configurations. A changed configuration needs a new call.", "properties": { "expires_at": { "deprecated": true, "description": "Deprecated: auto-run stays on until you turn it off, so this is 9999-01-01 for settings made now.", "examples": [ "9999-01-01T00:00:00.000Z" ], "format": "date-time", "type": "string" }, "field_ids": { "description": "The enrichment fields new records run.", "examples": [ [ "fld_1e57b877a78db86124936f976015f646" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "generation": { "deprecated": true, "description": "Deprecated: an internal counter, kept while shipped desktops read it.", "examples": [ 3 ], "format": "int64", "minimum": 1, "type": "integer", "x-sunset": "2027-02-01" }, "grant_id": { "deprecated": true, "description": "Deprecated: an internal id, kept while shipped desktops read it.", "examples": [ "autorun_49b367646693e1c432b2040b6b0c1ea0" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string", "x-sunset": "2027-02-01" }, "instance_id": { "deprecated": true, "description": "Deprecated: the instance, kept while shipped desktops read it.", "examples": [ "inst_9e815b66d1186bb90d2d77fbd69009df" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string", "x-sunset": "2027-02-01" }, "max_credits_per_batch": { "description": "The most credits one batch of new records may spend.", "examples": [ 100 ], "maximum": 10000000, "minimum": 0, "type": "integer" }, "max_credits_per_day": { "description": "Must be at least max_credits_per_batch.", "examples": [ 1000 ], "maximum": 100000000, "minimum": 0, "type": "integer" }, "max_rows_per_batch": { "description": "The most new records one batch may run, 1 to 100.", "examples": [ 50 ], "maximum": 100, "minimum": 1, "type": "integer" }, "max_rows_per_day": { "description": "Must be at least max_rows_per_batch.", "examples": [ 500 ], "maximum": 1000000, "minimum": 1, "type": "integer" }, "refusal": { "description": "Why new records are not running: the latest batch refused for a reason that will not clear, or the daily-budget pause and when it lifts. Absent while records run.", "examples": [ { "reason": "spend_cap_exceeded", "resumes_at": "2026-10-22T00:00:00.000Z" } ], "properties": { "reason": { "description": "The error code. A spend-cap code pauses until the budget resets; any other code stops that batch for good. See Errors.", "examples": [ "spend_cap_exceeded" ], "pattern": "^[a-z_]{1,64}$", "type": "string" }, "resumes_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When a paused batch runs again; null for a refusal that will not clear.", "examples": [ "2026-10-22T00:00:00.000Z" ] } }, "required": [ "reason" ], "type": "object" }, "state": { "deprecated": true, "description": "Deprecated detail of `status`: `active`, `pending`, `backlog_exceeded` and `configuration_changed` are `on`; `disabled` and `expired` are `off`.", "enum": [ "disabled", "active", "pending", "expired", "backlog_exceeded", "configuration_changed" ], "type": "string", "x-sunset": "2027-02-01" }, "status": { "description": "`on` runs new records; `off` runs nothing until you configure auto-run again.", "enum": [ "on", "off" ], "examples": [ "on" ], "type": "string" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "trigger": { "const": "new_records", "description": "Only newly created records. Existing records are never backfilled.", "type": "string" }, "view_id": { "description": "The view.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "workspace_id": { "deprecated": true, "description": "Deprecated: the workspace, kept while shipped desktops read it.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string", "x-sunset": "2027-02-01" } }, "required": [ "trigger", "view_id", "field_ids", "max_rows_per_batch", "max_credits_per_batch", "max_rows_per_day", "max_credits_per_day", "expires_at", "grant_id", "generation", "workspace_id", "instance_id", "table_id", "state" ], "type": "object" }, "AutoRunResponse": { "properties": { "data": { "anyOf": [ { "properties": { "state": { "const": "disabled", "deprecated": true, "description": "The current state.", "x-sunset": "2027-02-01" }, "status": { "const": "off", "description": "The object's state." }, "trigger": { "const": "new_records", "description": "What starts a run: only newly created records." } }, "required": [ "state", "trigger" ], "type": "object" }, { "$ref": "#/components/schemas/AutoRunGrant" } ], "description": "The table's auto-run settings, or `status: off` when none are set.", "examples": [ { "state": "disabled", "status": "off", "trigger": "new_records" } ] } }, "required": [ "data" ], "type": "object" }, "BillingQuote": { "properties": { "billable_outcomes": { "description": "The provider outcomes that are charged: `success` (a value was found) and `no_result` (the provider answered with nothing). A run's own `status` uses other words.", "items": { "enum": [ "success", "no_result" ], "type": "string" }, "type": "array" }, "billing_unit": { "description": "What one charge is for: a `row`, a `unique_row`, a `page` or a `query`.", "enum": [ "row", "unique_row", "page" ], "type": "string" }, "credits_per_unit": { "description": "Credits per charged unit.", "examples": [ 1 ], "maximum": 255, "minimum": 1, "type": "integer" }, "maximum_credits": { "description": "The most credits the run may spend.", "examples": [ 500 ], "minimum": 1, "type": "integer" }, "maximum_units": { "description": "The most units the run may charge.", "examples": [ 500 ], "minimum": 1, "type": "integer" }, "method_id": { "description": "The provider action.", "examples": [ "email_finder" ], "maxLength": 64, "minLength": 1, "type": "string" }, "provider_id": { "description": "The provider, as listed by List integrations.", "examples": [ "appenda" ], "maxLength": 64, "minLength": 1, "type": "string" }, "schema_version": { "const": 1, "description": "The quote format version." } }, "required": [ "schema_version", "provider_id", "method_id", "credits_per_unit", "billing_unit", "billable_outcomes", "maximum_units", "maximum_credits" ], "type": "object" }, "BlockDisplay": { "additionalProperties": false, "properties": { "chart_kind": { "description": "The chart: `kpi`, `bar`, `line`, `area` or `pie`.", "enum": [ "kpi", "bar", "line", "area", "pie" ] }, "color_style": { "default": "appenda", "description": "The palette: Appenda's multi-hue one, or one brand hue's tonal ramp.", "enum": [ "appenda", "greens", "yellows", "reds", "blues" ], "type": "string" }, "group_label": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "The name shown for the groups.", "examples": [ "Stage" ] }, "hide_legend": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Hide the chart legend.", "examples": [ false ] }, "series": { "description": "How each series is shown.", "items": { "$ref": "#/components/schemas/BlockSeries" }, "maxItems": 8, "type": "array" }, "title": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "The title shown on the block.", "examples": [ "Meetings by month" ] } }, "required": [ "chart_kind", "series" ], "type": "object" }, "BlockLayout": { "additionalProperties": false, "properties": { "column": { "description": "The grid column the block starts in, 1 to 12.", "examples": [ 1 ], "maximum": 12, "minimum": 1, "type": "integer" }, "height": { "deprecated": true, "description": "Deprecated and not used: a block is as tall as its content.", "examples": [ 3 ], "maximum": 8, "minimum": 1, "type": "integer", "x-sunset": "2027-02-01" }, "new_row": { "description": "Start a new row even when the row before has room; absent means false.", "examples": [ false ], "type": "boolean" }, "row": { "description": "The grid row the block starts in, from 1.", "examples": [ 1 ], "minimum": 1, "type": "integer" }, "width": { "description": "Grid columns the block spans, 1 to 12.", "examples": [ 6 ], "maximum": 12, "minimum": 1, "type": "integer" } }, "required": [ "column", "row", "width" ], "type": "object" }, "BlockSeries": { "additionalProperties": false, "properties": { "format": { "$ref": "#/components/schemas/ValueFormat", "description": "How the value is shown; display only, the stored data does not change." }, "label": { "description": "The name shown for the series.", "examples": [ "Meetings booked" ], "maxLength": 64, "minLength": 1, "type": "string" }, "palette_slot": { "anyOf": [ { "maximum": 4, "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "The palette color, 0 to 4, or null for the next one.", "examples": [ 2 ] } }, "required": [ "label", "format" ], "type": "object" }, "Commit": { "description": "One version-control commit: bounded metadata (counts and labels), never cell values.", "properties": { "action_type": { "anyOf": [ { "enum": [ "enrichment", "table_schema", "rows", "views", "imports", "restore", "fork" ], "type": "string" }, { "type": "null" } ], "description": "The feed's action filter: enrichment, table_schema, rows, views, imports, restore or fork; null for a kind this server does not know." }, "actor": { "description": "Who made the entry, and with which API key.", "properties": { "api_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The API key the change was made with, or null when it was made in the app.", "examples": [ "ak_184992130055f27f212a3582fc736e9e" ] }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where it came from: `desktop`, `agent`, `api`, `mcp` or `cloud_worker`; null when unknown.", "examples": [ "api" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member who made it, or null when unknown.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ] } }, "required": [ "id", "channel", "api_key_id" ], "type": "object" }, "actor_id": { "description": "The member who made the change.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "channel": { "description": "Where the change came from: desktop, agent, api, mcp or cloud_worker.", "examples": [ "api" ], "maxLength": 64, "type": "string" }, "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "id": { "description": "The history entry's id.", "examples": [ "commit_d42e4a6b3b74003ed5031158a1847494" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "kind": { "description": "What the entry recorded, such as `table_created` or `enrichment_run`.", "examples": [ "enrichment_run" ], "maxLength": 64, "type": "string" }, "message": { "description": "The entry's message.", "examples": [ "Enriched 212 work emails" ], "maxLength": 2048, "type": "string" }, "short_id": { "description": "A short reference for the history entry.", "examples": [ "de6127v" ], "maxLength": 16, "type": "string" }, "summary": { "additionalProperties": { "type": [ "integer", "string" ] }, "description": "Counts and labels for the change, such as rows added or rows enriched and the provider action.", "examples": [ { "method_id": "email_finder", "provider_id": "appenda", "rows_enriched": 212, "status": "succeeded" } ], "type": "object" }, "table_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The table the entry belongs to, or null for an older entry that did not record it.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ] }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The version captured at this entry, which Restore a version and Fork a version accept; null when none was kept.", "examples": [ "ver_commit_d42e4a6b3b74003ed5031158a1847494" ] } }, "required": [ "id", "short_id", "kind", "action_type", "channel", "actor_id", "message", "created_at", "summary", "table_id", "actor", "version_id" ], "type": "object" }, "CommitPage": { "description": "One page: 50 items by default, at most 100; follow `meta.next_cursor` until it is `null`.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/Commit" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "CommitResponse": { "properties": { "data": { "$ref": "#/components/schemas/Commit", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "CreateApiKey": { "additionalProperties": false, "description": "A token's authority is fixed by its kind (the collection it is created in); a role or scope list is refused.", "properties": { "expires_in_days": { "description": "Days until the key stops working, 1 to 365. Omit for a key that does not expire.", "examples": [ 90 ], "maximum": 365, "minimum": 1, "type": "integer" }, "max_credits_per_day": { "description": "The most credits the key's runs may hold in any 24 hours; past it a run is refused with `key_credit_limit_exceeded`. Default: no limit of its own.", "examples": [ 500 ], "maximum": 100000000, "minimum": 1, "type": "integer" }, "name": { "description": "A name that says what the key is for, 1 to 100 characters.", "examples": [ "CRM sync" ], "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateGroupRequest": { "additionalProperties": false, "description": "Name the fields to run (`table_id`, `field_ids`, `options`) or send a preview's token. `max_calls` and `max_credits` must cover the worst-case price unless `dry_run` is true. All stage reservations and admissions are atomic.", "examples": [ { "field_ids": [ "fld_1e57b877a78db86124936f976015f646", "fld_b00a97266f03cceb43636653c0e40b38" ], "max_calls": 1000, "max_credits": 1000, "options": { "force": false, "mode": { "kind": "all" } }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ], "properties": { "dry_run": { "default": false, "description": "Return 200 with the same answer as Preview a multi-field run, without starting anything.", "example": true, "type": "boolean" }, "field_ids": { "description": "The fields.", "examples": [ [ "fld_1e57b877a78db86124936f976015f646" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 60, "minItems": 1, "type": "array", "uniqueItems": true }, "max_calls": { "description": "The most provider calls you approve across every stage; it must cover the preview's quote.", "examples": [ 1000 ], "maximum": 6000000, "minimum": 1, "type": "integer" }, "max_credits": { "description": "The most credits you approve across every stage; it must cover the preview's quote.", "examples": [ 1000 ], "maximum": 100000000, "minimum": 0, "type": "integer" }, "options": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "force": { "const": true, "description": "Run rows that already have a result too, overwriting it and charging again. Needs `confirm_force: true`." } }, "required": [ "force" ] }, "then": { "properties": { "confirm_force": { "const": true, "description": "Confirms a forced run that overwrites results and charges again. Required with `force: true`." } }, "required": [ "confirm_force" ] } } ], "description": "Which rows the run reaches and how; force=true needs confirm_force=true and may repeat paid calls.", "examples": [ { "force": false, "mode": { "kind": "all" } } ], "properties": { "confirm_force": { "default": false, "description": "Confirms a forced run that overwrites results and charges again. Required with `force: true`.", "examples": [ false ], "type": "boolean" }, "force": { "default": false, "description": "Run rows that already have a result too, overwriting it and charging again. Needs `confirm_force: true`.", "examples": [ false ], "type": "boolean" }, "mode": { "description": "Which rows the run reaches: `all`, the `first` N, or a `range` of rows.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "all", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "count": { "description": "How many rows, from the first.", "examples": [ 500 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "kind": { "const": "first", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind", "count" ], "type": "object" }, { "additionalProperties": false, "description": "Inclusive one-based range; end must be at least start.", "properties": { "end": { "description": "The last row, from 1.", "examples": [ 600 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "kind": { "const": "range", "description": "Which kind of object this is; each kind has its own fields." }, "start": { "description": "The first row, from 1.", "examples": [ 101 ], "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": [ "kind", "start", "end" ], "type": "object" } ] }, "outcome_scope": { "description": "Run only rows whose last run ended this way: `stopped`, or an `error` of a given class.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "stopped", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "class": { "description": "Which failed rows to run again: `error_no_credits`, `error_provider` or `error_internal`.", "enum": [ "error_no_credits", "error_provider", "error_internal" ], "type": "string" }, "kind": { "const": "error", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "mode" ], "type": "object" }, "preview_token": { "deprecated": true, "description": "Deprecated: use `dry_run`. A preview's token: the run starts only if nothing it priced changed. Send it instead of `table_id`, `field_ids` and `options`.", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "maxLength": 16384, "minLength": 1, "type": "string" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "type": "object" }, "CreateJobRequest": { "description": "The selection with a spend cap (priced and started in one call), a preview's intent id and token, or a run on your own key bounded by its rows.", "examples": [ { "callback_url": "https://hooks.example.com/appenda", "credential_id": "cred_772ad6fd9b6f3d01a25cb34c169bf1b9", "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "options": { "force": false, "mode": { "count": 500, "kind": "first" } }, "spend_cap": { "max_rows": 500 }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ], "oneOf": [ { "additionalProperties": false, "anyOf": [ { "required": [ "credential_source" ] }, { "required": [ "credential_id" ] } ], "description": "Price and start the run in one call, admitted only if the price fits `spend_cap`.", "properties": { "callback_url": { "description": "An HTTPS address on port 443 POSTed once when the run ends, signed. A public DNS name only: no IP address, local name or credentials. A run held for approval gets it once approved.", "examples": [ "https://hooks.example.com/appenda" ], "format": "uri", "maxLength": 2048, "minLength": 12, "type": "string" }, "credential_id": { "description": "A provider key the workspace holds; send it alone to run on that key. Leave it out to use `credential_source`.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ], "maxLength": 64, "minLength": 1, "type": "string" }, "credential_source": { "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. `managed` (Appenda's key, spends credits), `default` (the workspace's default key) or `explicit` (the key in `credential_id`).", "enum": [ "managed", "default", "explicit" ], "type": "string" }, "field_id": { "description": "The field.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "description": "Which kind of object this is; each kind has its own fields.", "enum": [ "enrichment" ], "type": "string" }, "options": { "$ref": "#/components/schemas/RunOptions", "description": "Which rows the run reaches and how." }, "spend_cap": { "$ref": "#/components/schemas/SpendCap", "description": "The most the run may spend; it starts only if the price fits." }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "maxLength": 64, "minLength": 1, "type": "string" }, "via_agent": { "$ref": "#/components/schemas/ViaAgent", "description": "Set when an agent tool sends the request for you. Leave it out for your own requests.", "examples": [ { "kind": "claude_code" } ] } }, "required": [ "kind", "table_id", "field_id", "options", "spend_cap" ], "type": "object" }, { "additionalProperties": false, "anyOf": [ { "required": [ "credential_source" ] }, { "required": [ "credential_id" ] } ], "description": "Start the run a preview priced, with its intent id and preview token.", "properties": { "callback_url": { "description": "An HTTPS address on port 443 POSTed once when the run ends, signed. A public DNS name only: no IP address, local name or credentials. A run held for approval gets it once approved.", "examples": [ "https://hooks.example.com/appenda" ], "format": "uri", "maxLength": 2048, "minLength": 12, "type": "string" }, "credential_id": { "description": "A provider key the workspace holds; send it alone to run on that key. Leave it out to use `credential_source`.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ], "maxLength": 64, "type": "string" }, "credential_source": { "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. `managed` (Appenda's key, spends credits), `default` (the workspace's default key) or `explicit` (the key in `credential_id`).", "enum": [ "managed", "default", "explicit" ], "type": "string" }, "intent_id": { "description": "Your id for this run, used to tell retries apart.", "examples": [ "run_oct_emails" ], "maxLength": 64, "minLength": 1, "type": "string" }, "preview_token": { "deprecated": true, "description": "Deprecated: send the selection with `spend_cap`. The token from the preview, valid for this exact request only; anything changed since the preview is refused.", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "maxLength": 4096, "minLength": 32, "type": "string" }, "via_agent": { "$ref": "#/components/schemas/ViaAgent", "description": "Set when an agent tool sends the request for you. Leave it out for your own requests.", "examples": [ { "kind": "claude_code" } ] } }, "required": [ "intent_id", "preview_token" ], "type": "object" }, { "additionalProperties": false, "anyOf": [ { "required": [ "credential_source" ] }, { "required": [ "credential_id" ] } ], "description": "A run on the workspace's own key bounded by its row count: `options.mode` is `first` with `count` equal to `approved_max_calls`. Spends no credits.", "properties": { "approved_max_calls": { "description": "The rows you approve on your own key; equals `options.mode.count`, so `options.mode.kind` is `first`.", "examples": [ 100 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "callback_url": { "description": "An HTTPS address on port 443 POSTed once when the run ends, signed. A public DNS name only: no IP address, local name or credentials. A run held for approval gets it once approved.", "examples": [ "https://hooks.example.com/appenda" ], "format": "uri", "maxLength": 2048, "minLength": 12, "type": "string" }, "credential_id": { "description": "A provider key the workspace holds; send it alone to run on that key. Leave it out to use `credential_source`.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ], "maxLength": 64, "minLength": 1, "type": "string" }, "credential_source": { "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. `managed` (Appenda's key, spends credits), `default` (the workspace's default key) or `explicit` (the key in `credential_id`).", "enum": [ "default", "explicit" ], "type": "string" }, "field_id": { "description": "The field.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "description": "Which kind of object this is; each kind has its own fields.", "enum": [ "enrichment" ], "type": "string" }, "options": { "$ref": "#/components/schemas/RunOptions", "description": "Which rows the run reaches and how." }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "maxLength": 64, "minLength": 1, "type": "string" }, "via_agent": { "$ref": "#/components/schemas/ViaAgent", "description": "Set when an agent tool sends the request for you. Leave it out for your own requests.", "examples": [ { "kind": "claude_code" } ] } }, "required": [ "kind", "table_id", "field_id", "options", "approved_max_calls" ], "type": "object" } ] }, "CreatedApiKey": { "properties": { "data": { "$ref": "#/components/schemas/CreatedApiKeyData", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "CreatedApiKeyData": { "properties": { "id": { "description": "The key's id.", "examples": [ "ak_6d024656917ac2cb714ebd17b5244270" ], "type": "string" }, "last_four": { "description": "The key's last four characters.", "examples": [ "x7Qa" ], "type": "string" }, "max_credits_per_day": { "anyOf": [ { "maximum": 100000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "The key's own daily credit limit, or null for none.", "examples": [ 500 ] }, "name": { "description": "The key's name.", "examples": [ "CRM sync" ], "type": "string" }, "prefix": { "description": "The key's visible prefix.", "examples": [ "appenda_sk_live_" ], "type": "string" }, "role": { "description": "The role the key acts with.", "examples": [ "admin" ], "type": "string" }, "secret": { "description": "Shown once, on the response that created the token; never on a replay or a list.", "examples": [ "appenda_sk_live_EXAMPLEnotARealKey0000000000000000000" ], "type": "string" }, "type": { "description": "`api-user` acts as its creator, with their current role, in one workspace; `super-admin` acts as an Admin in every workspace. `personal` is deprecated.", "enum": [ "api-user", "super-admin", "personal" ], "type": "string" } }, "required": [ "id", "type", "name", "prefix", "last_four", "role" ], "type": "object" }, "CredentialCreate": { "additionalProperties": false, "examples": [ { "api_key": "your-provider-api-key", "name": "Outbound team key", "provider": "leadmagic" } ], "properties": { "api_key": { "description": "The provider's API key. It is stored encrypted and never returned.", "examples": [ "your-provider-api-key" ], "maxLength": 16384, "minLength": 1, "type": "string", "writeOnly": true }, "name": { "description": "A name for the key, so you can tell keys apart.", "examples": [ "Outbound team key" ], "maxLength": 120, "minLength": 1, "type": "string" }, "provider": { "description": "The provider the key is for, as listed by List integrations.", "examples": [ "leadmagic" ], "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`. The provider the key is for.", "examples": [ "leadmagic" ], "type": "string" } }, "required": [ "api_key", "provider" ], "type": "object" }, "CredentialMetadata": { "properties": { "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "id": { "description": "The provider key's id.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ], "type": "string" }, "is_default": { "description": "Whether this is the provider's default key.", "examples": [ true ], "type": "boolean" }, "name": { "description": "The key's name.", "examples": [ "Outbound team key" ], "type": "string" }, "ownership_scope": { "description": "Whether the key belongs to this workspace or to the whole instance.", "enum": [ "workspace", "instance" ] }, "owning_workspace_id": { "description": "The workspace that holds the key.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "type": "string" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "leadmagic" ], "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, the same value. The provider, as listed by List integrations.", "examples": [ "appenda" ], "type": "string" }, "status": { "description": "The key's state: `active` keys are used; `revoked` and `deleting` keys are not.", "enum": [ "pending", "active", "revoked", "deleting" ] } }, "required": [ "id", "provider_id", "name", "ownership_scope", "owning_workspace_id", "status", "is_default", "created_at" ], "type": "object" }, "CredentialMutation": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "id": { "description": "The provider key's id.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ], "type": "string" }, "owning_workspace_id": { "description": "The workspace that holds the key.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "type": "string" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "leadmagic" ], "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, the same value. The provider, as listed by List integrations.", "examples": [ "appenda" ], "type": "string" }, "status": { "description": "The key's state after the write.", "enum": [ "pending", "active", "revoked", "deleting" ], "examples": [ "active" ], "type": "string" } }, "required": [ "id", "provider_id", "owning_workspace_id", "status" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "CredentialPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/CredentialMetadata" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor for the next page, or null on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "CreditBalance": { "description": "The credits the workspace spends from. The balance belongs to the instance, so every workspace in it shares it; the spend cap is the workspace's own and is set in the app.", "properties": { "available": { "description": "Credits that can be spent now: what was granted, less what was spent and what running jobs hold.", "examples": [ 18450 ], "minimum": 0, "type": "integer" }, "available_decimal": { "description": "`available` as a JSON number, which can hold fractional credits. Equals the integer today: the ledger holds whole credits.", "examples": [ 18450 ], "type": "number" }, "object": { "description": "Always `credit_balance`.", "enum": [ "credit_balance" ], "examples": [ "credit_balance" ], "type": "string" }, "period": { "description": "The period `used_this_period` counts: the current UTC month.", "examples": [ { "end": "2026-11-01T00:00:00.000Z", "start": "2026-10-01T00:00:00.000Z" } ], "properties": { "end": { "description": "The next period's first moment.", "examples": [ "2026-11-01T00:00:00.000Z" ], "format": "date-time", "type": "string" }, "start": { "description": "The period's first moment.", "examples": [ "2026-10-01T00:00:00.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "plan": { "description": "The instance's plan: `trial`, `pro`, `business` or `enterprise`. New plans may be added.", "examples": [ "pro" ], "type": "string" }, "plan_allotment": { "description": "Credits granted and not yet expired: this period's plan credits, credit packs and the rollover.", "examples": [ 25000 ], "minimum": 0, "type": "integer" }, "plan_allotment_decimal": { "description": "`plan_allotment` as a JSON number, which can hold fractional credits. Equals the integer today: the ledger holds whole credits.", "examples": [ 25000 ], "type": "number" }, "renews_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the paid plan renews; null on a trial.", "examples": [ "2026-11-01T00:00:00.000Z" ] }, "rollover": { "description": "The part of `plan_allotment` carried over from last period's unused plan credits.", "examples": [ 4000 ], "minimum": 0, "type": "integer" }, "rollover_decimal": { "description": "`rollover` as a JSON number, which can hold fractional credits. Equals the integer today: the ledger holds whole credits.", "examples": [ 4000 ], "type": "number" }, "spend_cap": { "anyOf": [ { "properties": { "monthly_credits": { "description": "The most the workspace may spend in a month.", "examples": [ 5000 ], "minimum": 0, "type": "integer" }, "monthly_credits_decimal": { "description": "`monthly_credits` as a JSON number. Equals the integer today: the ledger holds whole credits.", "examples": [ 5000 ], "minimum": 0, "type": "number" }, "used_this_period": { "description": "Credits this workspace spent and holds this month, counted against its cap.", "examples": [ 1320 ], "minimum": 0, "type": "integer" } }, "required": [ "monthly_credits", "used_this_period", "monthly_credits_decimal" ], "type": "object" }, { "type": "null" } ], "description": "This workspace's monthly spending cap and what counts against it; null when no cap is set.", "examples": [ { "monthly_credits": 5000, "monthly_credits_decimal": 5000, "used_this_period": 1320 } ] }, "used_this_period": { "description": "Credits every workspace in the instance spent this period.", "examples": [ 6550 ], "minimum": 0, "type": "integer" }, "used_this_period_decimal": { "description": "`used_this_period` as a JSON number, which can hold fractional credits. Equals the integer today: the ledger holds whole credits.", "examples": [ 6550 ], "type": "number" } }, "required": [ "object", "plan", "available", "plan_allotment", "rollover", "used_this_period", "period", "renews_at", "spend_cap", "available_decimal", "plan_allotment_decimal", "rollover_decimal", "used_this_period_decimal" ], "type": "object" }, "CreditBalanceResponse": { "properties": { "data": { "$ref": "#/components/schemas/CreditBalance", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "CreditTransaction": { "description": "One movement of the balance. Grants, expiries and revocations belong to the instance and appear in every workspace of it; charges are this workspace's own. Together they add up to the balance.", "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider action the run called.", "examples": [ "email_finder" ] }, "at": { "deprecated": true, "description": "Deprecated: use `created_at`, which holds the same time.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string", "x-sunset": "2027-02-01" }, "created_at": { "description": "When it happened.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "credits": { "description": "Credits added (positive) or taken (negative).", "examples": [ -48 ], "type": "integer" }, "credits_decimal": { "description": "`credits` as a JSON number, which can hold fractional credits. Equals the integer today: the ledger holds whole credits.", "examples": [ -48 ], "type": "number" }, "field_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The key of the field the run filled; null when there is none or it was deleted.", "examples": [ "work_email" ] }, "id": { "description": "The transaction's id.", "examples": [ "lc_4485eb6d46e82821bb463595494d1f30" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "kind": { "description": "`charge`: a run spent credits. `grant`: credits were added. `expire`: unused credits lapsed. `revoke`: granted credits were taken back. New kinds may be added.", "enum": [ "charge", "grant", "expire", "revoke" ], "examples": [ "charge" ], "type": "string" }, "object": { "description": "Always `credit_transaction`.", "enum": [ "credit_transaction" ], "examples": [ "credit_transaction" ], "type": "string" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider the run called.", "examples": [ "leadmagic" ] }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The run a charge belongs to; null otherwise.", "examples": [ "job_f799d04594ff4df5347c941a1018d24f" ] }, "scope": { "description": "`workspace`: this workspace's charge. `instance`: a grant, expiry or revocation shared by every workspace.", "enum": [ "workspace", "instance" ], "examples": [ "workspace" ], "type": "string" }, "table_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The table the run enriched; null for an instance transaction.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ] } }, "required": [ "object", "id", "kind", "credits", "run_id", "table_id", "field_key", "provider", "action", "scope", "at", "credits_decimal", "created_at" ], "type": "object" }, "CreditTransactionPage": { "description": "Credit transactions, newest first. Default 50 and maximum 100 per page; follow `next_cursor` until it is null.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/CreditTransaction" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "The cursor to the next page; null on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "CsvDataFieldType": { "description": "Validated field types allowed for CSV schema creation. Formula and Enrichment are excluded.", "oneOf": [ { "enum": [ "text", "number", "boolean", "date", "json", "url", "email", "phone" ], "type": "string" }, { "additionalProperties": false, "properties": { "number": { "$ref": "#/components/schemas/NumberFormat", "description": "A number field and how it is shown." } }, "required": [ "number" ], "type": "object" }, { "additionalProperties": false, "properties": { "date": { "$ref": "#/components/schemas/DateOptions", "description": "A date field and how it is shown." } }, "required": [ "date" ], "type": "object" }, { "additionalProperties": false, "properties": { "url": { "$ref": "#/components/schemas/UrlOptions", "description": "A URL field and how it is normalized." } }, "required": [ "url" ], "type": "object" }, { "additionalProperties": false, "properties": { "single_select": { "$ref": "#/components/schemas/SelectConfig", "description": "A single-choice field and its choices." } }, "required": [ "single_select" ], "type": "object" }, { "additionalProperties": false, "properties": { "multi_select": { "$ref": "#/components/schemas/SelectConfig", "description": "A multiple-choice field and its choices." } }, "required": [ "multi_select" ], "type": "object" } ] }, "CsvExportPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "csv": { "description": "This page as CSV. The first page starts with a byte-order mark and the header line. Text a spreadsheet would run as a formula starts with `'`.", "examples": [ "Company domain,Work email\r\nnorthbeam.io,priya.raman@northbeam.io\r\n" ], "type": "string" }, "rows": { "description": "Records on this page.", "examples": [ 100 ], "type": "integer" } }, "required": [ "csv", "rows" ], "type": "object" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor for the next page, or null on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "CsvExportRequest": { "additionalProperties": false, "description": "Pages in a stable order, ties broken by id; edits made while you page can move items between pages.", "examples": [ { "delimiter": "comma", "limit": 100, "view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "properties": { "cursor": { "description": "The `next_cursor` from the previous page; omit for the first page. Bound to this list and its filters.", "examples": [ "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJyZWNfNWUxOWE3In0" ], "maxLength": 16384, "type": "string" }, "delimiter": { "description": "The CSV delimiter: `comma`, `semicolon` or `tab`.", "enum": [ "comma", "semicolon", "tab" ] }, "filter": { "$ref": "#/components/schemas/FilterSpec", "description": "Only the records this filter keeps; null or omitted keeps every record." }, "limit": { "default": 50, "description": "Records per page, 1 to 100. Defaults to 50.", "examples": [ 100 ], "maximum": 100, "minimum": 1, "type": "integer" }, "sort": { "$ref": "#/components/schemas/SortSpec", "description": "The order of the records; omitted keeps table order." }, "view_id": { "description": "Export only the records this view keeps, in its order.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [], "type": "object" }, "CsvImportChunk": { "additionalProperties": false, "properties": { "csv": { "description": "Data rows only, no header, in the started file's delimiter: up to 1,000 rows and about 32 KiB.", "examples": [ "ledgerline.com,marcus.lee@ledgerline.com\r\nfernhill.ai,ana.sousa@fernhill.ai\r\n" ], "minLength": 1, "type": "string" }, "index": { "description": "0-based chunk number; rows land in chunk order whatever order chunks arrive in. Resending an index with the same text is a replay; different text is 409.", "examples": [ 1 ], "maximum": 4999, "minimum": 0, "type": "integer" } }, "required": [ "index", "csv" ], "type": "object" }, "CsvImportFinish": { "additionalProperties": false, "properties": {}, "type": "object" }, "CsvImportJobResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "chunks_applied": { "description": "Chunks imported so far.", "examples": [ 12 ], "type": "integer" }, "commit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The import's history entry, once it has ended; null while it runs.", "examples": [ null ] }, "created_at": { "description": "When the import was started.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "fields_added": { "description": "Fields added.", "examples": [ 2 ], "type": "integer" }, "id": { "description": "The chunked import's id.", "examples": [ "csvi_71bdd9226218f46867d26a5795bc2041" ], "type": "string" }, "records_added": { "description": "Records added.", "examples": [ 980 ], "type": "integer" }, "rows_added": { "deprecated": true, "description": "Deprecated: use `records_added`, which holds the same number.", "examples": [ 980 ], "type": "integer", "x-sunset": "2027-02-01" }, "state": { "deprecated": true, "description": "Deprecated: use `status`, in the words every job uses. The import's state: `running`, `completed` or `stopped`.", "enum": [ "running", "completed", "stopped" ] }, "status": { "description": "The import's state: `running`, `succeeded` or `stopped`, in the words every job uses. New values can appear.", "enum": [ "queued", "running", "succeeded", "failed", "stopped", "needs_review" ], "examples": [ "running" ], "type": "string" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "type": "string" }, "updated_at": { "description": "When the import last changed: a chunk applied, finished or stopped.", "examples": [ "2026-10-21T14:04:01.000Z" ], "format": "date-time", "type": "string" }, "values_emptied": { "description": "Values that did not fit their field and were left empty.", "examples": [ 3 ], "type": "integer" } }, "required": [ "id", "table_id", "state", "status", "chunks_applied", "rows_added", "values_emptied", "fields_added", "commit_id", "created_at", "updated_at", "records_added" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "CsvImportPreview": { "oneOf": [ { "$ref": "#/components/schemas/CsvImportPreviewAppend" }, { "$ref": "#/components/schemas/RecordUpsertPreview" } ] }, "CsvImportPreviewAppend": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "columns": { "description": "The file's columns, in header order.", "items": { "properties": { "header": { "description": "The column's header.", "examples": [ "Company domain" ], "type": "string" }, "match": { "description": "How the column maps: to an `existing` field, a `new` field, or `unmapped`.", "enum": [ "existing", "new", "unmapped" ] }, "suggest_select": { "description": "Whether the column looks like a list of choices.", "examples": [ false ], "type": "boolean" }, "suggested_mapping": { "$ref": "#/components/schemas/CsvMapping", "description": "The mapping proposed for the column." } }, "type": "object" }, "type": "array" }, "duplicates_to_remove": { "description": "Rows the table's dedupe setting would drop or replace.", "examples": [ 4 ], "type": "integer" }, "fields_to_add": { "description": "Fields the import would create.", "examples": [ 2 ], "type": "integer" }, "mappings": { "description": "One mapping per column, in header order.", "items": { "$ref": "#/components/schemas/CsvMapping" }, "type": "array" }, "preview_token": { "description": "The token from the preview, valid for this exact request only. Anything changed since the preview is refused.", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "type": "string" }, "records_read": { "description": "Data rows read from the file, one record each.", "examples": [ 980 ], "type": "integer" }, "records_to_add": { "description": "Records the import would add.", "examples": [ 976 ], "type": "integer" }, "rows_read": { "deprecated": true, "description": "Deprecated: use `records_read`, which holds the same number.", "examples": [ 980 ], "type": "integer", "x-sunset": "2027-02-01" }, "rows_to_add": { "deprecated": true, "description": "Deprecated: use `records_to_add`, which holds the same number.", "examples": [ 976 ], "type": "integer", "x-sunset": "2027-02-01" }, "sample": { "description": "The first rows of the file, as read.", "examples": [ [ [ "northbeam.io", "priya.raman@northbeam.io" ] ] ], "items": { "items": { "type": "string" }, "type": "array" }, "maxItems": 10, "type": "array" }, "values_emptied": { "description": "Values that do not fit their field and would be left empty.", "examples": [ 3 ], "type": "integer" } }, "required": [ "columns", "mappings", "sample", "rows_read", "rows_to_add", "fields_to_add", "values_emptied", "preview_token", "records_read", "records_to_add" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "CsvImportPreviewRequest": { "additionalProperties": false, "examples": [ { "csv": "Company domain,Lead stage,Notes\r\nledgerline.com,Meeting booked,Asked for pricing\r\n", "mappings": [ { "field": "company_domain", "kind": "existing" }, { "field": "lead_stage", "kind": "existing" }, { "kind": "skip" } ], "match": { "field": "company_domain", "overwrite": "fill_empty" } } ], "properties": { "csv": { "description": "UTF-8 CSV text with a header row, quoted as in RFC 4180. The delimiter is detected: comma, semicolon, tab, pipe or a `sep=` first line. Up to 1,000 data rows and 256 columns.", "examples": [ "Company domain,Lead stage\r\nledgerline.com,Meeting booked\r\n" ], "minLength": 1, "type": "string" }, "mappings": { "description": "One mapping per column, in header order. Omit to use the proposed mapping.", "items": { "$ref": "#/components/schemas/CsvMappingRequest" }, "maxItems": 256, "type": "array" }, "match": { "additionalProperties": false, "description": "How rows match existing records.", "properties": { "field": { "description": "The field rows match on: an id or key.", "examples": [ "company_domain" ], "type": "string" }, "overwrite": { "default": "supplied_cells", "description": "How a matched record changes: `supplied_cells` writes every value sent, `fill_empty` fills only empty fields.", "enum": [ "supplied_cells", "fill_empty" ] } }, "required": [ "field" ], "type": "object" } }, "required": [ "csv" ], "type": "object" }, "CsvImportRequest": { "additionalProperties": false, "examples": [ { "csv": "Company domain,Deal stage,Notes\r\nledgerline.com,Meeting booked,Asked for pricing\r\n", "mappings": [ { "field": "company_domain", "kind": "existing" }, { "key": "deal_stage", "kind": "create", "name": "Deal stage", "type": "text" }, { "kind": "skip" } ] } ], "properties": { "csv": { "description": "The same CSV text you previewed.", "examples": [ "Company domain,Lead stage\r\nledgerline.com,Meeting booked\r\n" ], "minLength": 1, "type": "string" }, "dry_run": { "default": false, "description": "Return 200 with the same answer as Preview a CSV import, without writing fields, records or history.", "example": true, "type": "boolean" }, "mappings": { "description": "One per column, in header order. Omitted: the proposed mapping.", "items": { "$ref": "#/components/schemas/CsvMappingRequest" }, "maxItems": 256, "type": "array" }, "match": { "additionalProperties": false, "description": "How rows match existing records. Every column must map to an existing field or be skipped. Import a CSV only: Start a CSV import refuses it.", "properties": { "field": { "description": "The field rows match on: an id or key.", "examples": [ "company_domain" ], "type": "string" }, "overwrite": { "default": "supplied_cells", "description": "How a matched record changes: `supplied_cells` writes every value sent, `fill_empty` fills only empty fields.", "enum": [ "supplied_cells", "fill_empty" ] } }, "required": [ "field" ], "type": "object" }, "preview_token": { "deprecated": true, "description": "Deprecated: use `dry_run`. Optional confirmation from a previous preview; a token for a changed file, mapping or schema is refused.", "example": "csvpreview_4b3eb6b438967240aad5093ddd5c4153b80a2e9dba54d0d5841dd3ef7d143aea", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "type": "string" } }, "required": [ "csv" ], "type": "object" }, "CsvImportResult": { "oneOf": [ { "$ref": "#/components/schemas/CsvImportResultAppend" }, { "$ref": "#/components/schemas/RecordsMutation" } ] }, "CsvImportResultAppend": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "duplicates_removed": { "description": "Rows the table's dedupe setting dropped or replaced.", "examples": [ 4 ], "type": "integer" }, "fields_added": { "description": "Fields added.", "examples": [ 2 ], "type": "integer" }, "records_added": { "description": "Records added.", "examples": [ 980 ], "type": "integer" }, "rows_added": { "deprecated": true, "description": "Deprecated: use `records_added`, which holds the same number.", "examples": [ 980 ], "type": "integer", "x-sunset": "2027-02-01" }, "values_emptied": { "description": "Values that did not fit their field and were left empty.", "examples": [ 3 ], "type": "integer" } }, "required": [ "rows_added", "fields_added", "values_emptied", "records_added" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "CsvMapping": { "oneOf": [ { "properties": { "kind": { "const": "skip", "description": "What to do with the column: skip it, put it in an existing field, or create a field." } }, "required": [ "kind" ], "type": "object" }, { "properties": { "field_id": { "description": "The existing field the column fills.", "examples": [ "fld_b00a97266f03cceb43636653c0e40b38" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "kind": { "const": "existing", "description": "What to do with the column: skip it, put it in an existing field, or create a field." } }, "required": [ "kind", "field_id" ], "type": "object" }, { "description": "Create a validated data field; Formula and Enrichment types are refused by CSV import.", "properties": { "config": { "$ref": "#/components/schemas/FieldConfig", "description": "With a `type` named as a string, the field's settings, as Create a field takes them; the older `{type: options}` form takes none." }, "key": { "description": "The new field's key: letters, digits and underscores.", "examples": [ "company_domain" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "kind": { "const": "create", "description": "What to do with the column: skip it, put it in an existing field, or create a field." }, "label": { "deprecated": true, "description": "Deprecated: use `name`. The new field's name; send one of the two.", "examples": [ "Company domain" ], "minLength": 1, "type": "string", "x-sunset": "2027-02-01" }, "name": { "description": "The new field's name.", "examples": [ "Company domain" ], "minLength": 1, "type": "string" }, "type": { "$ref": "#/components/schemas/CsvDataFieldType", "description": "The new field's type." } }, "required": [ "kind", "key", "name", "type" ], "type": "object" } ], "properties": { "kind": { "description": "What to do with the column: skip it, put it in an existing field, or create a field.", "enum": [ "skip", "existing", "create" ], "type": "string" } } }, "CsvMappingRequest": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "skip", "description": "What to do with the column: skip it, put it in an existing field, or create a field." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "description": "Fill an existing field, named by `field` (its key or id). The older `field_id` is still accepted; sending both with different values is refused.", "properties": { "field": { "description": "The existing field the column fills: its key or its id.", "examples": [ "company_domain" ], "maxLength": 64, "minLength": 1, "type": "string" }, "field_id": { "deprecated": true, "description": "Deprecated: use `field`. The existing field's id.", "examples": [ "fld_b00a97266f03cceb43636653c0e40b38" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string", "x-sunset": "2027-02-01" }, "kind": { "const": "existing", "description": "What to do with the column: skip it, put it in an existing field, or create a field." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "description": "Create a validated data field; Formula and Enrichment types are refused by CSV import.", "properties": { "config": { "$ref": "#/components/schemas/FieldConfig", "description": "With a `type` named as a string, the field's settings, as Create a field takes them; the older `{type: options}` form takes none." }, "key": { "description": "The new field's key: letters, digits and underscores.", "examples": [ "company_domain" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "kind": { "const": "create", "description": "What to do with the column: skip it, put it in an existing field, or create a field." }, "label": { "deprecated": true, "description": "Deprecated: use `name`. The new field's name; send one of the two.", "examples": [ "Company domain" ], "minLength": 1, "type": "string", "x-sunset": "2027-02-01" }, "name": { "description": "The new field's name.", "examples": [ "Company domain" ], "minLength": 1, "type": "string" }, "type": { "$ref": "#/components/schemas/CsvDataFieldType", "description": "The new field's type." } }, "required": [ "kind", "key", "name", "type" ], "type": "object" } ], "properties": { "kind": { "description": "What to do with the column: skip it, put it in an existing field, or create a field.", "enum": [ "skip", "existing", "create" ], "type": "string" } } }, "DateDisplay": { "description": "How a date field shows its value. Turning the time on never rewrites a value; turning it off is a conversion.", "properties": { "clock": { "description": "A `12h` or `24h` clock.", "enum": [ "12h", "24h" ], "type": "string" }, "include_time": { "description": "The field holds a time as well as a day.", "examples": [ false ], "type": "boolean" }, "style": { "description": "How the day is written; left out: ISO (`2026-07-06`).", "enum": [ "local", "friendly", "us", "european", "iso", "weekday", "weekday_short" ], "type": "string" }, "time_zone": { "description": "IANA time zone a time shows in; left out: the workspace's.", "examples": [ "Europe/Madrid" ], "maxLength": 64, "type": "string" } }, "type": "object" }, "DateOptions": { "additionalProperties": false, "properties": { "clock_24h": { "description": "Show times on a 24-hour clock.", "examples": [ true ], "type": "boolean" }, "format": { "description": "How a date is shown: `local`, `friendly`, `us`, `european`, `iso`, `weekday` or `weekday_short`.", "enum": [ "local", "friendly", "us", "european", "iso", "weekday", "weekday_short", null ] }, "include_time": { "description": "Show the time as well as the date.", "examples": [ false ], "type": "boolean" }, "time_zone": { "anyOf": [ { "description": "An IANA time-zone name; absent means UTC.", "type": "string" }, { "type": "null" } ], "description": "An IANA time zone, or null for UTC.", "examples": [ "Europe/Madrid" ] } }, "required": [], "type": "object" }, "DeleteMutation": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "deleted": { "const": true, "description": "Whether the object was deleted." }, "id": { "description": "The id of the deleted object.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "EmptyObject": { "additionalProperties": false, "description": "An empty JSON object.", "properties": {}, "type": "object" }, "EnrichmentCredentialBinding": { "additionalProperties": false, "properties": { "credential_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The workspace key to run with, or null to use the default.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ] }, "credential_source": { "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. Which key the field runs with: `managed` (Appenda's key, spends credits) or `byok` (one of the workspace's own keys).", "enum": [ "managed", "byok" ], "type": "string" } }, "required": [ "credential_source" ], "type": "object" }, "EnrichmentFieldConfig": { "description": "Enrichment configuration and safe credential reference; secret values are never returned.", "properties": { "action": { "description": "The action's id.", "examples": [ "email_finder" ], "type": "string" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workspace key the field runs with, or null for the default. Never the secret.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ] }, "credential_source": { "anyOf": [ { "enum": [ "managed", "byok" ], "type": "string" }, { "type": "null" } ], "description": "Which key the field runs with: `managed` (Appenda's key) or `byok` (the workspace's own key); null for the default." }, "first_n": { "description": "Run only the first N rows.", "examples": [ 100 ], "minimum": 1, "type": "integer" }, "inputs": { "additionalProperties": { "description": "A source field id, or {\"field_id\",\"json_path\"} to read inside a JSON cell.", "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "description": "The action's inputs, each one of this table's fields, a fixed `value` or a `template`.", "examples": [ { "domain": "fld_b00a97266f03cceb43636653c0e40b38", "first_name": "fld_3b9ed9139c16536a8e36fd6279b1a510", "last_name": "fld_4ad93454e0feed19f81e719c13744619" } ], "type": "object" }, "method_id": { "deprecated": true, "description": "Deprecated: use `action`, which holds the same value.", "examples": [ "email_finder" ], "type": "string", "x-sunset": "2027-02-01" }, "output": { "description": "A JSON pointer into the answer the field shows; `/` is the whole answer.", "examples": [ "/email" ], "type": "string" }, "output_path": { "description": "Which part of the action's result the field keeps.", "examples": [ "/email" ], "type": "string" }, "provider": { "description": "The integration's id.", "examples": [ "leadmagic" ], "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, which holds the same value.", "examples": [ "leadmagic" ], "type": "string", "x-sunset": "2027-02-01" }, "run_condition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A true-or-false formula over this table's fields; rows it rejects are skipped and not charged.", "examples": [ "{fld_b00a97266f03cceb43636653c0e40b38} != \"\"" ] }, "run_when": { "anyOf": [ { "properties": { "match": { "description": "Whether every rule (`all`) or one rule (`any`) must hold.", "enum": [ "all", "any" ], "examples": [ "all" ], "type": "string" }, "rules": { "description": "The conditions, with the same operators as a view filter.", "examples": [ [ { "field": "work_email", "operator": "is_empty" } ] ], "items": { "properties": { "field": { "description": "The key of the field the rule reads.", "examples": [ "work_email" ], "type": "string" }, "operator": { "description": "How the field is compared, as in a view filter.", "examples": [ "is_empty" ], "type": "string" }, "path": { "description": "A dotted path inside a JSON field.", "examples": [ "company.domain" ], "type": "string" }, "value": { "description": "The value to compare with; left out for `is_empty`, `is_not_empty`, `is_true` and `is_false`.", "examples": [ "Northbeam" ] } }, "required": [ "field", "operator" ], "type": "object" }, "maxItems": 20, "type": "array" } }, "required": [ "match", "rules" ], "type": "object" }, { "description": "A stored condition the rules cannot state, with `{field_key}` references. Sent back unchanged, it keeps the condition.", "properties": { "formula": { "description": "The condition as a formula over field keys.", "examples": [ "AND(NOT(ISBLANK({work_email})), {score} > 50)" ], "maxLength": 4096, "type": "string" } }, "required": [ "formula" ], "type": "object" } ], "description": "When the field runs for a record, as Create an enrichment field takes it; left out when it runs for every record. A stored condition the rules cannot state reads as `{\"formula\": …}`.", "examples": [ { "match": "all", "rules": [ { "field": "work_email", "operator": "is_empty" } ] } ] } }, "required": [ "provider_id", "method_id", "inputs", "output_path" ], "type": "object" }, "EnrichmentFieldCreate": { "additionalProperties": false, "description": "An enrichment field built from an action's parameters (Get action parameters). Inputs are keyed by the action's input keys and name fields by key. Nothing runs or is charged until a run starts. HTTP request fields cannot be created with an API key yet.", "properties": { "action": { "description": "The action's id, from List integration actions.", "examples": [ "email_finder" ], "maxLength": 128, "minLength": 1, "type": "string" }, "credential_id": { "description": "One of the workspace's own keys for the provider; its default key when left out. A built-in provider takes none (credential_not_applicable).", "examples": [ "cred_971e3efd6924ee8db473896da8f1c630" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "dry_run": { "description": "Check the field and answer it without creating anything. Defaults to false.", "examples": [ false ], "type": "boolean" }, "inputs": { "additionalProperties": { "description": "Where an input's value comes from on each record: a field by key (optionally a `path` inside a JSON field), a fixed `value`, or a `template` with `{field_key}` slots.", "examples": [ { "field": "work_email" } ], "oneOf": [ { "additionalProperties": false, "properties": { "field": { "description": "The key of the field to read.", "examples": [ "work_email" ], "type": "string" }, "path": { "description": "A JSON pointer inside a JSON field.", "examples": [ "/emails/0" ], "type": "string" } }, "required": [ "field" ], "type": "object" }, { "additionalProperties": false, "properties": { "value": { "description": "The same value on every record.", "examples": [ "gpt-5-mini" ] } }, "required": [ "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "template": { "description": "Text with `{field_key}` slots filled from the record.", "examples": [ "Find the CEO of {company_name}" ], "type": "string" } }, "required": [ "template" ], "type": "object" } ] }, "description": "Each action input's value, keyed by input key.", "examples": [ { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "last_name": { "field": "last_name" } } ], "maxProperties": 64, "type": "object" }, "name": { "description": "The field's name; its key is read from it.", "examples": [ "Work email" ], "maxLength": 80, "minLength": 1, "type": "string" }, "output": { "description": "A JSON pointer into the answer the field shows; the whole answer when left out.", "examples": [ "/email" ], "type": "string" }, "provider": { "description": "The integration's id.", "examples": [ "leadmagic" ], "maxLength": 128, "minLength": 1, "type": "string" }, "run_when": { "additionalProperties": false, "description": "When the field runs for a record: rules over the record's fields by key, all or any of them. Every record when left out.", "examples": [ { "match": "all", "rules": [ { "field": "work_email", "operator": "is_empty" } ] } ], "properties": { "match": { "description": "Whether every rule (`all`) or one rule (`any`) must hold.", "enum": [ "all", "any" ], "examples": [ "all" ], "type": "string" }, "rules": { "description": "The conditions, with the same operators as a view filter.", "examples": [ [ { "field": "work_email", "operator": "is_empty" } ] ], "items": { "additionalProperties": false, "properties": { "field": { "description": "The key of the field the rule reads.", "examples": [ "work_email" ], "type": "string" }, "operator": { "description": "How the field is compared, as in a view filter.", "examples": [ "is_empty" ], "type": "string" }, "path": { "description": "A dotted path inside a JSON field.", "examples": [ "company.domain" ], "type": "string" }, "value": { "description": "The value to compare with; left out for `is_empty`, `is_not_empty`, `is_true` and `is_false`.", "examples": [ "Northbeam" ] } }, "required": [ "field", "operator" ], "type": "object" }, "maxItems": 20, "type": "array" } }, "required": [ "match", "rules" ], "type": "object" }, "schema_version": { "description": "The `schema_version` of the action parameters the inputs were built from. A version with breaking changes since is refused with the changes listed.", "examples": [ 2 ], "minimum": 1, "type": "integer" } }, "required": [ "name", "provider", "action", "schema_version", "inputs" ], "type": "object" }, "EnrichmentFieldWrite": { "additionalProperties": false, "description": "Change an enrichment field: every property is optional, and one left out keeps its value. Inputs sent replace those inputs only, unless the provider or action changes, which needs the full `inputs`. Nothing runs or is charged until a run starts. HTTP request fields cannot be created with an API key yet.", "examples": [ { "action": "email_finder", "inputs": { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "last_name": { "field": "last_name" } }, "name": "Work email", "provider": "leadmagic", "schema_version": 2 } ], "properties": { "action": { "description": "The action's id, from List integration actions.", "examples": [ "email_finder" ], "maxLength": 128, "minLength": 1, "type": "string" }, "credential_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "A key this workspace holds for the provider. Omit to use the workspace's default key at run time.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ] }, "credential_source": { "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. Which key the field runs with: `managed` (Appenda's key, spends credits) or `byok` (one of the workspace's own keys).", "enum": [ "managed", "byok" ], "type": "string" }, "first_n": { "deprecated": true, "description": "Deprecated: ignored by Start a run, whose `options.mode` decides. The row count the desktop app and agents use when a run names none.", "examples": [ 100 ], "minimum": 1, "type": "integer" }, "inputs": { "additionalProperties": { "anyOf": [ { "description": "Where an input's value comes from on each record: a field by key (optionally a `path` inside a JSON field), a fixed `value`, or a `template` with `{field_key}` slots.", "examples": [ { "field": "work_email" } ], "oneOf": [ { "additionalProperties": false, "properties": { "field": { "description": "The key of the field to read.", "examples": [ "work_email" ], "type": "string" }, "path": { "description": "A JSON pointer inside a JSON field.", "examples": [ "/emails/0" ], "type": "string" } }, "required": [ "field" ], "type": "object" }, { "additionalProperties": false, "properties": { "value": { "description": "The same value on every record.", "examples": [ "gpt-5-mini" ] } }, "required": [ "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "template": { "description": "Text with `{field_key}` slots filled from the record.", "examples": [ "Find the CEO of {company_name}" ], "type": "string" } }, "required": [ "template" ], "type": "object" } ] }, { "description": "Deprecated: a field id. Use `{\"field\": \"\"}`.", "examples": [ "fld_b00a97266f03cceb43636653c0e40b38" ], "type": "string" }, { "description": "Deprecated: `{\"field_id\", \"json_path\"}`. Use `{\"field\", \"path\"}`.", "type": "object" } ], "description": "An input as Create an enrichment field writes it: a field by key, a fixed `value` or a `template`. A field id is still accepted.", "examples": [ { "field": "work_email" } ] }, "description": "The action's inputs, each one of this table's fields, a fixed `value` or a `template`.", "examples": [ { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "last_name": { "field": "last_name" } } ], "maxProperties": 64, "type": "object" }, "key": { "description": "The field's key: letters, digits and underscores. Required on create; refused on update.", "examples": [ "work_email" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "label": { "deprecated": true, "description": "Deprecated: use `name`. The field's new name.", "examples": [ "Work email" ], "maxLength": 80, "minLength": 1, "type": "string" }, "method_id": { "deprecated": true, "description": "Deprecated: use `action`. The action's id.", "examples": [ "email_finder" ], "maxLength": 128, "type": "string" }, "name": { "description": "The field's new name. Its key does not change.", "examples": [ "Work email" ], "maxLength": 80, "minLength": 1, "type": "string" }, "output": { "description": "A JSON pointer into the answer the field shows; the whole answer when left out.", "examples": [ "/email" ], "type": "string" }, "output_path": { "deprecated": true, "description": "Deprecated: use `output`. Which part of the action's result the field keeps.", "examples": [ "/email" ], "minLength": 1, "type": "string" }, "provider": { "description": "The integration's id.", "examples": [ "leadmagic" ], "maxLength": 128, "minLength": 1, "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`. The integration's id.", "examples": [ "appenda" ], "maxLength": 128, "minLength": 1, "not": { "const": "custom_http" }, "type": "string" }, "run_condition": { "deprecated": true, "description": "Deprecated: use `run_when`. A boolean formula over this table's field ids; rows it rejects are skipped and not charged.", "examples": [ "{fld_b00a97266f03cceb43636653c0e40b38} != \"\"" ], "maxLength": 4096, "minLength": 1, "type": "string" }, "run_when": { "anyOf": [ { "additionalProperties": false, "properties": { "match": { "description": "Whether every rule (`all`) or one rule (`any`) must hold.", "enum": [ "all", "any" ], "examples": [ "all" ], "type": "string" }, "rules": { "description": "The conditions, with the same operators as a view filter.", "examples": [ [ { "field": "work_email", "operator": "is_empty" } ] ], "items": { "additionalProperties": false, "properties": { "field": { "description": "The key of the field the rule reads.", "examples": [ "work_email" ], "type": "string" }, "operator": { "description": "How the field is compared, as in a view filter.", "examples": [ "is_empty" ], "type": "string" }, "path": { "description": "A dotted path inside a JSON field.", "examples": [ "company.domain" ], "type": "string" }, "value": { "description": "The value to compare with; left out for `is_empty`, `is_not_empty`, `is_true` and `is_false`.", "examples": [ "Northbeam" ] } }, "required": [ "field", "operator" ], "type": "object" }, "maxItems": 20, "type": "array" } }, "required": [ "match", "rules" ], "type": "object" }, { "additionalProperties": false, "description": "A stored condition the rules cannot state, with `{field_key}` references. Sent back unchanged, it keeps the condition.", "properties": { "formula": { "description": "The condition as a formula over field keys.", "examples": [ "AND(NOT(ISBLANK({work_email})), {score} > 50)" ], "maxLength": 4096, "type": "string" } }, "required": [ "formula" ], "type": "object" } ], "description": "When the field runs for a record: rules over the record's fields by key, all or any of them. Every record when left out.", "examples": [ { "match": "all", "rules": [ { "field": "work_email", "operator": "is_empty" } ] } ] }, "schema_version": { "description": "The `schema_version` of the action parameters the inputs were built from. A version with breaking changes since is refused with the changes listed.", "examples": [ 2 ], "minimum": 1, "type": "integer" } }, "type": "object" }, "Field": { "examples": [ { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" } ], "properties": { "config": { "$ref": "#/components/schemas/FieldConfig", "description": "The type's settings: a number's or date's `format`, a select's `choices`, a formula's `expressions`, a lookup's path, an enrichment's `provider`, `action` and `inputs`, a waterfall's `steps`." }, "id": { "description": "The field's id.", "examples": [ "fld_b00a97266f03cceb43636653c0e40b38" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "key": { "description": "The field's stable key: letters, digits and underscores. Records, formulas and filters name the field by it.", "examples": [ "lead_score" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "name": { "description": "The field's name.", "examples": [ "Lead score" ], "maxLength": 80, "minLength": 1, "type": "string" }, "object": { "const": "field", "description": "Always `field`." }, "position": { "description": "The field's place in the table, left to right.", "examples": [ 7 ], "minimum": 0, "type": "integer" }, "read_only": { "description": "Whether values are computed or fetched (formula, lookup, enrichment) rather than written.", "type": "boolean" }, "samples": { "description": "Only on a formula or lookup dry run: what it computes on the table's first records.", "examples": [ [ { "record_id": "rec_f780069b0c95896f9fb6b5f51ffa5d8b", "value": "northbeam.io", "winning": 1 } ] ], "items": { "properties": { "record_id": { "description": "The record.", "examples": [ "rec_f780069b0c95896f9fb6b5f51ffa5d8b" ], "type": "string" }, "value": { "description": "The value computed, as the API shows the field's values; `null` when blank.", "examples": [ "northbeam.io" ] }, "winning": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Which of `expressions` gave the value (0-based); `null` when none did or the formula is not stacked.", "examples": [ 1 ] } }, "required": [ "record_id", "winning", "value" ], "type": "object" }, "maxItems": 5, "type": "array" }, "type": { "description": "The field's type. New types may be added; treat an unknown one as read-only.", "enum": [ "text", "number", "boolean", "date", "json", "url", "email", "phone", "single_select", "multi_select", "formula", "lookup", "enrichment", "waterfall" ], "type": "string" }, "updated_at": { "description": "When the field last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "object", "id", "key", "name", "type", "config", "position", "read_only", "updated_at" ], "type": "object" }, "FieldChoice": { "description": "One choice of a select field.", "properties": { "color": { "description": "The choice's color; left out: `blue`.", "enum": [ "blue", "cyan", "teal", "green", "yellow", "orange", "red", "pink", "purple", "gray" ], "type": "string" }, "id": { "description": "The choice's id. Leave it out for a new choice; keep it to keep the choice's values.", "examples": [ "choice_c376ae596decf98b88afd886d1777cb2" ], "maxLength": 64, "type": "string" }, "name": { "description": "The choice's name. Values are written and read by it.", "examples": [ "Meeting booked" ], "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "FieldConfig": { "description": "The settings of the field's `type`. Number: `format`. Date: `format`. URL: the clean-up switches. Single and multi select: `choices`. Formula: `expressions`, `result_type`, `output_format`. Lookup: `source_field`, `path`, `array`, `result_type`, `when_empty`. Other types take `{}`.", "properties": { "add_scheme": { "description": "URL: prefix `https://` when a value has no scheme.", "examples": [ true ], "type": "boolean" }, "array": { "description": "How a lookup reads an array: `first` (the default) reads the first item, `join` every item's text separated by `, `, `count` how many items hold a value.", "enum": [ "first", "join", "count" ], "type": "string" }, "choices": { "description": "A select field's choices, in display order.", "items": { "$ref": "#/components/schemas/FieldChoice" }, "maxItems": 100, "type": "array" }, "domain_only": { "description": "URL: keep only the registrable domain.", "examples": [ false ], "type": "boolean" }, "expressions": { "description": "A formula's expressions in priority order; the first non-empty result wins. Fields are named `{field_key}`.", "examples": [ [ "{work_email_score}", "{fallback_score}" ] ], "items": { "maxLength": 4096, "type": "string" }, "maxItems": 8, "minItems": 1, "type": "array" }, "format": { "description": "How a number or date field shows its value.", "oneOf": [ { "$ref": "#/components/schemas/NumberDisplay" }, { "$ref": "#/components/schemas/DateDisplay" } ] }, "linkedin_canonical": { "description": "URL: make professional network profile and company links canonical.", "examples": [ true ], "type": "boolean" }, "output_format": { "description": "How a formula shows its result: `{\"number\": {…}}` or `{\"date\": {…}}`.", "properties": { "date": { "$ref": "#/components/schemas/DateDisplay", "description": "How a date result is shown." }, "number": { "$ref": "#/components/schemas/NumberDisplay", "description": "How a number result is shown." } }, "type": "object" }, "path": { "description": "The dotted path a lookup reads; `*` (or an index) is an array item.", "examples": [ "company.domain" ], "maxLength": 512, "type": "string" }, "references": { "description": "The keys of the fields a formula reads. Returned, never accepted.", "examples": [ [ "fallback_score", "work_email_score" ] ], "items": { "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "readOnly": true, "type": "array" }, "result_type": { "description": "What a formula or lookup returns.", "enum": [ "text", "number", "boolean" ], "type": "string" }, "source_field": { "description": "The key of the JSON field a lookup reads.", "examples": [ "company_profile" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "strip_query": { "description": "URL: drop the query string and fragment.", "examples": [ true ], "type": "boolean" }, "strip_scheme": { "description": "URL: drop the scheme.", "examples": [ false ], "type": "boolean" }, "strip_trailing_slash": { "description": "URL: drop a trailing slash.", "examples": [ true ], "type": "boolean" }, "strip_www": { "description": "URL: drop a leading `www.`.", "examples": [ true ], "type": "boolean" }, "when_empty": { "description": "What a lookup shows when the path holds nothing.", "examples": [ "Unknown" ], "type": [ "string", "number" ] } }, "type": "object" }, "FieldConversion": { "description": "What a field change would do to its values.", "examples": [ { "blank": 15, "converted": 182, "dry_run": true, "emptied": 3, "object": "field_conversion", "samples": [ { "after": null, "before": "N/A", "emptied": true, "record_id": "rec_bb0132c0d0082fd355c21f84a92fc712" }, { "after": 1250, "before": "1,250", "emptied": false, "record_id": "rec_c45e244f8f025a2b60165fc5b391a5d0" } ] } ], "properties": { "blank": { "description": "Values that are blank and stay blank.", "examples": [ 15 ], "minimum": 0, "type": "integer" }, "converted": { "description": "Values that convert to the new type.", "examples": [ 182 ], "minimum": 0, "type": "integer" }, "dry_run": { "const": true, "description": "Always `true`: nothing was changed." }, "emptied": { "description": "Values that don't fit the new type and would be emptied.", "examples": [ 3 ], "minimum": 0, "type": "integer" }, "object": { "const": "field_conversion", "description": "Always `field_conversion`." }, "samples": { "description": "Up to five records, emptied ones first.", "items": { "properties": { "after": { "description": "The value after the change, or `null`.", "examples": [ null ] }, "before": { "description": "The value now, as the API returns it.", "examples": [ "N/A" ] }, "emptied": { "description": "Whether the change empties this value.", "type": "boolean" }, "record_id": { "description": "The record's id.", "examples": [ "rec_bb0132c0d0082fd355c21f84a92fc712" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "record_id", "before", "after", "emptied" ], "type": "object" }, "maxItems": 5, "type": "array" } }, "required": [ "object", "dry_run", "converted", "emptied", "blank", "samples" ], "type": "object" }, "FieldCreate": { "additionalProperties": false, "examples": [ { "config": { "format": { "currency": "USD", "decimals": 2, "style": "currency" } }, "key": "arr", "name": "ARR", "type": "number" } ], "properties": { "config": { "$ref": "#/components/schemas/FieldConfig", "description": "The settings of the field's type; left out: the type's defaults." }, "dry_run": { "description": "Check the field (its type, config and formula) and return it without creating it; a formula or lookup also returns `samples`, what it computes on the first five records. Default `false`.", "type": "boolean" }, "key": { "description": "The field's key: letters, digits and underscores, unique in the table.", "examples": [ "company_domain" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "name": { "description": "The field's name.", "examples": [ "Company domain" ], "maxLength": 80, "minLength": 1, "type": "string" }, "position": { "description": "Where the field goes; left out: after the last field.", "examples": [ 3 ], "minimum": 0, "type": "integer" }, "type": { "description": "The field's type. Enrichment fields have their own create operation.", "enum": [ "text", "number", "boolean", "date", "json", "url", "email", "phone", "single_select", "multi_select", "formula", "lookup" ], "type": "string" } }, "required": [ "key", "name", "type" ], "type": "object" }, "FieldMutation": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "oneOf": [ { "$ref": "#/components/schemas/Field" }, { "$ref": "#/components/schemas/FieldConversion" } ] } }, "required": [ "data" ], "type": "object" }, "FieldOutput": { "description": "One path the field's values hold, from a sample of the table's first records.", "properties": { "coverage": { "description": "The share of sampled records that hold the path.", "examples": [ 0.96 ], "maximum": 1, "minimum": 0, "type": "number" }, "declared": { "description": "Whether the field's provider action declares this output.", "examples": [ true ], "type": "boolean" }, "example": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One value seen at the path, shortened to 48 characters; null for objects and arrays.", "examples": [ "northbeam.io" ] }, "field_id": { "description": "The field the path is read from.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "object": { "description": "Always `field_output`.", "enum": [ "field_output" ], "examples": [ "field_output" ], "type": "string" }, "path": { "description": "The dotted path: keys joined by `.`, array items written `*` (`experience.*.title`). A literal dot in a key is written `\\.`.", "examples": [ "company.domain" ], "type": "string" }, "type": { "description": "The value's JSON type across the sample; `mixed` when it varies. New types may be added.", "enum": [ "object", "array", "text", "number", "boolean", "null", "mixed" ], "examples": [ "text" ], "type": "string" } }, "required": [ "object", "path", "type", "coverage", "example", "declared", "field_id" ], "type": "object" }, "FieldOutputPage": { "description": "The field's outputs, most covered first, in one page.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/FieldOutput" }, "maxItems": 100, "type": "array" }, "meta": { "description": "About the sample the outputs come from.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "The cursor to the next page; null on the last page.", "examples": [ null ] }, "sampled_records": { "description": "Records sampled: up to 50 of the records that hold a value in the field, spread evenly over the table.", "examples": [ 50 ], "maximum": 50, "minimum": 0, "type": "integer" } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "FieldPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/Field" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "FieldResponse": { "properties": { "data": { "$ref": "#/components/schemas/Field", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "FieldUpdate": { "additionalProperties": false, "examples": [ { "convert": true, "dry_run": true, "type": "number" } ], "properties": { "config": { "$ref": "#/components/schemas/FieldConfig", "description": "New settings for the field's type. A new `format` changes only how values show." }, "convert": { "description": "Confirm a change that rewrites values: each value is read as text and parsed as the new type; a value that doesn't fit is emptied. Default `false`.", "type": "boolean" }, "dry_run": { "description": "Change nothing and report what the change would do: a type change, what it would convert and empty, with samples; a formula or lookup, the field with `samples` of what it computes. Default `false`.", "type": "boolean" }, "name": { "description": "A new name for the field.", "examples": [ "Company website" ], "maxLength": 80, "minLength": 1, "type": "string" }, "type": { "description": "A new type. A change that rewrites values needs `convert: true`.", "enum": [ "text", "number", "boolean", "date", "json", "url", "email", "phone", "single_select", "multi_select", "formula", "lookup" ], "type": "string" } }, "type": "object" }, "FilterCondition": { "additionalProperties": false, "properties": { "field_id": { "description": "The field.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "maxLength": 64, "minLength": 1, "type": "string" }, "json_path": { "anyOf": [ { "description": "RFC 6901 pointer required for Json fields and refused for other field types.", "type": "string" }, { "type": "null" } ], "description": "A pointer into a JSON field's value, such as `/company/size`; null for other fields.", "examples": [ "/company/size" ] }, "operator": { "description": "How the field is compared with the value.", "enum": [ "is_empty", "is_not_empty", "is", "is_not", "contains", "does_not_contain", "starts_with", "ends_with", "domain_is", "is_any_of", "is_none_of", "eq", "ne", "lt", "lte", "gt", "gte", "is_true", "is_false", "before", "after", "on_or_before", "on_or_after", "between", "has_any_of", "has_all_of", "has_none_of", "is_exactly", "found_by" ] }, "value": { "$ref": "#/components/schemas/FilterValue", "description": "The value the field is compared with." } }, "required": [ "field_id", "operator", "value" ], "type": "object" }, "FilterGroup": { "additionalProperties": false, "properties": { "combinator": { "description": "How the conditions join: `and` keeps records matching all, `or` any.", "enum": [ "and", "or" ] }, "groups": { "description": "Nested groups combined with items by this group's combinator; three levels deep at most, 20 conditions across the tree, none empty.", "example": [ { "combinator": "or", "items": [ { "fieldId": "fld_stage", "operator": "is", "value": { "kind": "text", "value": "won" } }, { "fieldId": "fld_stage", "operator": "is", "value": { "kind": "text", "value": "qualified" } } ] } ], "items": { "$ref": "#/components/schemas/FilterGroup" }, "type": "array" }, "items": { "description": "The conditions.", "items": { "$ref": "#/components/schemas/FilterCondition" }, "maxItems": 20, "type": "array" } }, "required": [ "combinator", "items" ], "type": "object" }, "FilterSpec": { "additionalProperties": false, "description": "A filter over a table's live fields: a group of conditions joined by `and` or `or`. Operators and values must suit each field's type.", "examples": [ { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } } ], "properties": { "root": { "$ref": "#/components/schemas/FilterGroup", "description": "The top group of conditions." } }, "required": [ "root" ], "type": "object" }, "FilterValue": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "text", "description": "The kind of value the condition compares with." }, "value": { "description": "The value to compare with.", "examples": [ "Meeting booked" ], "maxLength": 1024, "type": "string" } }, "required": [ "kind", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "number", "description": "The kind of value the condition compares with." }, "value": { "description": "The value to compare with.", "examples": [ "Meeting booked" ], "type": "number" } }, "required": [ "kind", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "boolean", "description": "The kind of value the condition compares with." }, "value": { "description": "The value to compare with.", "examples": [ "Meeting booked" ], "type": "boolean" } }, "required": [ "kind", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "text_list", "description": "The kind of value the condition compares with." }, "values": { "description": "The values to compare with.", "examples": [ [ "Contacted", "Meeting booked" ] ], "items": { "description": "At most 1,024 UTF-8 bytes; field-specific operator compatibility is checked against the live table.", "maxLength": 1024, "type": "string" }, "maxItems": 50, "type": "array" } }, "required": [ "kind", "values" ], "type": "object" }, { "additionalProperties": false, "properties": { "end": { "description": "The last day, `YYYY-MM-DD`.", "examples": [ "2026-10-31" ], "type": "number" }, "kind": { "const": "number_range", "description": "The kind of value the condition compares with." }, "start": { "description": "The first day, `YYYY-MM-DD`.", "examples": [ "2026-10-01" ], "type": "number" } }, "required": [ "kind", "start", "end" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "number_list", "description": "The kind of value the condition compares with." }, "values": { "description": "The values to compare with.", "examples": [ [ "Contacted", "Meeting booked" ] ], "items": { "type": "number" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "kind", "values" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "none", "description": "The kind of value the condition compares with." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "date", "description": "The kind of value the condition compares with." }, "value": { "description": "The value to compare with.", "examples": [ "Meeting booked" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } }, "required": [ "kind", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "end": { "description": "The last day, `YYYY-MM-DD`.", "examples": [ "2026-10-31" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "kind": { "const": "date_range", "description": "The kind of value the condition compares with." }, "start": { "description": "The first day, `YYYY-MM-DD`.", "examples": [ "2026-10-01" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } }, "required": [ "kind", "start", "end" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "relative_date", "description": "The kind of value the condition compares with." }, "value": { "description": "The value to compare with.", "examples": [ "Meeting booked" ], "type": "string" } }, "required": [ "kind", "value" ], "type": "object" } ] }, "ForkRequest": { "additionalProperties": false, "description": "`rows`: `all`, `view` (the rows the view named by `view_id` showed at that version) or `none`. Nothing runs on the fork.", "properties": { "name": { "description": "The new table's name.", "examples": [ "Series B SaaS accounts (October)" ], "maxLength": 200, "minLength": 1, "type": "string" }, "rows": { "description": "Which records the new table gets: `all`, `view` (those the view named by `view_id` showed then) or `none`.", "enum": [ "all", "view", "none" ], "type": "string" }, "view_id": { "description": "With `rows: view`, the view whose records the new table gets.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "rows" ], "type": "object" }, "ForkResult": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "created_at": { "description": "When the new table was created.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "forked_from": { "description": "The table and version this table was forked from.", "properties": { "table_id": { "description": "The table it was forked from.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "version_id": { "description": "The version it was forked from.", "examples": [ "ver_commit_d42e4a6b3b74003ed5031158a1847494" ], "type": "string" } }, "required": [ "table_id", "version_id" ], "type": "object" }, "id": { "description": "The new table's id.", "examples": [ "tbl_c9b4f80d3721cb7401bb23ae8643e40c" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "name": { "description": "The new table's name.", "examples": [ "Series B SaaS accounts (October)" ], "type": "string" }, "object": { "const": "table", "description": "Always `table`.", "type": "string" }, "records_added": { "description": "Records copied into the new table.", "examples": [ 980 ], "minimum": 0, "type": "integer" }, "rows_added": { "deprecated": true, "description": "Deprecated name of `records_added`.", "examples": [ 980 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "table_id": { "deprecated": true, "description": "Deprecated name of `id`.", "examples": [ "tbl_c9b4f80d3721cb7401bb23ae8643e40c" ], "type": "string", "x-sunset": "2027-02-01" }, "updated_at": { "description": "When the new table last changed; the same as `created_at` for a fork.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "object", "id", "name", "created_at", "updated_at", "forked_from", "records_added", "table_id", "rows_added" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "FormulaPreviewRequest": { "additionalProperties": false, "properties": { "condition": { "default": false, "description": "Validate and preview a boolean run condition.", "examples": [ false ], "type": "boolean" }, "expression": { "description": "A formula; fields by {name} or {field_id}.", "examples": [ "{first_name} & \" \" & {last_name}" ], "maxLength": 4096, "minLength": 1, "type": "string" }, "limit": { "description": "How many records to compute the formula for, 1 to 12.", "examples": [ 5 ], "maximum": 12, "minimum": 1, "type": "integer" }, "record_ids": { "description": "The records.", "examples": [ [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "rec_f2ab6e0db3b99626e3c794205f5fb69f" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 12, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "expression" ], "type": "object" }, "FormulaPreviewResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "error": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "Why the expression cannot run: {code, message, position?, suggestion?}. rows is then empty.", "examples": [ null ] }, "referenced_field_ids": { "description": "The fields the formula reads.", "examples": [ [ "fld_3b9ed9139c16536a8e36fd6279b1a510", "fld_4ad93454e0feed19f81e719c13744619" ] ], "items": { "type": "string" }, "type": "array" }, "rows": { "description": "The result rows.", "items": { "properties": { "id": { "description": "The record the value was computed for.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "type": "string" }, "value": { "description": "The formula's value for this record.", "examples": [ "Priya Raman" ] } }, "required": [ "id", "value" ], "type": "object" }, "maxItems": 12, "type": "array" } }, "required": [ "error", "rows" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "HistoricalChange": { "properties": { "after": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/HistoricalField" }, { "$ref": "#/components/schemas/HistoricalRecord" } ] }, { "type": "null" } ], "description": "The field or record after the change, or null when it was removed." }, "before": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/HistoricalField" }, { "$ref": "#/components/schemas/HistoricalRecord" } ] }, { "type": "null" } ], "description": "The field or record before the change, or null when it was added." }, "id": { "description": "The changed field's or record's id.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "type": "string" }, "kind": { "description": "What changed: a field or record added, removed or changed.", "enum": [ "field_added", "field_removed", "field_changed", "record_added", "record_removed", "record_changed" ] } }, "required": [ "id", "kind", "before", "after" ], "type": "object" }, "HistoricalChangePage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/HistoricalChange" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "counts": { "$ref": "#/components/schemas/RestoreCounts", "description": "What restoring the base to this version would change, as Restore a version reports it." }, "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor for the next page, or null on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more", "counts" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "HistoricalField": { "$ref": "#/components/schemas/Field" }, "HistoricalRecord": { "properties": { "cells": { "additionalProperties": true, "deprecated": true, "description": "Deprecated: use `fields`, keyed by field key. The same values keyed by field id; formula values are computed.", "examples": [ { "fld_4ac9744e5c4b96172195f7f2f070a486": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" }, "fld_7a852289ea2135b37304ae3217fa47e0": "2026-10-21", "fld_b00a97266f03cceb43636653c0e40b38": "northbeam.io" } ], "type": "object" }, "fields": { "additionalProperties": true, "description": "Field values at this version, keyed by field key; a field the version no longer has is left out.", "examples": [ { "company_domain": "northbeam.io", "last_contacted": "2026-10-21", "lead_stage": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" } } ], "type": "object" }, "id": { "description": "The record's id.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "type": "string" }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" } }, "required": [ "id", "position", "cells", "fields" ], "type": "object" }, "HistoricalRecordPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/HistoricalRecord" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor for the next page, or null on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "InputOptionPage": { "description": "A picker input's live choices, on one page.", "examples": [ { "data": [ { "label": "Leads", "value": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ], "meta": { "has_more": false, "next_cursor": null } } ], "properties": { "data": { "description": "The choices, in the provider's order.", "examples": [ [ { "label": "Leads", "value": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ] ], "items": { "properties": { "label": { "description": "What the choice is called.", "examples": [ "Leads" ], "type": "string" }, "value": { "description": "The value to send for the input.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "type": [ "string", "number" ] } }, "required": [ "value", "label" ], "type": "object" }, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "Opaque authenticated cursor that carries the provider's own cursor, bound to this input and query. Null means traversal is complete.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "Integration": { "description": "A catalog provider the workspace's plan allows. connected is true when the workspace has a default key for it, and always for a built-in provider; keys are never returned.", "properties": { "auth_mode": { "description": "How the provider authenticates.", "examples": [ "api_key" ], "type": "string" }, "category": { "description": "The provider's category.", "examples": [ "people" ], "type": "string" }, "connected": { "description": "Whether the workspace has a default key for this provider.", "examples": [ true ], "type": "boolean" }, "connection": { "description": "`built_in`: always connected and never given a credential (Appenda). `credential`: connect a key first. More values may be added.", "enum": [ "built_in", "credential" ], "examples": [ "built_in" ], "type": "string" }, "connection_fields": { "description": "What connecting the provider asks for, such as an API key; empty for a built-in provider.", "examples": [ [ { "help": "Paste the API key from your account settings.", "kind": "secret", "label": "API key", "name": "api_key", "required": true } ] ], "items": { "type": "object" }, "type": "array" }, "credential_shape": { "description": "What a key for this provider looks like.", "examples": [ "api_key" ], "type": "string" }, "key_source": { "deprecated": true, "description": "Deprecated: use `key_sources`. `appenda`, `own` or `either` (both).", "enum": [ "appenda", "own", "either" ], "examples": [ "either" ], "type": "string", "x-sunset": "2027-02-01" }, "key_sources": { "description": "Whose keys the action can run on: `appenda` (Appenda's keys, spending credits) and `own` (a key the workspace connects). New values can appear.", "examples": [ [ "appenda", "own" ] ], "items": { "enum": [ "appenda", "own" ], "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "logo_key": { "description": "The provider's logo.", "examples": [ "appenda" ], "type": "string" }, "methods": { "description": "The provider's actions.", "examples": [ [ { "category": "tables", "id": "send_row", "kind": "row_action", "label": "Send row to table", "name": "Send row to table", "price": "free", "runs_on": "local_and_cloud" } ] ], "items": { "properties": { "category": { "description": "The method's group: `tables`, `search`, `enrich` or `actions`. More groups may be added.", "examples": [ "tables" ], "type": "string" }, "description": { "description": "What the method does, including its side effects.", "examples": [ "Write this row as a row of another table. Writes rows to another table and writes history; spends no credits." ], "type": "string" }, "example_input": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One example of the method's inputs, as JSON text; null when there is none.", "examples": [ "{\"target_table\":\"tbl_5246f913f71a9485a05033249a6dc75e\",\"mapping\":[{\"from\":\"fld_1e57b877a78db86124936f976015f646\",\"to_field_id\":\"fld_a6806b5f732319fbc6a15bafac71f658\"}]}" ] }, "id": { "description": "The method's id: the `action` you name when you create a field.", "examples": [ "send_row" ], "type": "string" }, "input_fields": { "description": "The keys of the method's required inputs.", "examples": [ [ "target_table", "mapping" ] ], "items": { "type": "string" }, "type": "array" }, "inputs": { "description": "The method's typed inputs, as Get action parameters returns them.", "examples": [ [ { "description": "The table of this workspace the rows go to or are read from.", "key": "target_table", "required": true } ] ], "items": { "type": "object" }, "type": "array" }, "kind": { "description": "`row_enrich` and `row_action` run once per record as a field; `provider_action` and `list_import` run on their own. More kinds may be added.", "examples": [ "row_action" ], "type": "string" }, "label": { "deprecated": true, "description": "Deprecated: use `name`, which holds the same text.", "examples": [ "Send row to table" ], "type": "string", "x-sunset": "2027-02-01" }, "logo_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The method's own logo; null when it uses the provider's.", "examples": [ "appenda" ] }, "managed_billing_unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What a managed run charges per: `row`, `unique_row`, `page` or `query`; null when it is not priced in credits.", "examples": [ "row" ] }, "managed_credits_per_unit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Credits per billing unit on Appenda's keys; null when it is not priced in credits.", "examples": [ 0.5 ] }, "name": { "description": "The action's name.", "examples": [ "Send row to table" ], "type": "string" }, "optional_input_fields": { "description": "The keys of the method's optional inputs.", "examples": [ [ "match_field", "overwrite" ] ], "items": { "type": "string" }, "type": "array" }, "output_fields": { "description": "The fields each answer carries.", "examples": [ [ "status", "created", "updated" ] ], "items": { "type": "string" }, "type": "array" }, "output_paths": { "description": "JSON pointers to the useful fields of one result item; empty for a method that is not a list import.", "examples": [ [ "/full_name", "/job_title" ] ], "items": { "type": "string" }, "type": "array" }, "price": { "anyOf": [ { "enum": [ "free", "credits" ], "type": "string" }, { "type": "null" } ], "description": "A built-in method's cost: `free` never spends credits, `credits` spends Appenda credits. null for other providers, whose key decides.", "examples": [ "free" ] }, "runs_on": { "description": "`local_and_cloud`: runs on the desktop and in the Cloud. `cloud`: runs only in the Cloud.", "enum": [ "local_and_cloud", "cloud" ], "examples": [ "local_and_cloud" ], "type": "string" }, "summary": { "description": "One line that says what the method does.", "examples": [ "Write this row, or the fields you choose from it, as a row of another table." ], "type": "string" } }, "required": [ "id", "label", "kind", "category", "runs_on", "name" ], "type": "object" }, "type": "array" }, "name": { "description": "The provider's display name.", "examples": [ "Appenda" ], "type": "string" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "leadmagic" ], "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, the same value. The provider, as listed by List integrations.", "examples": [ "appenda" ], "type": "string" } }, "required": [ "provider_id", "name", "connection", "methods", "connected", "key_source", "key_sources" ], "type": "object" }, "IntegrationAction": { "description": "One action of an integration.", "properties": { "can_be_field": { "description": "Whether the action can be an enrichment field.", "examples": [ true ], "type": "boolean" }, "description": { "description": "What the action does.", "examples": [ "Finds a person's work email from their name and company domain." ], "type": "string" }, "id": { "description": "The action's id.", "examples": [ "email_finder" ], "type": "string" }, "key_source": { "deprecated": true, "description": "Deprecated: use `key_sources`. `appenda`, `own` or `either` (both).", "enum": [ "appenda", "own", "either" ], "examples": [ "either" ], "type": "string", "x-sunset": "2027-02-01" }, "key_sources": { "description": "Whose keys the action can run on: `appenda` (Appenda's keys, spending credits) and `own` (a key the workspace connects). New values can appear.", "examples": [ [ "appenda", "own" ] ], "items": { "enum": [ "appenda", "own" ], "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "kind": { "description": "`row_enrich` and `row_action` run once per record as a field; `provider_action` and `list_import` run on their own. More kinds may be added.", "examples": [ "row_enrich" ], "type": "string" }, "name": { "description": "The action's name.", "examples": [ "Find work email" ], "type": "string" }, "object": { "description": "Always `action`.", "enum": [ "action" ], "examples": [ "action" ], "type": "string" }, "schema_version": { "description": "The version of the action's parameters; name it when you create a field.", "examples": [ 2 ], "type": "integer" } }, "required": [ "object", "id", "name", "kind", "can_be_field", "schema_version", "key_source", "key_sources" ], "type": "object" }, "IntegrationActionPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/IntegrationAction" }, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Always null: this collection is one bounded page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "IntegrationConnection": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "connected": { "description": "Whether the workspace has a default key for this provider.", "examples": [ true ], "type": "boolean" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "leadmagic" ], "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, the same value. The provider, as listed by List integrations.", "examples": [ "appenda" ], "type": "string" } }, "required": [ "provider_id", "connected" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "IntegrationCredentialWrite": { "additionalProperties": false, "description": "A provider's own API key, write only: it is sealed like a key pasted in the desktop's Integrations settings and is never returned, logged or echoed in an error. Only providers that take one pasted API key are accepted (credential_shape_unsupported otherwise). A provider that is already connected answers integration_connected: disconnect it first.", "properties": { "api_key": { "description": "The provider's API key. It is stored encrypted and never returned.", "examples": [ "your-provider-api-key" ], "maxLength": 8000, "minLength": 1, "type": "string", "writeOnly": true }, "name": { "description": "A name for the key. Defaults to `API key`.", "examples": [ "Outbound team key" ], "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "api_key" ], "type": "object" }, "IntegrationPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/Integration" }, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Always null: this collection is one bounded page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "Interface": { "properties": { "block_errors": { "description": "Blocks whose table or fields changed underneath them.", "items": { "properties": { "block_id": { "description": "The block.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "type": "string" }, "page_id": { "description": "The page.", "examples": [ "page_06fc6be90b523fa3c79bc2e19ff0d11b" ], "type": "string" }, "reason": { "description": "Why, in words.", "examples": [ "Over this month's budget for this table." ], "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "The interface's id.", "examples": [ "iface_e75642bd5fc3eba043f27a2c87459bef" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "name": { "description": "The interface's name.", "examples": [ "Pipeline overview" ], "type": "string" }, "pages": { "description": "The interface's pages, in order.", "items": { "$ref": "#/components/schemas/InterfacePage" }, "maxItems": 8, "type": "array" }, "table_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The table this interface belongs to, or null for a workspace interface.", "examples": [ null ] }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "id", "table_id", "name", "pages", "updated_at", "block_errors" ], "type": "object" }, "InterfaceBlock": { "oneOf": [ { "$ref": "#/components/schemas/InterfaceKnownBlock" }, { "additionalProperties": true, "description": "An unsupported saved block is preserved unchanged when editing another block. New or modified unsupported blocks are rejected.", "not": { "$ref": "#/components/schemas/InterfaceKnownBlock" }, "properties": { "id": { "description": "The block's id.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "maxLength": 64, "minLength": 1, "type": "string" }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" }, "title": { "description": "The title shown on the block.", "examples": [ "Meetings by month" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "id", "title", "position" ], "type": "object" } ] }, "InterfaceBlockMove": { "additionalProperties": false, "properties": { "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" } }, "required": [ "position" ], "type": "object" }, "InterfaceBlockWrite": { "additionalProperties": false, "examples": [ { "block": { "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "position": 0, "query": { "limit": 50, "metrics": [ { "label": "Meetings", "operation": "count" } ], "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "title": "Meetings booked" } } ], "properties": { "block": { "$ref": "#/components/schemas/InterfaceKnownBlock", "description": "The block to write." } }, "required": [ "block" ], "type": "object" }, "InterfaceCreate": { "additionalProperties": false, "description": "Without pages the interface starts with one empty Overview page.", "examples": [ { "name": "Pipeline overview", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ], "properties": { "name": { "description": "The interface's name, 1 to 64 characters.", "examples": [ "Pipeline overview" ], "maxLength": 64, "minLength": 1, "type": "string" }, "pages": { "description": "The interface's pages, in order.", "items": { "$ref": "#/components/schemas/InterfacePage" }, "maxItems": 8, "type": "array" }, "table_id": { "description": "A table to scope the interface to; it is then deleted with the table. Omit for a workspace interface.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [], "type": "object" }, "InterfaceFilterBinding": { "additionalProperties": false, "properties": { "block_id": { "description": "The block.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "maxLength": 64, "minLength": 1, "type": "string" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "block_id", "table_id" ], "type": "object" }, "InterfaceKnownBlock": { "oneOf": [ { "additionalProperties": false, "description": "Chart blocks may omit kind for compatibility with saved definitions.", "properties": { "display": { "anyOf": [ { "$ref": "#/components/schemas/BlockDisplay" }, { "type": "null" } ], "description": "How the chart looks, or null for the defaults." }, "id": { "description": "The block's id.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "const": "chart", "description": "The kind of block: a chart, a filter control or a section." }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/BlockLayout" }, { "type": "null" } ], "description": "Where the block sits on the page grid; null places it after the previous block." }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" }, "query": { "$ref": "#/components/schemas/StoredAggregateSpec", "description": "What the chart computes." }, "section_id": { "description": "The section block on this page whose filter also applies.", "examples": [ "block_c35d83a7a2e46c143a700d469509ab98" ], "maxLength": 64, "minLength": 1, "type": "string" }, "title": { "description": "The title shown on the block.", "examples": [ "Meetings by month" ], "maxLength": 64, "minLength": 1, "type": "string" }, "use_page_filter": { "description": "Whether the page filter applies; absent means true.", "examples": [ true ], "type": "boolean" } }, "required": [ "id", "title", "query", "position" ], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "description": "The block's id.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "const": "table", "description": "The kind of block: a chart, a filter control or a section." }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/BlockLayout" }, { "type": "null" } ], "description": "Where the block sits on the page grid; null places it after the previous block." }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" }, "section_id": { "description": "The section block on this page whose filter also applies.", "examples": [ "block_c35d83a7a2e46c143a700d469509ab98" ], "maxLength": 64, "minLength": 1, "type": "string" }, "source": { "$ref": "#/components/schemas/TableBlockSource", "description": "Where the records come from." }, "title": { "description": "The title shown on the block.", "examples": [ "Meetings by month" ], "maxLength": 64, "minLength": 1, "type": "string" }, "use_page_filter": { "description": "Whether the page filter applies; absent means true.", "examples": [ true ], "type": "boolean" } }, "required": [ "id", "title", "position", "kind", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "description": "The block's id.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "const": "text", "description": "The kind of block: a chart, a filter control or a section." }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/BlockLayout" }, { "type": "null" } ], "description": "Where the block sits on the page grid; null places it after the previous block." }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" }, "section_id": { "description": "The section block on this page whose filter also applies.", "examples": [ "block_c35d83a7a2e46c143a700d469509ab98" ], "maxLength": 64, "minLength": 1, "type": "string" }, "text": { "description": "The section's text.", "examples": [ "Accounts we are actively working this quarter." ], "maxLength": 16384, "type": "string" }, "title": { "description": "The title shown on the block.", "examples": [ "Meetings by month" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "id", "title", "position", "kind", "text" ], "type": "object" }, { "additionalProperties": false, "properties": { "bindings": { "description": "Filter controls on the page that also filter this block.", "items": { "$ref": "#/components/schemas/InterfaceFilterBinding" }, "maxItems": 24, "minItems": 1, "type": "array" }, "filter": { "$ref": "#/components/schemas/FilterSpec", "description": "Only the records this filter keeps; null or omitted keeps every record." }, "id": { "description": "The block's id.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "const": "filter_control", "description": "The kind of block: a chart, a filter control or a section." }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/BlockLayout" }, { "type": "null" } ], "description": "Where the block sits on the page grid; null places it after the previous block." }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" }, "section_id": { "description": "The section block on this page whose filter also applies.", "examples": [ "block_c35d83a7a2e46c143a700d469509ab98" ], "maxLength": 64, "minLength": 1, "type": "string" }, "title": { "description": "The title shown on the block.", "examples": [ "Meetings by month" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "id", "title", "position", "kind", "bindings", "filter" ], "type": "object" }, { "additionalProperties": false, "description": "A titled band; its filter applies to every block whose section_id names it.", "properties": { "description": { "description": "A short description shown under the title.", "examples": [ "Meetings booked from outbound, by month." ], "maxLength": 280, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterSpec", "description": "Only the records this filter keeps; null or omitted keeps every record." }, "id": { "description": "The block's id.", "examples": [ "block_72554c079aeac4c4e25acb33100ddf2d" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "const": "section", "description": "The kind of block: a chart, a filter control or a section." }, "layout": { "anyOf": [ { "$ref": "#/components/schemas/BlockLayout" }, { "type": "null" } ], "description": "Where the block sits on the page grid; null places it after the previous block." }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" }, "title": { "description": "The title shown on the block.", "examples": [ "Meetings by month" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "id", "title", "position", "kind" ], "type": "object" } ] }, "InterfaceList": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/InterfaceSummary" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "InterfaceMutation": { "description": "The interface as written, and the history entry the write made.", "properties": { "data": { "$ref": "#/components/schemas/Interface", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "InterfacePage": { "additionalProperties": false, "properties": { "blocks": { "description": "The page's blocks, in order.", "items": { "$ref": "#/components/schemas/InterfaceBlock" }, "maxItems": 24, "type": "array" }, "filter": { "anyOf": [ { "$ref": "#/components/schemas/FilterSpec" }, { "type": "null" } ], "description": "Only the records this filter keeps; null or omitted keeps every record." }, "id": { "description": "The page's id.", "examples": [ "page_06fc6be90b523fa3c79bc2e19ff0d11b" ], "maxLength": 64, "minLength": 1, "type": "string" }, "name": { "description": "The page's name.", "examples": [ "This quarter" ], "maxLength": 64, "minLength": 1, "type": "string" }, "page_type": { "description": "The page: a `dashboard` of blocks or a `record_explorer` over a table.", "enum": [ "dashboard", "record_explorer" ] }, "position": { "description": "Its place in order, from 0.", "examples": [ 2 ], "type": "integer" }, "source_table_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "The table the page reads, or null.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ] }, "source_view_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "The view the page reads, or null for the whole table.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ] } }, "required": [ "id", "name", "page_type", "position", "blocks" ], "type": "object" }, "InterfaceResponse": { "properties": { "data": { "$ref": "#/components/schemas/Interface", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "InterfaceSummary": { "properties": { "id": { "description": "The interface's id.", "examples": [ "iface_e75642bd5fc3eba043f27a2c87459bef" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "name": { "description": "The interface's name.", "examples": [ "Pipeline overview" ], "type": "string" }, "table_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The table this interface belongs to, or null for a workspace interface.", "examples": [ null ] }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "id", "table_id", "name", "updated_at" ], "type": "object" }, "InterfaceUpdate": { "additionalProperties": false, "description": "At least one property; pages replace the whole definition.", "examples": [ { "name": "Pipeline overview Q4" } ], "properties": { "name": { "description": "A new name, 1 to 64 characters.", "examples": [ "Pipeline overview" ], "maxLength": 64, "minLength": 1, "type": "string" }, "pages": { "description": "All of the interface's pages, replacing the current ones.", "items": { "$ref": "#/components/schemas/InterfacePage" }, "maxItems": 8, "type": "array" } }, "required": [], "type": "object" }, "JobAcceptedResponse": { "description": "The run was accepted and runs in the background.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "The run's id; read it with Get a run. Null when nothing ran because every record was missing an input.", "examples": [ "job_d60ef6b2d188d2801bd33bf129195874" ] }, "kind": { "description": "The kind of run.", "enum": [ "enrichment" ], "type": "string" }, "missing_input_count": { "description": "The selected records skipped because an input is empty; none is sent or charged. Set only when nothing else ran.", "examples": [ 12 ], "format": "int64", "minimum": 0, "type": "integer" }, "object": { "description": "Always `run`.", "enum": [ "run" ], "examples": [ "run" ], "type": "string" }, "record_count": { "description": "The records the run was asked to enrich.", "examples": [ 250 ], "format": "int64", "minimum": 0, "type": "integer" }, "requested_rows": { "deprecated": true, "description": "Deprecated: use `record_count`, which holds the same number.", "examples": [ 250 ], "format": "int64", "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "spend": { "description": "For a run started with `spend_cap`: the cap and the credits it reserved.", "properties": { "billing_quote": { "anyOf": [ { "$ref": "#/components/schemas/BillingQuote" }, { "type": "null" } ], "description": "What the run may cost, or null when it runs on the workspace's own key." }, "max_credits": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "The most credits the run may spend.", "examples": [ 500 ] }, "max_rows": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "The most records the run may reach, from its spend cap; null when the cap set none.", "examples": [ 500 ] }, "reserved_credits": { "description": "Credits reserved for the run: the quote's most credits, or 0 on the workspace's own key.", "examples": [ 500 ], "minimum": 0, "type": "integer" } }, "required": [ "max_credits", "max_rows", "reserved_credits", "billing_quote" ], "type": "object" }, "status": { "description": "The run's status. A new run starts `queued`; a start whose records all miss an input is `succeeded` at once.", "enum": [ "queued", "succeeded" ], "examples": [ "queued" ], "type": "string" }, "workspace_id": { "description": "The workspace.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "object", "id", "workspace_id", "kind", "requested_rows", "status", "record_count" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "JobPreviewRequest": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "credential_source": { "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. `managed` (Appenda's key, spends credits), `default` (the workspace's default key) or `explicit` (the key in `credential_id`).", "enum": [ "managed", "default" ] } }, "required": [ "credential_source" ] }, "then": { "not": { "required": [ "credential_id" ] } } }, { "if": { "properties": { "credential_source": { "const": "explicit", "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. `managed` (Appenda's key, spends credits), `default` (the workspace's default key) or `explicit` (the key in `credential_id`)." } }, "required": [ "credential_source" ] }, "then": { "required": [ "credential_id" ] } } ], "description": "One enrichment field and the rows to run. To run several fields that feed each other, use Preview a multi-field run.", "properties": { "credential_id": { "description": "A provider key the workspace holds; send it alone to run on that key. Leave it out to use `credential_source`.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ], "maxLength": 64, "minLength": 1, "type": "string" }, "credential_source": { "default": "managed", "deprecated": true, "description": "Deprecated: use `credential_id`, which alone picks the key. `managed` (Appenda's key, spends credits), `default` (the workspace's default key) or `explicit` (the key in `credential_id`).", "enum": [ "managed", "default", "explicit" ], "type": "string" }, "field_id": { "description": "The field.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "description": "The kind of run. Only `enrichment` exists today.", "enum": [ "enrichment" ], "type": "string" }, "options": { "$ref": "#/components/schemas/RunOptions", "description": "Which rows the run reaches and how." }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "maxLength": 64, "minLength": 1, "type": "string" }, "via_agent": { "$ref": "#/components/schemas/ViaAgent", "description": "Set when an agent tool sends the request for you. Leave it out for your own requests.", "examples": [ { "kind": "claude_code" } ] } }, "required": [ "kind", "table_id", "field_id", "options" ], "type": "object" }, "JobPreviewResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "approval_required": { "description": "Whether starting this run will be held for approval.", "examples": [ false ], "type": "boolean" }, "billing_quote": { "anyOf": [ { "$ref": "#/components/schemas/BillingQuote" }, { "type": "null" } ], "description": "What the run may cost, or null when it runs on the workspace's own key." }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The key the run will use, or null for Appenda's managed key.", "examples": [ null ], "readOnly": true }, "expires_at": { "description": "When the preview token stops working.", "examples": [ "2026-10-21T14:18:12.000Z" ], "format": "date-time", "type": "string" }, "intent_id": { "description": "Your id for this run, used to tell retries apart.", "examples": [ "run_oct_emails" ], "maxLength": 64, "minLength": 1, "type": "string" }, "max_calls": { "description": "The most provider calls the run may make.", "examples": [ 500 ], "format": "int64", "minimum": 1, "type": "integer" }, "preview_token": { "description": "The token from the preview, valid for this exact request only. Anything changed since the preview is refused.", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "maxLength": 4096, "minLength": 1, "type": "string" }, "requested_rows": { "description": "Rows the run was asked to reach.", "examples": [ 500 ], "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "intent_id", "preview_token", "expires_at", "max_calls", "requested_rows", "approval_required", "credential_id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "JobStatusResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider action the run calls.", "examples": [ "email_finder" ] }, "completed_rows": { "deprecated": true, "description": "Deprecated: use `records_done`, which holds the same number.", "examples": [ 240 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "credits": { "description": "The run's credits: what it set aside, what it spent once it ended and whose key paid. Missing when they could not be read in time.", "examples": [ { "estimated": 50, "estimated_decimal": 50, "key_source": "appenda", "used": 48, "used_decimal": 48 } ], "properties": { "estimated": { "description": "Credits set aside from the balance when the run started, from its price. Credits it does not use return when it ends.", "examples": [ 50 ], "minimum": 0, "type": "integer" }, "estimated_decimal": { "description": "`estimated` as a JSON number. Equals the integer today: the ledger holds whole credits.", "examples": [ 50 ], "minimum": 0, "type": "number" }, "key_source": { "description": "Whose key paid: `appenda` (Appenda's keys, spending credits) or `own` (a key the workspace connected). New values can appear.", "enum": [ "appenda", "own" ], "examples": [ "appenda" ], "type": "string" }, "used": { "description": "Credits the run spent, settled once when it ends: 0 while it runs. A run on a key you connected spends none.", "examples": [ 48 ], "minimum": 0, "type": "integer" }, "used_decimal": { "description": "`used` as a JSON number. Equals the integer today: the ledger holds whole credits.", "examples": [ 48 ], "minimum": 0, "type": "number" } }, "required": [ "estimated", "used", "key_source", "estimated_decimal", "used_decimal" ], "type": "object" }, "failed_rows": { "deprecated": true, "description": "Deprecated: use `records_failed`, which holds the same number.", "examples": [ 8 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "field_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The enrichment field the run fills.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ] }, "id": { "description": "The run's id.", "examples": [ "job_d60ef6b2d188d2801bd33bf129195874" ], "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "description": "The kind of run.", "enum": [ "enrichment" ], "examples": [ "enrichment" ], "type": "string" }, "needs_review_rows": { "deprecated": true, "description": "Deprecated: records whose charge is being settled; they are counted in `records_done`.", "examples": [ 2 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "no_result_rows": { "deprecated": true, "description": "Deprecated: use `records_empty`, which holds the same number.", "examples": [ 30 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "object": { "description": "Always `run`.", "enum": [ "run" ], "examples": [ "run" ], "type": "string" }, "outcome_class_counts": { "description": "Why records ended without a value: stopped by you, out of credits, a provider error or an Appenda error.", "examples": [ { "error_internal": 1, "error_no_credits": 2, "error_provider": 8, "stopped_by_user": 4 } ], "properties": { "error_internal": { "description": "Records that failed inside Appenda.", "examples": [ 1 ], "minimum": 0, "type": "integer" }, "error_no_credits": { "description": "Records not run because the workspace ran out of credits.", "examples": [ 2 ], "minimum": 0, "type": "integer" }, "error_provider": { "description": "Records the provider call failed for.", "examples": [ 8 ], "minimum": 0, "type": "integer" }, "stopped_by_user": { "description": "Records left unsent because the run was stopped.", "examples": [ 4 ], "minimum": 0, "type": "integer" } }, "required": [ "stopped_by_user", "error_no_credits", "error_provider", "error_internal" ], "type": "object" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider the run calls.", "examples": [ "leadmagic" ] }, "record_count": { "description": "The records the run was asked to enrich.", "examples": [ 250 ], "minimum": 0, "type": "integer" }, "records_done": { "description": "Records the run has finished, whatever the outcome.", "examples": [ 240 ], "minimum": 0, "type": "integer" }, "records_empty": { "description": "Records where the provider answered but found nothing.", "examples": [ 30 ], "minimum": 0, "type": "integer" }, "records_failed": { "description": "Records the provider call failed for. Failed records are not charged.", "examples": [ 8 ], "minimum": 0, "type": "integer" }, "records_found": { "description": "Records where the provider found a value.", "examples": [ 198 ], "minimum": 0, "type": "integer" }, "records_skipped": { "description": "Records not sent, for example because the run was stopped or an input was empty.", "examples": [ 4 ], "minimum": 0, "type": "integer" }, "requested_rows": { "deprecated": true, "description": "Deprecated: use `record_count`, which holds the same number.", "examples": [ 250 ], "format": "int64", "minimum": 1, "type": "integer", "x-sunset": "2027-02-01" }, "skipped_rows": { "deprecated": true, "description": "Deprecated: use `records_skipped`, which holds the same number.", "examples": [ 4 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "status": { "description": "The run's status: `queued` (waiting to start), `running`, `succeeded`, `failed` or `stopped`, and `needs_review` while its charge is settled. New statuses can appear.", "enum": [ "queued", "running", "succeeded", "failed", "stopped", "needs_review" ], "examples": [ "succeeded" ], "type": "string" }, "stop_requested": { "description": "Whether a stop was requested.", "examples": [ false ], "type": "boolean" }, "succeeded_rows": { "deprecated": true, "description": "Deprecated: use `records_found`, which holds the same number.", "examples": [ 198 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "table_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The table the run writes to.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ] }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" }, "waiting_for": { "description": "Fields still being filled that this run reads; it starts once they end. Empty when it waits for nothing.", "examples": [ [] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "type": "array" }, "workspace_id": { "description": "The workspace.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "object", "id", "workspace_id", "kind", "requested_rows", "status", "stop_requested", "created_at", "updated_at", "table_id", "field_id", "provider", "action", "record_count", "records_done", "records_found", "records_empty", "records_skipped", "records_failed", "completed_rows", "succeeded_rows", "no_result_rows", "skipped_rows", "failed_rows", "needs_review_rows", "outcome_class_counts", "waiting_for" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "JobStopResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "id": { "description": "The run's id.", "examples": [ "job_d60ef6b2d188d2801bd33bf129195874" ], "maxLength": 64, "minLength": 1, "type": "string" }, "stop_requested": { "const": true, "description": "Whether a stop was requested.", "type": "boolean" }, "workspace_id": { "description": "The workspace.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "id", "workspace_id", "stop_requested" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "ListImportJobResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "action": { "description": "The provider search action.", "examples": [ "people_search" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "billable_units": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Units charged so far, or null before any.", "examples": [ 980 ] }, "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "credits": { "description": "The import's credits: what it set aside, what it spent once it ended and whose key paid. Missing when they could not be read in time.", "examples": [ { "estimated": 500, "estimated_decimal": 500, "key_source": "appenda", "used": 480, "used_decimal": 480 } ], "properties": { "estimated": { "description": "Credits set aside from the balance when the import started, from its price. Credits it does not use return when it ends.", "examples": [ 500 ], "minimum": 0, "type": "integer" }, "estimated_decimal": { "description": "`estimated` as a JSON number. Equals the integer today: the ledger holds whole credits.", "examples": [ 50 ], "minimum": 0, "type": "number" }, "key_source": { "description": "Whose key paid: `appenda` (Appenda's keys, spending credits) or `own` (a key the workspace connected). New values can appear.", "enum": [ "appenda", "own" ], "examples": [ "appenda" ], "type": "string" }, "used": { "description": "Credits the import spent, settled once when it ends: 0 while it runs. An import on a key you connected spends none.", "examples": [ 480 ], "minimum": 0, "type": "integer" }, "used_decimal": { "description": "`used` as a JSON number. Equals the integer today: the ledger holds whole credits.", "examples": [ 48 ], "minimum": 0, "type": "number" } }, "required": [ "estimated", "used", "key_source", "estimated_decimal", "used_decimal" ], "type": "object" }, "credits_reserved": { "description": "Credits held for the run so far.", "examples": [ 500 ], "minimum": 0, "type": "integer" }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the import ended, or null while it runs.", "examples": [ "max_rows_reached" ] }, "finalized": { "description": "Whether the import's pages were released.", "examples": [ false ], "type": "boolean" }, "job_id": { "description": "The import's id.", "examples": [ "lij_79f45934b99ad0b7ba5d4327e5b80b74" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "max_pages": { "description": "The most result pages the import may fetch.", "examples": [ 10 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "max_rows": { "description": "The most rows the import may add.", "examples": [ 1000 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "method_id": { "deprecated": true, "description": "Deprecated: use `action`, the same value. The provider action.", "examples": [ "people_search" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "pages_done": { "description": "Pages fetched so far.", "examples": [ 4 ], "maximum": 100000, "minimum": 0, "type": "integer" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "appenda" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, the same value. The provider, as listed by List integrations.", "examples": [ "appenda" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "records_done": { "description": "Records added so far.", "examples": [ 100 ], "maximum": 100000, "minimum": 0, "type": "integer" }, "rows_done": { "deprecated": true, "description": "Deprecated: use `records_done`, which holds the same number.", "examples": [ 100 ], "maximum": 100000, "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "status": { "description": "The import's status: `queued`, `running`, `succeeded`, `failed` or `stopped`. New statuses can appear.", "enum": [ "queued", "running", "succeeded", "failed", "stopped", "needs_review" ], "examples": [ "succeeded" ], "type": "string" }, "stop_requested": { "description": "Whether a stop was requested.", "examples": [ false ], "type": "boolean" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "job_id", "status", "stop_requested", "provider_id", "method_id", "table_id", "max_rows", "max_pages", "pages_done", "rows_done", "end_reason", "billable_units", "credits_reserved", "finalized", "created_at", "updated_at", "records_done" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "ListImportPage": { "description": "The workspace's list imports, newest first. Default 50 and maximum 100 per page; follow `next_cursor` until it is null.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/ListImportSummary" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "The cursor to the next page; null on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "ListImportStopResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "job_id": { "description": "The import's id.", "examples": [ "lij_79f45934b99ad0b7ba5d4327e5b80b74" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "stop": { "description": "Whether the import is `stopping` or has `ended`.", "enum": [ "stopping", "ended" ], "type": "string" } }, "required": [ "job_id", "stop" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "ListImportSummary": { "description": "A list import as List list imports shows it. Get a list import answers its full state.", "properties": { "action": { "description": "The provider action the job calls.", "examples": [ "email_finder" ], "type": "string" }, "applied": { "description": "Whether the rows were written into the table.", "examples": [ true ], "type": "boolean" }, "created_at": { "description": "When the job started.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "id": { "description": "The list import's id.", "examples": [ "lij_d9735a83f6b094787f1fedc1f2703331" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "max_rows": { "description": "The most rows the import may bring in.", "examples": [ 500 ], "minimum": 0, "type": "integer" }, "object": { "description": "Always `list_import`.", "enum": [ "list_import" ], "examples": [ "list_import" ], "type": "string" }, "pages_done": { "description": "Provider pages fetched so far.", "examples": [ 3 ], "minimum": 0, "type": "integer" }, "provider": { "description": "The provider the job calls.", "examples": [ "leadmagic" ], "type": "string" }, "records_found": { "description": "Records the provider returned so far.", "examples": [ 75 ], "minimum": 0, "type": "integer" }, "rows_found": { "deprecated": true, "description": "Deprecated: use `records_found`, which holds the same number.", "examples": [ 75 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "status": { "description": "`queued` waits to start; `running` is in progress. `succeeded`, `failed`, `stopped` and `needs_review` (charge settling) are final; a stopped job keeps its results. New values may appear.", "enum": [ "queued", "running", "succeeded", "failed", "stopped", "needs_review" ], "examples": [ "succeeded" ], "type": "string" }, "stop_requested": { "description": "Whether a stop was asked for.", "examples": [ false ], "type": "boolean" }, "table_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The table the results go to.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ] }, "updated_at": { "description": "When the job last changed.", "examples": [ "2026-10-21T14:05:40.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "object", "id", "status", "provider", "action", "stop_requested", "created_at", "updated_at", "table_id", "max_rows", "pages_done", "rows_found", "applied", "records_found" ], "type": "object" }, "LogoConfirmed": { "properties": { "data": { "$ref": "#/components/schemas/LogoConfirmedData", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "LogoConfirmedData": { "properties": { "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The logo's URL, or null without one.", "examples": [ "https://images.appenda.app/logos/ws_2e056e042c3953f816e10bb208432f9e.png" ] } }, "required": [ "logoUrl" ], "type": "object" }, "LogoUpload": { "properties": { "data": { "$ref": "#/components/schemas/LogoUploadData", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "LogoUploadData": { "properties": { "imageId": { "description": "The upload's id.", "examples": [ "workspace/ws_2e056e042c3953f816e10bb208432f9e/logo" ], "type": "string" }, "uploadURL": { "description": "A one-time direct upload URL; the image is stored only after confirm.", "examples": [ "https://upload.appenda.app/workspace/ws_2e056e042c3953f816e10bb208432f9e/logo?signature=9f2c4b1e" ], "type": "string" } }, "required": [ "imageId", "uploadURL" ], "type": "object" }, "Member": { "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member's name, or null.", "examples": [ "Priya Raman" ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member's email address, or null when it is not shared.", "examples": [ "priya.raman@northbeam.io" ] }, "joined_at": { "description": "When the member entered the workspace (an instance admin listed without a membership: when they became an instance admin).", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "role": { "description": "The member's built-in role.", "examples": [ "editor" ], "type": "string" }, "role_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assigned custom role key, if any.", "examples": [ null ] }, "status": { "description": "The member's account state: always `Active` today. New states may be added.", "examples": [ "Active" ], "type": "string" }, "user_id": { "description": "The member's account.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ], "type": "string" } }, "required": [ "user_id", "display_name", "email", "role", "status" ], "type": "object" }, "MemberPage": { "description": "One page: 50 items by default, at most 100; follow `meta.next_cursor` until it is `null`.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/Member" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "MemberRemoved": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "deleted": { "const": true, "description": "Always true." }, "id": { "description": "The removed member's user id.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "object": { "const": "member", "description": "Always `member`.", "type": "string" } }, "required": [ "id", "object", "deleted" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "MemberRoleWrite": { "additionalProperties": false, "description": "The member's new role. An API user token acts as its creator, with their current role, so it can grant or change Owner only if they can. A super-admin token acts as an Admin and never can.", "properties": { "role": { "description": "The member's new built-in role. A key cannot grant or change `owner`.", "enum": [ "owner", "admin", "editor", "viewer" ], "examples": [ "editor" ], "type": "string" } }, "required": [ "role" ], "type": "object" }, "MemberUpdated": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "id": { "description": "The member's user id.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "object": { "const": "member", "description": "Always `member`.", "type": "string" }, "role": { "description": "The member's built-in role now.", "enum": [ "admin", "editor", "viewer" ], "examples": [ "editor" ], "type": "string" } }, "required": [ "object", "id", "role" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "NumberDisplay": { "description": "How a number field shows its value. Changing it never rewrites a stored value.", "properties": { "abbreviate": { "description": "Show 1.2K and 3.4M.", "examples": [ false ], "type": "boolean" }, "allow_negative": { "description": "`false` refuses negative values on write.", "type": "boolean" }, "currency": { "description": "ISO 4217 currency code.", "examples": [ "USD" ], "pattern": "^[A-Z]{3}$", "type": "string" }, "currency_position": { "description": "Whether the currency shows `before` or `after` the amount.", "enum": [ "before", "after" ], "type": "string" }, "decimals": { "description": "Digits after the decimal mark; left out shows the value as stored.", "examples": [ 2 ], "maximum": 8, "minimum": 0, "type": "integer" }, "negatives": { "description": "Show negative values with a `minus` sign or in `parentheses`.", "enum": [ "minus", "parentheses" ], "type": "string" }, "notation": { "description": "`comma_period` (1,234.5), `period_comma` (1.234,5) or `space_comma` (1 234,5); left out: the workspace's.", "enum": [ "comma_period", "period_comma", "space_comma" ], "type": "string" }, "style": { "description": "`number`, `currency`, `percent` (the value is a fraction: 0.25 shows 25%) or `percent_whole` (25 shows 25%).", "enum": [ "number", "currency", "percent", "percent_whole" ], "type": "string" }, "symbol": { "description": "A shown prefix that is not a currency code; never with `currency`.", "examples": [ "pts " ], "maxLength": 8, "type": "string" }, "thousands": { "description": "Group thousands; on by default for a currency.", "examples": [ true ], "type": "boolean" } }, "type": "object" }, "NumberFormat": { "additionalProperties": false, "properties": { "abbreviate": { "description": "Show large numbers short, such as 12.5K.", "examples": [ false ], "type": "boolean" }, "currency": { "anyOf": [ { "description": "Prefix of at most eight UTF-8 bytes.", "maxLength": 8, "type": "string" }, { "type": "null" } ], "description": "The currency: an ISO 4217 code, or a symbol of up to eight bytes for display.", "examples": [ "USD" ] }, "currency_after": { "description": "Show the currency after the number.", "examples": [ false ], "type": "boolean" }, "decimals": { "anyOf": [ { "maximum": 8, "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Decimal places, 0 to 8, or null for as many as needed.", "examples": [ 2 ] }, "negative_parens": { "description": "Show negative numbers in parentheses.", "examples": [ false ], "type": "boolean" }, "no_negatives": { "description": "Show negative numbers as 0.", "examples": [ false ], "type": "boolean" }, "percent": { "description": "Show the number as a percentage of 1.", "examples": [ false ], "type": "boolean" }, "percent_whole": { "description": "Show the number as a percentage of 100.", "examples": [ false ], "type": "boolean" }, "separators": { "description": "Thousands and decimal separators: `comma_period` (1,234.5), `period_comma` (1.234,5) or `space_comma` (1 234,5).", "enum": [ "comma_period", "period_comma", "space_comma", null ] }, "thousands": { "description": "Show a thousands separator.", "examples": [ true ], "type": "boolean" } }, "required": [], "type": "object" }, "OutputFieldsCreate": { "additionalProperties": false, "description": "The outputs to turn into fields, all or none.", "properties": { "outputs": { "description": "Up to 50 outputs; each becomes one field.", "examples": [ [ { "path": "company.domain" }, { "name": "Current title", "path": "experience.0.title" } ] ], "items": { "additionalProperties": false, "properties": { "array": { "description": "How to read an array: `first` (the default) reads the first item, `join` every item's text separated by `, `, `count` how many items hold a value.", "enum": [ "first", "join", "count" ], "examples": [ "first" ], "type": "string" }, "name": { "description": "The new field's name. Default: the path's last key, capitalized.", "examples": [ "Company domain" ], "maxLength": 120, "minLength": 1, "type": "string" }, "path": { "description": "The output's dotted path, as List field outputs names it. A `*` or an index reads one array item.", "examples": [ "company.domain" ], "maxLength": 512, "minLength": 1, "type": "string" } }, "required": [ "path" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "outputs" ], "type": "object" }, "OutputFieldsCreated": { "properties": { "data": { "description": "The fields created, in the order asked.", "items": { "$ref": "#/components/schemas/Field" }, "maxItems": 50, "type": "array" } }, "required": [ "data" ], "type": "object" }, "PreviewGroupRequest": { "additionalProperties": false, "description": "Select up to 60 configured enrichment fields. Dependencies are inferred from authoritative field/formula inputs; cycles are rejected. Each field runs as one job of at most 100,000 rows.", "properties": { "field_ids": { "description": "The enrichment fields to run, up to 60; dependencies are worked out from their inputs.", "examples": [ [ "fld_1e57b877a78db86124936f976015f646", "fld_3b111e2d329410910aafdbad96ec1f45" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 60, "minItems": 1, "type": "array", "uniqueItems": true }, "options": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "force": { "const": true, "description": "Run rows that already have a result too, overwriting it and charging again. Needs `confirm_force: true`." } }, "required": [ "force" ] }, "then": { "properties": { "confirm_force": { "const": true, "description": "Confirms a forced run that overwrites results and charges again. Required with `force: true`." } }, "required": [ "confirm_force" ] } } ], "description": "Which rows the run reaches and how.", "examples": [ { "force": false, "mode": { "kind": "all" } } ], "properties": { "confirm_force": { "default": false, "description": "Confirms a forced run that overwrites results and charges again. Required with `force: true`.", "examples": [ false ], "type": "boolean" }, "force": { "default": false, "description": "Run rows that already have a result too, overwriting it and charging again. Needs `confirm_force: true`.", "examples": [ false ], "type": "boolean" }, "mode": { "description": "Which rows the run reaches: `all`, the `first` N, or a `range` of rows.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "all", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "count": { "description": "How many rows, from the first.", "examples": [ 500 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "kind": { "const": "first", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind", "count" ], "type": "object" }, { "additionalProperties": false, "description": "Inclusive one-based range; end must be at least start.", "properties": { "end": { "description": "The last row, from 1.", "examples": [ 600 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "kind": { "const": "range", "description": "Which kind of object this is; each kind has its own fields." }, "start": { "description": "The first row, from 1.", "examples": [ 101 ], "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": [ "kind", "start", "end" ], "type": "object" } ] }, "outcome_scope": { "description": "Run only rows whose last run ended this way: `stopped`, or an `error` of a given class.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "stopped", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "class": { "description": "Which failed rows to run again: `error_no_credits`, `error_provider` or `error_internal`.", "enum": [ "error_no_credits", "error_provider", "error_internal" ], "type": "string" }, "kind": { "const": "error", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "mode" ], "type": "object" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "table_id", "field_ids", "options" ], "type": "object" }, "ProviderAction": { "description": "A provider action and, once it ran, its readable result. It is sent at most once: an answer that never came back ends `failed`, never sent again (legacy runs read `needs_review`).", "properties": { "action": { "description": "The provider action.", "examples": [ "leads_bulk_add" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "created_at": { "description": "When it was started.", "examples": [ "2026-11-02T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why it ended, or null while it runs.", "examples": [ "complete" ] }, "id": { "description": "The provider action's id.", "examples": [ "paj_4b1d2c3e4f5a6b7c8d9e0f1a2b3c4d5e" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "object": { "const": "provider_action", "description": "Always `provider_action`.", "type": "string" }, "outcome": { "anyOf": [ { "enum": [ "applied", "rejected", "failed", "unknown", "not_sent" ], "type": "string" }, { "type": "null" } ], "description": "What the call did: `applied`, `rejected` (the provider refused the input), `failed`, `unknown` (sent, no answer) or `not_sent`; null until it ran.", "examples": [ "applied" ] }, "provider": { "description": "The provider.", "examples": [ "instantly" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "result": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "The readable result: the HTTP status, the outcome class and its label, such as `Leads added: 2`; null until it ran.", "examples": [ { "class": "created", "result": { "label": "Leads added: 2", "outcome": "created", "value": 2 }, "status": 200 } ] }, "status": { "description": "`pending` until the runner takes it, `running` while it is sent, then `succeeded`, `failed`, or `stopped`. An answer that never came back is `failed`. Legacy runs may read `needs_review`.", "enum": [ "pending", "running", "succeeded", "failed", "stopped", "needs_review" ], "examples": [ "succeeded" ], "type": "string" }, "table_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The table the action is for, or null for a workspace-wide action.", "examples": [ null ] }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-11-02T09:12:46.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "object", "id", "status", "provider", "action" ], "type": "object" }, "ProviderActionResponse": { "properties": { "data": { "$ref": "#/components/schemas/ProviderAction", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "ProviderActionStartRequest": { "additionalProperties": false, "description": "One provider action: a single call that changes or reads the connected tool's workspace, not a table row. It runs on the workspace's own key.", "properties": { "action": { "description": "The provider action to run, as listed by List integration actions.", "examples": [ "leads_bulk_add" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "credential_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The provider key to use, one the workspace holds; the workspace's default key when left out.", "examples": [ "cred_772ad6fd9b6f3d01a25cb34c169bf1b9" ] }, "input": { "description": "The action's inputs, as Get action parameters lists them; up to 48 KiB.", "examples": [ { "campaign_id": "0199a1b2-0000-7000-8000-000000000001", "leads": [ { "email": "priya.raman@northbeam.io", "first_name": "Priya" } ] } ], "type": "object" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "instantly" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "table_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The table the action is for, when it is for one; left out for a workspace-wide action.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ] } }, "required": [ "provider", "action", "input" ], "type": "object" }, "ProviderUsage": { "description": "One provider method's settled cloud runs on one UTC day with one key source.", "properties": { "action": { "description": "The provider action.", "examples": [ "email_finder" ], "type": "string" }, "capability": { "description": "The method's capability (work_email, email_verdict, phone) or category (search.web, crm.write, sequencer.lead, ...); other when unlisted.", "examples": [ "work_email" ], "type": "string" }, "credits": { "description": "Credits charged; 0 on the workspace's own key.", "examples": [ 870 ], "minimum": 0, "type": "integer" }, "credits_decimal": { "description": "`credits` as a JSON number, which can hold fractional credits. Equals the integer today: the ledger holds whole credits.", "examples": [ 120 ], "minimum": 0, "type": "number" }, "credits_per_found": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "credits / found_rows; null without a find.", "examples": [ 1 ] }, "day": { "description": "The UTC day the runs settled.", "examples": [ "2026-10-20" ], "format": "date", "type": "string" }, "found_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "found_rows / rows; null without rows.", "examples": [ 0.7 ] }, "found_rows": { "description": "Rows whose outcome is a find for the capability: a deliverable verdict, a verified or catch-all email, a number, a record, or a write made or queued. Duplicates are not.", "examples": [ 870 ], "minimum": 0, "type": "integer" }, "key_source": { "description": "Whose key paid: `appenda` (Appenda's keys, spending credits) or `own` (a key the workspace connected). New values can appear.", "enum": [ "appenda", "own" ], "examples": [ "appenda" ], "type": "string" }, "method_id": { "deprecated": true, "description": "Deprecated: use `action`, the same value. The provider action.", "examples": [ "email_finder" ], "type": "string" }, "outcomes": { "description": "Rows per outcome (valid, catch_all, not_found, invalid, created, updated, already_exists, failed, ...).", "items": { "properties": { "outcome": { "description": "The outcome, such as `valid`, `not_found` or `failed`.", "examples": [ "valid" ], "type": "string" }, "record_count": { "description": "Records with this outcome.", "examples": [ 870 ], "minimum": 1, "type": "integer" }, "rows": { "deprecated": true, "description": "Deprecated: use `record_count`, which holds the same number.", "examples": [ 870 ], "minimum": 1, "type": "integer", "x-sunset": "2027-02-01" } }, "required": [ "outcome", "rows", "record_count" ], "type": "object" }, "type": "array" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "leadmagic" ], "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, the same value. The provider, as listed by List integrations.", "examples": [ "appenda" ], "type": "string" }, "record_count": { "description": "Records the runs settled, every outcome.", "examples": [ 1240 ], "minimum": 0, "type": "integer" }, "rows": { "deprecated": true, "description": "Deprecated: use `record_count`, which holds the same number.", "examples": [ 1240 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "runs": { "description": "Runs that settled.", "examples": [ 6 ], "minimum": 0, "type": "integer" } }, "required": [ "day", "provider_id", "method_id", "capability", "key_source", "runs", "rows", "credits", "found_rows", "found_rate", "credits_per_found", "outcomes", "record_count", "credits_decimal" ], "type": "object" }, "ProviderUsageResponse": { "description": "The workspace's provider usage over the range, one item per provider method, UTC day and key source. Usage is recorded per settled run and kept when its field or table is deleted, so credits stay equal to what was billed. A range holding more than one read returns is refused with 422 `usage_range_too_wide`, never truncated: narrow `from`/`to` and read again.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/ProviderUsage" }, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Always null: the range is one bounded page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "PublicFilter": { "additionalProperties": false, "description": "A filter by field key with plain values: rules joined by `all` or `any`. Up to 20 rules.", "examples": [ { "match": "all", "rules": [ { "field": "company_name", "operator": "is_any_of", "value": [ "Northbeam", "Acme" ] }, { "field": "employee_count", "operator": "gte", "value": 50 } ] } ], "properties": { "match": { "description": "Whether a record must meet `all` rules or `any` of them. Default `all`.", "enum": [ "all", "any" ], "examples": [ "all" ], "type": "string" }, "rules": { "description": "The rules, up to 20.", "items": { "$ref": "#/components/schemas/PublicFilterRule" }, "maxItems": 20, "type": "array" } }, "required": [ "rules" ], "type": "object" }, "PublicFilterRule": { "additionalProperties": false, "description": "One rule: a field by key, an operator that suits its type and a plain value.", "examples": [ { "field": "company_name", "operator": "is", "value": "Northbeam" } ], "properties": { "field": { "description": "The field's key.", "examples": [ "company_name" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" }, "operator": { "description": "How the field's value is compared. Operators must suit the field's type.", "enum": [ "is_empty", "is_not_empty", "is", "is_not", "contains", "does_not_contain", "starts_with", "ends_with", "domain_is", "is_any_of", "is_none_of", "eq", "ne", "lt", "lte", "gt", "gte", "is_true", "is_false", "before", "after", "on_or_before", "on_or_after", "between", "has_any_of", "has_all_of", "has_none_of", "is_exactly", "found_by" ], "examples": [ "is" ], "type": "string" }, "value": { "description": "A plain value: text, a number, a boolean, a day (`YYYY-MM-DD`) or a relative date (`past_7_days`), a list, or a two-item range; null for operators that take none.", "examples": [ "Northbeam" ] } }, "required": [ "field", "operator" ], "type": "object" }, "PublicSortKey": { "additionalProperties": false, "description": "One sort key: a field by key and a direction.", "examples": [ { "direction": "desc", "field": "employee_count" } ], "properties": { "direction": { "description": "`asc` (smallest first) or `desc`.", "enum": [ "asc", "desc" ], "examples": [ "desc" ], "type": "string" }, "field": { "description": "The field's key.", "examples": [ "employee_count" ], "pattern": "^[A-Za-z0-9_]{1,64}$", "type": "string" } }, "required": [ "field", "direction" ], "type": "object" }, "RateLimitClass": { "properties": { "per_instance": { "description": "Requests all workspaces in the instance may make per window.", "examples": [ 1200 ], "minimum": 1, "type": "integer" }, "per_key": { "description": "Requests one key may make per window.", "examples": [ 300 ], "minimum": 1, "type": "integer" }, "per_workspace": { "description": "Requests all keys in the workspace may make per window.", "examples": [ 600 ], "minimum": 1, "type": "integer" } }, "required": [ "per_key", "per_workspace", "per_instance" ], "type": "object" }, "RateLimits": { "description": "The limits that apply to the calling token on this plan, and how many long-running imports a workspace may have open at once.", "properties": { "classes": { "description": "The limits for each kind of request.", "properties": { "provider": { "$ref": "#/components/schemas/RateLimitClass", "description": "Limits on starting runs and list imports." }, "read": { "$ref": "#/components/schemas/RateLimitClass", "description": "Limits on reads." }, "write": { "$ref": "#/components/schemas/RateLimitClass", "description": "Limits on writes." } }, "required": [ "read", "write", "provider" ], "type": "object" }, "concurrent_jobs": { "description": "How many imports a workspace may have open at once.", "properties": { "csv_imports": { "description": "CSV imports the workspace may have open at once.", "examples": [ 50 ], "minimum": 1, "type": "integer" }, "list_imports": { "description": "List imports the workspace may have open at once.", "examples": [ 50 ], "minimum": 1, "type": "integer" } }, "required": [ "list_imports", "csv_imports" ], "type": "object" }, "object": { "description": "Always `rate_limits`.", "enum": [ "rate_limits" ], "examples": [ "rate_limits" ], "type": "string" }, "window_seconds": { "description": "The length of each limit's window, in seconds.", "examples": [ 60 ], "minimum": 1, "type": "integer" } }, "required": [ "object", "window_seconds", "classes", "concurrent_jobs" ], "type": "object" }, "RateLimitsResponse": { "properties": { "data": { "$ref": "#/components/schemas/RateLimits", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "Record": { "properties": { "cells": { "deprecated": true, "description": "Deprecated: use `fields`, keyed by field key. The same values keyed by field id; formula values are computed.", "examples": [ { "fld_4ac9744e5c4b96172195f7f2f070a486": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" }, "fld_7a852289ea2135b37304ae3217fa47e0": "2026-10-21", "fld_b00a97266f03cceb43636653c0e40b38": "northbeam.io" } ], "type": "object" }, "fields": { "additionalProperties": true, "description": "Field values keyed by field key, the same values as `cells`. A date is `YYYY-MM-DD`, a date with a time RFC 3339 in UTC, a select choice `{id, name}`.", "examples": [ { "company_domain": "northbeam.io", "last_contacted": "2026-10-21", "lead_stage": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" } } ], "type": "object" }, "id": { "description": "The record's id.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" }, "version": { "description": "The record's revision; it grows with every change.", "examples": [ 7 ], "type": "integer" } }, "required": [ "id", "version", "updated_at", "cells", "fields" ], "type": "object" }, "RecordCreated": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "id": { "description": "The new record's id.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RecordPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/Record" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "RecordQuery": { "additionalProperties": false, "description": "Pages in a stable order, ties broken by id; edits made while you page can move items between pages.", "examples": [ { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "limit": 50, "search": "northbeam", "sort": { "keys": [ { "direction": "desc", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23" } ] } } ], "properties": { "cursor": { "description": "The `next_cursor` from the previous page; omit for the first page. Bound to this list and its filters.", "examples": [ "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJyZWNfNWUxOWE3In0" ], "maxLength": 16384, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterSpec", "description": "Only the records this filter keeps; null or omitted keeps every record." }, "limit": { "default": 50, "description": "Records per page, 1 to 100. Defaults to 50.", "examples": [ 50 ], "maximum": 100, "minimum": 1, "type": "integer" }, "record_ids": { "description": "Get these records by id instead: 1 to 100 ids, sent alone.", "examples": [ [ "rec_24e9d8fc115d24dca1fa69e7beb9dfeb", "rec_27bb443825ccd74209fa49af64a20d05" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" }, "search": { "description": "Case-insensitive text match across text fields.", "examples": [ "northbeam" ], "maxLength": 256, "type": "string" }, "sort": { "$ref": "#/components/schemas/SortSpec", "description": "The order of the records; omitted keeps table order." } }, "required": [], "type": "object" }, "RecordResponse": { "properties": { "data": { "$ref": "#/components/schemas/Record", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "RecordUpsertPreview": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "preview_token": { "description": "The token from the preview, valid for this exact request only. Anything changed since the preview is refused.", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "maxLength": 4096, "type": "string" }, "records_to_create": { "description": "Inputs that would create a record.", "examples": [ 18 ], "maximum": 100, "minimum": 0, "type": "integer" }, "records_to_update": { "description": "Inputs that would update a record.", "examples": [ 82 ], "maximum": 100, "minimum": 0, "type": "integer" }, "rows_to_create": { "deprecated": true, "description": "Deprecated: use `records_to_create`, which holds the same number.", "examples": [ 18 ], "maximum": 100, "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "rows_to_update": { "deprecated": true, "description": "Deprecated: use `records_to_update`, which holds the same number.", "examples": [ 82 ], "maximum": 100, "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" } }, "required": [ "rows_to_create", "rows_to_update", "preview_token", "records_to_create", "records_to_update" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RecordWrite": { "additionalProperties": false, "examples": [ { "fields": { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } } ], "properties": { "cells": { "deprecated": true, "description": "Deprecated: use `fields`, which takes the same values. Send one of the two.", "examples": [ { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } ], "maxProperties": 1000, "type": "object" }, "fields": { "description": "Values keyed by field key or id. Dates are `YYYY-MM-DD` or RFC 3339 with any offset; a choice is its name or id; URLs, emails and phones are normalized.", "examples": [ { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } ], "maxProperties": 1000, "type": "object" } }, "type": "object" }, "RecordsCreate": { "additionalProperties": false, "properties": { "records": { "description": "The records to write, up to 100.", "items": { "$ref": "#/components/schemas/RecordWrite" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "records" ], "type": "object" }, "RecordsDelete": { "additionalProperties": false, "description": "Exactly one selector: `record_ids`, `view_id` or `filter`. A view or filter selection that keeps more than `max_records` is refused and nothing is deleted.", "examples": [ { "record_ids": [ "rec_ec89f0cdf353cb742933bb0c607f918c", "rec_47a0f9d1a76df13293377a1be53f515f" ] } ], "properties": { "expected_count": { "description": "Optional exact count of the records the view or filter keeps. If it now keeps a different number, nothing is deleted (409 selection_changed).", "examples": [ 212 ], "maximum": 1000, "minimum": 1, "type": "integer" }, "filter": { "$ref": "#/components/schemas/FilterSpec", "description": "Only the records this filter keeps; null or omitted keeps every record." }, "max_records": { "default": 1000, "description": "Most records a view or filter may keep. A larger selection is refused and nothing is deleted.", "example": 250, "maximum": 1000, "minimum": 1, "type": "integer" }, "record_ids": { "description": "The records.", "examples": [ [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "rec_f2ab6e0db3b99626e3c794205f5fb69f" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "view_id": { "description": "Delete the records this view of the table keeps.", "example": "view_e587a794500fc5e402585863046843e6", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "type": "object" }, "RecordsDeleted": { "description": "The records the request deleted, and the one commit it made.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "properties": { "deleted": { "const": true, "description": "How many records were deleted." }, "id": { "description": "The deleted record's id.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "RecordsMutation": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "properties": { "id": { "description": "The record that holds this input: the one written, or for a skipped input the record it matched.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "index": { "description": "The input's position in `records`, from 0.", "examples": [ 2 ], "maximum": 99, "minimum": 0, "type": "integer" }, "matched_id": { "description": "The record the input matched: the stored duplicate a `replaced` input replaced, or the record a `skipped` one duplicates.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "outcome": { "description": "What became of the input: `created`; `replaced`, created and the stored duplicates deleted; `skipped`, not written because it duplicates `matched_id`.", "enum": [ "created", "replaced", "skipped" ], "examples": [ "skipped" ], "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "meta": { "description": "What the table's dedupe setting did with the records sent.", "examples": [ { "created": 2, "replaced": 1, "skipped": 1 } ], "properties": { "created": { "description": "Records written.", "examples": [ 2 ], "minimum": 0, "type": "integer" }, "replaced": { "description": "Stored records deleted because a record sent duplicates them and the table keeps the newest.", "examples": [ 1 ], "minimum": 0, "type": "integer" }, "skipped": { "description": "Records sent but not written because they duplicate a stored record or an earlier one sent.", "examples": [ 1 ], "minimum": 0, "type": "integer" } }, "required": [ "created", "skipped", "replaced" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RecordsUpdate": { "additionalProperties": false, "examples": [ { "records": [ { "fields": { "lead_stage": "Contacted" }, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" } ] } ], "properties": { "records": { "description": "The records to write, up to 100.", "items": { "additionalProperties": false, "properties": { "cells": { "deprecated": true, "description": "Deprecated: use `fields`, which takes the same values. Send one of the two.", "examples": [ { "lead_stage": "Contacted" } ], "maxProperties": 1000, "type": "object" }, "fields": { "description": "The values to change, keyed by field key or id; fields left out keep their values.", "examples": [ { "lead_stage": "Contacted" } ], "maxProperties": 1000, "type": "object" }, "id": { "description": "The record to update.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "id" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "records" ], "type": "object" }, "RecordsUpdated": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "properties": { "id": { "description": "The record's id.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "index": { "description": "The input's position in `records`, from 0.", "examples": [ 2 ], "maximum": 99, "minimum": 0, "type": "integer" }, "outcome": { "description": "Always `updated`: every record named was updated.", "enum": [ "updated" ], "examples": [ "updated" ], "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "RecordsUpsert": { "additionalProperties": false, "examples": [ { "match_field": "company_domain", "records": [ { "fields": { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } } ] } ], "properties": { "dry_run": { "default": false, "description": "Answer how many records the upsert would create and update, and write nothing.", "examples": [ false ], "type": "boolean" }, "match_field": { "description": "The field whose value matches inputs to records: an id or key of a text or email field.", "examples": [ "company_domain" ], "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "overwrite": { "default": "supplied_cells", "description": "Which values a matched record takes: `supplied_cells` (default) writes every value sent; `fill_empty` writes only into fields that are empty.", "enum": [ "supplied_cells", "fill_empty" ], "examples": [ "supplied_cells" ], "type": "string" }, "preview_token": { "deprecated": true, "description": "Deprecated: use `dry_run`. The token from the preview, valid for this exact request only; anything changed since the preview is refused.", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "maxLength": 4096, "minLength": 32, "type": "string" }, "records": { "description": "The records to write, up to 100.", "items": { "$ref": "#/components/schemas/RecordWrite" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "records", "match_field" ], "type": "object" }, "RecordsUpsertResult": { "oneOf": [ { "$ref": "#/components/schemas/RecordsUpserted" }, { "$ref": "#/components/schemas/RecordUpsertPreview" } ] }, "RecordsUpserted": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "properties": { "id": { "description": "The record's id.", "examples": [ "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "index": { "description": "The input's position in `records`, from 0.", "examples": [ 2 ], "maximum": 99, "minimum": 0, "type": "integer" }, "outcome": { "description": "`created` when no stored record matched the input, `updated` when one did.", "enum": [ "created", "updated" ], "examples": [ "updated" ], "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "meta": { "description": "How many records the upsert created and how many it updated.", "examples": [ { "created": 1, "updated": 1 } ], "properties": { "created": { "description": "Records created because no stored record matched.", "examples": [ 1 ], "minimum": 0, "type": "integer" }, "updated": { "description": "Stored records updated because their match field matched.", "examples": [ 1 ], "minimum": 0, "type": "integer" } }, "required": [ "created", "updated" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "RenameRequest": { "additionalProperties": false, "properties": { "name": { "description": "The new name, 1 to 100 characters after trimming.", "examples": [ "Northbeam GTM" ], "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "RenameResult": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "id": { "description": "The id of what was renamed: the workspace or the instance.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "name": { "description": "The new name.", "examples": [ "Northbeam GTM" ], "maxLength": 100, "minLength": 1, "type": "string" }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "id", "name", "updated_at" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RestoreCounts": { "properties": { "cells_changed": { "deprecated": true, "description": "Deprecated name of `values_changed`.", "examples": [ 212 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "fields_added": { "description": "Fields added.", "examples": [ 2 ], "minimum": 0, "type": "integer" }, "fields_changed": { "description": "Fields changed.", "examples": [ 1 ], "minimum": 0, "type": "integer" }, "fields_removed": { "description": "Fields removed.", "examples": [ 1 ], "minimum": 0, "type": "integer" }, "records_added": { "description": "Records added.", "examples": [ 980 ], "minimum": 0, "type": "integer" }, "records_changed": { "description": "Records changed.", "examples": [ 212 ], "minimum": 0, "type": "integer" }, "records_removed": { "description": "Records removed.", "examples": [ 3 ], "minimum": 0, "type": "integer" }, "rows_added": { "deprecated": true, "description": "Deprecated name of `records_added`.", "examples": [ 980 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "rows_changed": { "deprecated": true, "description": "Deprecated name of `records_changed`.", "examples": [ 212 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "rows_removed": { "deprecated": true, "description": "Deprecated name of `records_removed`.", "examples": [ 3 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "values_changed": { "description": "Field values changed.", "examples": [ 212 ], "minimum": 0, "type": "integer" } }, "required": [ "cells_changed", "fields_added", "fields_changed", "fields_removed", "rows_added", "rows_changed", "rows_removed", "records_added", "records_removed", "records_changed", "values_changed" ], "type": "object" }, "RestoreRequest": { "additionalProperties": false, "description": "Every field is optional: an empty body restores the version.", "examples": [ { "dry_run": true } ], "properties": { "dry_run": { "description": "Report what the restore would change without writing anything. Default false.", "examples": [ false ], "type": "boolean" }, "expected_commit_id": { "description": "Refuse with `table_changed` unless this is still the table's newest history entry.", "examples": [ "commit_349a80d9fbf025a19ce8ff7b588d115b" ], "maxLength": 64, "minLength": 1, "type": "string" }, "if_unchanged_since": { "deprecated": true, "description": "Deprecated name of `expected_commit_id`; send one or the other.", "examples": [ "commit_349a80d9fbf025a19ce8ff7b588d115b" ], "maxLength": 64, "minLength": 1, "type": "string", "x-sunset": "2027-02-01" } }, "type": "object" }, "RestoreResult": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "cells_changed": { "deprecated": true, "description": "Deprecated name of `values_changed`.", "examples": [ 212 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "changed": { "description": "Whether the restore changes the table; false when it already equals the version.", "examples": [ true ], "type": "boolean" }, "commit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The history entry the restore made; null for a dry run or when nothing changed.", "examples": [ "commit_da351ef8de3782b2c6c7632fd2ae9945" ] }, "dry_run": { "description": "Whether this was a dry run that wrote nothing.", "examples": [ false ], "type": "boolean" }, "fields_added": { "description": "Fields added.", "examples": [ 2 ], "minimum": 0, "type": "integer" }, "fields_changed": { "description": "Fields changed.", "examples": [ 1 ], "minimum": 0, "type": "integer" }, "fields_removed": { "description": "Fields removed.", "examples": [ 1 ], "minimum": 0, "type": "integer" }, "object": { "const": "restore", "description": "Always `restore`.", "type": "string" }, "records_added": { "description": "Records added.", "examples": [ 980 ], "minimum": 0, "type": "integer" }, "records_changed": { "description": "Records changed.", "examples": [ 212 ], "minimum": 0, "type": "integer" }, "records_removed": { "description": "Records removed.", "examples": [ 3 ], "minimum": 0, "type": "integer" }, "rows_added": { "deprecated": true, "description": "Deprecated name of `records_added`.", "examples": [ 980 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "rows_changed": { "deprecated": true, "description": "Deprecated name of `records_changed`.", "examples": [ 212 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "rows_removed": { "deprecated": true, "description": "Deprecated name of `records_removed`.", "examples": [ 3 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "values_changed": { "description": "Field values changed.", "examples": [ 212 ], "minimum": 0, "type": "integer" }, "version_id": { "description": "The version the table was restored to.", "examples": [ "ver_commit_d42e4a6b3b74003ed5031158a1847494" ], "type": "string" } }, "required": [ "cells_changed", "fields_added", "fields_changed", "fields_removed", "rows_added", "rows_changed", "rows_removed", "object", "version_id", "changed", "dry_run", "commit_id", "records_added", "records_removed", "records_changed", "values_changed" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RoleAssignment": { "additionalProperties": false, "properties": { "roleKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member's custom role, or null.", "examples": [ null ] } }, "required": [ "roleKey" ], "type": "object" }, "RoleConfiguration": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "canDefineRoles": { "description": "Whether the plan allows custom roles.", "examples": [ true ], "type": "boolean" }, "privilegesApplicable": { "description": "The privileges a custom role can set on this plan.", "examples": [ [ "canInviteMembers", "canExport" ] ], "items": { "type": "string" }, "maxItems": 32, "type": "array" }, "roles": { "description": "The workspace's roles.", "items": { "properties": { "baseRole": { "description": "The built-in role this role is based on.", "enum": [ "admin", "creator", "editor", "viewer" ], "type": "string" }, "bundle": { "$ref": "#/components/schemas/RolePermissionBundle", "description": "What the role may do." }, "customised": { "description": "Whether this built-in role differs from its defaults.", "examples": [ false ], "type": "boolean" }, "defaultBundle": { "$ref": "#/components/schemas/RolePermissionBundle", "description": "What the built-in role may do by default." }, "key": { "description": "The role's key: a built-in role name or a custom role id.", "examples": [ "editor" ], "type": "string" }, "lockedSessionModes": { "description": "Chat modes this built-in role can never use.", "items": { "enum": [ "read_only", "ask", "full_access" ], "type": "string" }, "type": "array" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A custom role's name; null for a built-in role.", "examples": [ "Research analyst" ] } }, "required": [ "key", "name", "baseRole", "bundle", "defaultBundle", "customised", "lockedSessionModes" ], "type": "object" }, "maxItems": 35, "type": "array" }, "templates": { "description": "Starting points for a new custom role.", "items": { "properties": { "baseRole": { "description": "The built-in role this role is based on.", "enum": [ "admin", "creator", "editor", "viewer" ], "type": "string" }, "bundle": { "$ref": "#/components/schemas/RolePermissionBundle", "description": "What the role may do." }, "customised": { "description": "Whether this built-in role differs from its defaults.", "examples": [ false ], "type": "boolean" }, "defaultBundle": { "$ref": "#/components/schemas/RolePermissionBundle", "description": "What the built-in role may do by default." }, "key": { "description": "The role's key: a built-in role name or a custom role id.", "examples": [ "editor" ], "type": "string" }, "lockedSessionModes": { "description": "Chat modes this built-in role can never use.", "items": { "enum": [ "read_only", "ask", "full_access" ], "type": "string" }, "type": "array" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A custom role's name; null for a built-in role.", "examples": [ "Research analyst" ] } }, "required": [ "key", "name", "baseRole", "bundle", "defaultBundle", "customised", "lockedSessionModes" ], "type": "object" }, "maxItems": 1, "type": "array" } }, "required": [ "roles", "templates", "canDefineRoles", "privilegesApplicable" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RoleCreate": { "additionalProperties": false, "properties": { "baseRole": { "description": "The built-in role this role is based on.", "enum": [ "admin", "creator", "editor", "viewer" ], "type": "string" }, "name": { "description": "The custom role's name.", "examples": [ "Research analyst" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "name", "baseRole" ], "type": "object" }, "RoleMutation": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The written role's key; null when the write cleared a custom role.", "examples": [ "role_7c1f4e2a9b3d4c5e8f6a0b1c2d3e4f5a" ] }, "outcome": { "description": "The outcome, such as `valid`, `not_found` or `failed`.", "examples": [ "valid" ], "type": "string" } }, "required": [ "outcome", "key" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RolePermissionBundle": { "additionalProperties": false, "properties": { "allowedSessionModes": { "description": "The agent chat modes this role may use.", "items": { "enum": [ "read_only", "ask", "allow_session", "full_access" ] }, "type": "array" }, "canCreateApiKeys": { "description": "May create API user tokens.", "examples": [ false ], "type": "boolean" }, "canCreatePersonalAccessTokens": { "description": "May create personal tokens, a retired kind of key.", "examples": [ true ], "type": "boolean" }, "canDeleteWorkspace": { "description": "May delete the workspace.", "examples": [ false ], "type": "boolean" }, "canExport": { "description": "May export data out of the workspace.", "examples": [ true ], "type": "boolean" }, "canGrantApprovals": { "description": "May approve other members' held requests.", "examples": [ false ], "type": "boolean" }, "canInviteMembers": { "description": "May invite members.", "examples": [ false ], "type": "boolean" }, "canManageAgentAccess": { "description": "May change what agents may do.", "examples": [ false ], "type": "boolean" }, "canManageBilling": { "description": "May manage billing.", "examples": [ false ], "type": "boolean" }, "canManageIntegrations": { "description": "May connect and disconnect provider keys.", "examples": [ false ], "type": "boolean" }, "canManageTeam": { "description": "May manage members and roles.", "examples": [ false ], "type": "boolean" }, "maxRowsWithoutApproval": { "description": "Rows this role may run without approval.", "examples": [ 1000 ], "maximum": 4294967295, "minimum": 0, "type": "integer" }, "providerRowCaps": { "additionalProperties": { "maximum": 4294967295, "minimum": 0, "type": "integer" }, "description": "The most rows this role may run per provider.", "examples": [ { "appenda": 1000 } ], "type": "object" }, "providersAllowed": { "additionalProperties": { "type": "boolean" }, "description": "Which providers this role may run.", "examples": [ { "appenda": true } ], "type": "object" }, "toolClasses": { "additionalProperties": { "enum": [ "deny", "ask", "allow" ], "type": "string" }, "description": "What agents acting with this role may do, per tool: `deny`, `ask` or `allow`.", "examples": [ { "mutate_rows": "ask", "read_table": "allow" } ], "propertyNames": { "enum": [ "read_table", "mutate_rows", "table_admin", "schema", "view_layout", "list_import", "enrichment_paid", "fs", "terminal", "vc_mutate", "provider_write", "external_mcp_read", "external_mcp_write", "web" ] }, "type": "object" } }, "required": [ "allowedSessionModes", "toolClasses", "maxRowsWithoutApproval" ], "type": "object" }, "RoleUpdate": { "oneOf": [ { "additionalProperties": false, "properties": { "name": { "description": "A new name for a custom role.", "examples": [ "Research analyst" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, { "additionalProperties": false, "properties": { "bundle": { "$ref": "#/components/schemas/RolePermissionBundle", "description": "What the role may do." } }, "required": [ "bundle" ], "type": "object" } ] }, "RunGroupPreviewResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "approval_required": { "description": "Whether starting this run will be held for approval.", "examples": [ false ], "type": "boolean" }, "expires_at": { "description": "When the preview token stops working.", "examples": [ "2026-10-21T14:18:12.000Z" ], "format": "date-time", "type": "string" }, "max_calls": { "description": "The most provider calls the run may make.", "examples": [ 500 ], "maximum": 6000000, "minimum": 1, "type": "integer" }, "max_credits": { "description": "The most credits the run may spend.", "examples": [ 500 ], "maximum": 100000000, "minimum": 0, "type": "integer" }, "preview_token": { "description": "The token from the preview, valid for this exact request only. Anything changed since the preview is refused.", "examples": [ "pvw_v1.EXAMPLE-preview-token-not-a-real-value" ], "maxLength": 16384, "minLength": 1, "type": "string" }, "record_count": { "description": "Rows the widest stage may run; each stage's own bound is its max_calls.", "examples": [ 500 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "skipped": { "description": "Fields left out of the run because the workspace holds no key for their provider, each with the reason. The other fields still run; one that reads a skipped field no longer waits for it.", "examples": [ [ { "field_id": "fld_5a1c9e0d7b3f4e2a8c6d1b0e9f7a3c5d", "reason": "own_key_required" } ] ], "items": { "properties": { "field_id": { "description": "The field.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "reason": { "description": "Why the field was left out: `own_key_required` (its provider needs a key the workspace has not connected). New reasons can appear.", "enum": [ "own_key_required" ], "examples": [ "own_key_required" ] } }, "required": [ "field_id", "reason" ], "type": "object" }, "maxItems": 60, "minItems": 0, "type": "array" }, "stages": { "description": "The run's fields, in dependency order.", "items": { "$ref": "#/components/schemas/RunGroupPreviewStage" }, "maxItems": 60, "minItems": 1, "type": "array" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "preview_token", "expires_at", "table_id", "record_count", "max_calls", "max_credits", "approval_required", "stages" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RunGroupPreviewStage": { "properties": { "action": { "description": "The provider action.", "examples": [ "email_finder" ], "maxLength": 64, "minLength": 1, "type": "string" }, "billing_quote": { "anyOf": [ { "$ref": "#/components/schemas/BillingQuote" }, { "type": "null" } ], "description": "What the run may cost, or null when it runs on the workspace's own key." }, "configuration": { "$ref": "#/components/schemas/EnrichmentFieldConfig", "description": "The enrichment field's configuration." }, "credential_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, { "type": "null" } ], "description": "The key the stage will use, or null for Appenda's managed key.", "examples": [ null ] }, "depends_on": { "description": "The fields this one waits for.", "examples": [ [ "fld_1e57b877a78db86124936f976015f646" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 60, "minItems": 0, "type": "array", "uniqueItems": true }, "field_id": { "description": "The field.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "max_calls": { "description": "The most provider calls the run may make.", "examples": [ 500 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "max_credits": { "description": "The most credits the run may spend.", "examples": [ 500 ], "maximum": 100000000, "minimum": 0, "type": "integer" }, "method_id": { "deprecated": true, "description": "Deprecated: use `action`, the same value. The provider action.", "examples": [ "email_finder" ], "maxLength": 64, "minLength": 1, "type": "string" }, "provider": { "description": "The provider, as listed by List integrations.", "examples": [ "leadmagic" ], "maxLength": 64, "minLength": 1, "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`, the same value. The provider, as listed by List integrations.", "examples": [ "appenda" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "field_id", "depends_on", "provider_id", "method_id", "credential_id", "max_calls", "max_credits", "billing_quote", "configuration" ], "type": "object" }, "RunGroupResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "created_at": { "description": "When the multi-field run was started.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "credits_reserved": { "description": "Credits held for the run so far.", "examples": [ 500 ], "maximum": 100000000, "minimum": 0, "type": "integer" }, "id": { "description": "The multi-field run's id.", "examples": [ "group_56ff59d335d64643a037a602c9591144" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "stages": { "description": "The run's fields, in dependency order.", "items": { "$ref": "#/components/schemas/RunGroupStage" }, "maxItems": 60, "minItems": 1, "type": "array" }, "status": { "description": "The run's state: `pending`, `running`, `succeeded`, `stopped`, `partially_completed` or `failed`. New states can appear.", "enum": [ "pending", "running", "succeeded", "stopped", "needs_review", "partially_completed", "failed" ], "examples": [ "running" ], "type": "string" }, "stop_requested": { "description": "Whether a stop was requested.", "examples": [ false ], "type": "boolean" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "updated_at": { "description": "When the run or any of its fields last changed.", "examples": [ "2026-10-21T14:05:40.000Z" ], "format": "date-time", "type": "string" }, "workspace_id": { "description": "The workspace.", "examples": [ "ws_2e056e042c3953f816e10bb208432f9e" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "id", "workspace_id", "table_id", "stop_requested", "credits_reserved", "status", "stages", "created_at", "updated_at" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "RunGroupStage": { "properties": { "depends_on": { "description": "The fields this one waits for.", "examples": [ [ "fld_1e57b877a78db86124936f976015f646" ] ], "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 60, "minItems": 0, "type": "array", "uniqueItems": true }, "field_id": { "description": "The field.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "job_id": { "description": "The stage's run; read it with Get a run.", "examples": [ "job_d60ef6b2d188d2801bd33bf129195874" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "requested_rows": { "description": "Rows the run was asked to reach.", "examples": [ 500 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "status": { "description": "The stage's state, as for a run. New states can appear.", "enum": [ "pending", "running", "succeeded", "failed", "stopped", "needs_review" ], "examples": [ "succeeded" ], "type": "string" } }, "required": [ "field_id", "job_id", "depends_on", "status", "requested_rows" ], "type": "object" }, "RunOptions": { "description": "Which rows the run reaches and how.", "oneOf": [ { "additionalProperties": false, "properties": { "confirm_force": { "description": "Required true with force when calling with an API token: force re-runs rows that already have results and charges them again (force_confirmation_required otherwise).", "examples": [ false ], "type": "boolean" }, "force": { "description": "Run rows that already have a result too, overwriting it and charging again. Needs `confirm_force: true`.", "examples": [ false ], "type": "boolean" }, "mode": { "additionalProperties": false, "description": "Which rows the run reaches: `all`, the `first` N, or a `range` of rows.", "properties": { "kind": { "const": "all", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, "outcome_scope": { "description": "Run only rows whose last run ended this way: `stopped`, or an `error` of a given class.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "stopped", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "class": { "description": "Which failed rows to run again: `error_no_credits`, `error_provider` or `error_internal`.", "enum": [ "error_no_credits", "error_provider", "error_internal" ], "type": "string" }, "kind": { "const": "error", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" } ] }, "predicate_id": { "deprecated": true, "description": "Deprecated: ignored; leave it out.", "type": "null", "x-sunset": "2027-02-01" } }, "required": [ "mode", "force" ], "type": "object" }, { "additionalProperties": false, "properties": { "confirm_force": { "description": "Required true with force when calling with an API token: force re-runs rows that already have results and charges them again (force_confirmation_required otherwise).", "examples": [ false ], "type": "boolean" }, "force": { "description": "Run rows that already have a result too, overwriting it and charging again. Needs `confirm_force: true`.", "examples": [ false ], "type": "boolean" }, "mode": { "additionalProperties": false, "description": "Which rows the run reaches: `all`, the `first` N, or a `range` of rows.", "properties": { "count": { "description": "How many rows, from the first.", "examples": [ 500 ], "format": "int64", "minimum": 1, "type": "integer" }, "kind": { "const": "first", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "count", "kind" ], "type": "object" }, "outcome_scope": { "description": "Run only rows whose last run ended this way: `stopped`, or an `error` of a given class.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "stopped", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "class": { "description": "Which failed rows to run again: `error_no_credits`, `error_provider` or `error_internal`.", "enum": [ "error_no_credits", "error_provider", "error_internal" ], "type": "string" }, "kind": { "const": "error", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" } ] }, "predicate_id": { "deprecated": true, "description": "Deprecated: ignored; leave it out.", "type": "null", "x-sunset": "2027-02-01" } }, "required": [ "mode", "force" ], "type": "object" }, { "additionalProperties": false, "properties": { "confirm_force": { "description": "Required true with force when calling with an API token: force re-runs rows that already have results and charges them again (force_confirmation_required otherwise).", "examples": [ false ], "type": "boolean" }, "force": { "description": "Run rows that already have a result too, overwriting it and charging again. Needs `confirm_force: true`.", "examples": [ false ], "type": "boolean" }, "mode": { "additionalProperties": false, "description": "Which rows the run reaches: `all`, the `first` N, or a `range` of rows.", "properties": { "end": { "description": "The last row, from 1.", "examples": [ 600 ], "format": "int64", "minimum": 1, "type": "integer" }, "kind": { "const": "range", "description": "Which kind of object this is; each kind has its own fields." }, "start": { "description": "The first row, from 1.", "examples": [ 101 ], "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "end", "kind", "start" ], "type": "object" }, "outcome_scope": { "description": "Run only rows whose last run ended this way: `stopped`, or an `error` of a given class.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "stopped", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "class": { "description": "Which failed rows to run again: `error_no_credits`, `error_provider` or `error_internal`.", "enum": [ "error_no_credits", "error_provider", "error_internal" ], "type": "string" }, "kind": { "const": "error", "description": "Which kind of object this is; each kind has its own fields." } }, "required": [ "kind" ], "type": "object" } ] }, "predicate_id": { "deprecated": true, "description": "Deprecated: ignored; leave it out.", "type": "null", "x-sunset": "2027-02-01" } }, "required": [ "mode", "force" ], "type": "object" } ] }, "RunPage": { "description": "Your runs, newest first. Default 50 and maximum 100 per page; follow `next_cursor` until it is null.", "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/RunSummary" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "The cursor to the next page; null on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "RunSummary": { "description": "A run as List runs shows it. Get a run answers its progress and outcomes.", "properties": { "action": { "description": "The provider action the run calls.", "examples": [ "email_finder" ], "type": "string" }, "created_at": { "description": "When the run started.", "examples": [ "2026-10-21T14:03:12.000Z" ], "format": "date-time", "type": "string" }, "field_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The enrichment field the run fills.", "examples": [ "fld_1e57b877a78db86124936f976015f646" ] }, "id": { "description": "The run's id.", "examples": [ "job_f799d04594ff4df5347c941a1018d24f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "object": { "description": "Always `run`.", "enum": [ "run" ], "examples": [ "run" ], "type": "string" }, "provider": { "description": "The provider the run calls.", "examples": [ "leadmagic" ], "type": "string" }, "record_count": { "description": "The records the run was asked to enrich.", "examples": [ 250 ], "minimum": 0, "type": "integer" }, "requested_rows": { "deprecated": true, "description": "Deprecated: use `record_count`, which holds the same number.", "examples": [ 250 ], "minimum": 0, "type": "integer", "x-sunset": "2027-02-01" }, "status": { "description": "`queued` waits to start; `running` is in progress. `succeeded`, `failed`, `stopped` and `needs_review` (charge settling) are final; a stopped run keeps its results. New values may appear.", "enum": [ "queued", "running", "succeeded", "failed", "stopped", "needs_review" ], "examples": [ "succeeded" ], "type": "string" }, "stop_requested": { "description": "Whether a stop was asked for.", "examples": [ false ], "type": "boolean" }, "table_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The table the run writes to.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ] }, "updated_at": { "description": "When the run last changed.", "examples": [ "2026-10-21T14:05:40.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "object", "id", "status", "table_id", "provider", "action", "stop_requested", "created_at", "updated_at", "requested_rows", "field_id", "record_count" ], "type": "object" }, "SelectChoice": { "additionalProperties": false, "properties": { "color": { "description": "The choice's color.", "enum": [ "blue", "cyan", "teal", "green", "yellow", "orange", "red", "pink", "purple", "gray" ] }, "id": { "description": "The choice's id.", "examples": [ "choice_de52216fb6cddc1180542ac93880a6f0" ], "maxLength": 64, "minLength": 1, "type": "string" }, "name": { "description": "The choice as shown.", "examples": [ "Meeting booked" ], "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [ "color", "id", "name" ], "type": "object" }, "SelectConfig": { "additionalProperties": false, "description": "Choice IDs and case-folded names must be unique; trimmed names total at most 64 KiB.", "properties": { "choices": { "description": "The field's choices, in order, up to 500.", "items": { "$ref": "#/components/schemas/SelectChoice" }, "maxItems": 500, "type": "array" } }, "required": [ "choices" ], "type": "object" }, "SortKey": { "additionalProperties": false, "properties": { "direction": { "description": "The order: `asc` (smallest first) or `desc` (largest first).", "enum": [ "asc", "desc" ] }, "field_id": { "description": "The field to sort by.", "examples": [ "fld_5e8f73060c995895e07dfe7f6f6edd23" ], "maxLength": 64, "minLength": 1, "type": "string" }, "json_path": { "description": "For a JSON field, a pointer to the value to sort by, such as `/company/size`.", "examples": [ "/company/size" ], "maxLength": 256, "minLength": 1, "type": "string" } }, "required": [ "field_id", "direction" ], "type": "object" }, "SortSpec": { "additionalProperties": false, "description": "At most three distinct field IDs; nulls sort last and the API adds a deterministic unique record tie-breaker.", "examples": [ { "keys": [ { "direction": "desc", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23" } ] } ], "properties": { "keys": { "description": "The sort keys, first one first.", "items": { "$ref": "#/components/schemas/SortKey" }, "maxItems": 3, "type": "array" } }, "required": [ "keys" ], "type": "object" }, "SpendCap": { "additionalProperties": false, "description": "The most the run may spend: `max_credits` on Appenda's managed key, `max_rows` on the workspace's own key. Name `provider` and `action` together to refuse the run unless the field still runs that action.", "examples": [ { "max_credits": 500 } ], "properties": { "action": { "description": "The action the cap approves.", "examples": [ "email_finder" ], "maxLength": 64, "minLength": 1, "type": "string" }, "max_credits": { "description": "The most credits the run may spend; required for a run on Appenda's managed key.", "examples": [ 500 ], "maximum": 4294967295, "minimum": 1, "type": "integer" }, "max_rows": { "description": "The most rows the run may reach; required for a run on the workspace's own key.", "examples": [ 500 ], "maximum": 4294967295, "minimum": 1, "type": "integer" }, "method_id": { "deprecated": true, "description": "Deprecated: use `action`. The action the cap approves.", "examples": [ "email_finder" ], "maxLength": 64, "minLength": 1, "type": "string" }, "provider": { "description": "The provider the cap approves; with `action`, the cap holds only for that action.", "examples": [ "leadmagic" ], "maxLength": 64, "minLength": 1, "type": "string" }, "provider_id": { "deprecated": true, "description": "Deprecated: use `provider`. The provider the cap approves.", "examples": [ "appenda" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "type": "object" }, "StoredAggregateSeries": { "additionalProperties": false, "description": "Persisted local chart series budget. Network aggregate requests cap this at100.", "properties": { "field_id": { "description": "The field that splits each group into series.", "examples": [ "fld_4ac9744e5c4b96172195f7f2f070a486" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "json_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 6901 JSON pointer; a group path may end in /- to unnest one array.", "examples": [ "/company/size" ] }, "limit": { "anyOf": [ { "maximum": 1000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": 6, "description": "How many series to keep, 1 to 1,000.", "examples": [ 5 ] } }, "required": [ "field_id" ], "type": "object" }, "StoredAggregateSpec": { "additionalProperties": false, "description": "Persisted local analytical specification. Network execution additionally enforces its server-side result budget.", "properties": { "filter": { "anyOf": [ { "$ref": "#/components/schemas/FilterSpec" }, { "type": "null" } ], "description": "Only the records this filter keeps; null or omitted keeps every record." }, "group_by": { "anyOf": [ { "$ref": "#/components/schemas/AggregateGroup" }, { "type": "null" } ], "description": "The field to group by, or null for one total." }, "limit": { "description": "How many result rows to keep, 1 to 1,000.", "examples": [ 50 ], "maximum": 1000, "minimum": 1, "type": "integer" }, "metrics": { "description": "What to compute for each group, up to 8.", "items": { "$ref": "#/components/schemas/AggregateMetric" }, "maxItems": 8, "minItems": 1, "type": "array" }, "order": { "anyOf": [ { "$ref": "#/components/schemas/AggregateOrder" }, { "type": "null" } ], "description": "How to order the result rows, or null for group order." }, "series": { "anyOf": [ { "$ref": "#/components/schemas/StoredAggregateSeries" }, { "type": "null" } ], "description": "How each group splits into series." }, "source": { "$ref": "#/components/schemas/AggregateSource", "description": "Where the records come from." } }, "required": [ "source", "metrics", "limit" ], "type": "object" }, "Table": { "properties": { "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "dedupe": { "$ref": "#/components/schemas/TableDedupe", "description": "The table's deduplication setting." }, "forked_from": { "description": "The table and version this table was forked from.", "properties": { "table_id": { "description": "The table it was forked from.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "version_id": { "description": "The version it was forked from.", "examples": [ "ver_commit_d42e4a6b3b74003ed5031158a1847494" ], "type": "string" } }, "required": [ "table_id", "version_id" ], "type": "object" }, "id": { "description": "The table's id.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "name": { "description": "The table's name.", "examples": [ "Series B SaaS accounts" ], "maxLength": 80, "minLength": 1, "type": "string" }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "id", "name", "created_at", "updated_at" ], "type": "object" }, "TableBlockSource": { "description": "A saved view supplies its current filters and sorts; provide the chosen field IDs. Inline sources may use all fields or an explicit list.", "oneOf": [ { "additionalProperties": false, "properties": { "field_ids": { "description": "The fields the block shows, in order.", "examples": [ [ "fld_b00a97266f03cceb43636653c0e40b38", "fld_1e57b877a78db86124936f976015f646" ] ], "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 256, "type": "array", "uniqueItems": true }, "filter": { "anyOf": [ { "$ref": "#/components/schemas/FilterSpec" }, { "type": "null" } ], "description": "Only the records this filter keeps; null or omitted keeps every record." }, "page_size": { "default": 50, "description": "Records per page, 1 to 200.", "examples": [ 50 ], "maximum": 200, "minimum": 1, "type": "integer" }, "sort": { "anyOf": [ { "$ref": "#/components/schemas/SortSpec" }, { "type": "null" } ], "description": "The order of the records; omitted keeps table order." }, "source_view_id": { "description": "The view the page reads, or null for the whole table.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "type": "null" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "table_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "field_ids": { "description": "The fields the block shows, in order.", "examples": [ [ "fld_b00a97266f03cceb43636653c0e40b38", "fld_1e57b877a78db86124936f976015f646" ] ], "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 256, "minItems": 1, "type": "array", "uniqueItems": true }, "filter": { "description": "Only the records this filter keeps; null or omitted keeps every record.", "type": "null" }, "page_size": { "default": 50, "description": "Records per page, 1 to 200.", "examples": [ 50 ], "maximum": 200, "minimum": 1, "type": "integer" }, "sort": { "description": "The order of the records; omitted keeps table order.", "type": "null" }, "source_view_id": { "description": "The view the page reads, or null for the whole table.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "maxLength": 64, "minLength": 1, "type": "string" }, "table_id": { "description": "The table.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "table_id", "source_view_id", "field_ids" ], "type": "object" } ] }, "TableDedupe": { "description": "When on, a new record that matches a kept record on the first complete tier is dropped, or replaces it with `keep_newest`. Nothing merges.", "properties": { "enabled": { "description": "Whether deduplication is on.", "examples": [ true ], "type": "boolean" }, "keep_newest": { "description": "When a new record matches a kept one: true replaces the kept record, false drops the new one.", "examples": [ false ], "type": "boolean" }, "tiers": { "description": "Up to 5 groups of fields that identify a record, most trusted first. Records match on the first group whose fields all hold a value; values are normalized and blanks never match.", "examples": [ [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] ], "items": { "items": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array" }, "maxItems": 5, "minItems": 1, "type": "array" } }, "required": [ "enabled", "tiers", "keep_newest" ], "type": "object" }, "TableDedupeWrite": { "additionalProperties": false, "properties": { "enabled": { "description": "Whether deduplication is on.", "examples": [ true ], "type": "boolean" }, "keep_newest": { "default": false, "description": "When a new record matches a kept one: true replaces the kept record, false drops the new one.", "examples": [ false ], "type": "boolean" }, "tiers": { "description": "Up to 5 groups of fields, by id or key, that identify a record, most trusted first. Records match on the first group whose fields all hold a value; blanks never match.", "examples": [ [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] ], "items": { "items": { "maxLength": 128, "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array" }, "maxItems": 5, "minItems": 1, "type": "array" } }, "required": [ "enabled", "tiers" ], "type": "object" }, "TableMutation": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "dedupe": { "$ref": "#/components/schemas/TableDedupe", "description": "The table's deduplication setting." }, "id": { "description": "The table's id.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "name": { "description": "The table's name.", "examples": [ "Series B SaaS accounts" ], "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "id", "name" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "TablePage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/Table" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "TableResponse": { "properties": { "data": { "$ref": "#/components/schemas/Table", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "TableVersion": { "description": "A restorable version of a table: the table right after a history entry. Every version is kept for 7 days, then the newest of each day for 30 days; a table's newest version is always kept.", "properties": { "actor": { "description": "Who made the version's history entry.", "properties": { "api_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The API key the change was made with, or null when it was made in the app.", "examples": [ "ak_184992130055f27f212a3582fc736e9e" ] }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where it came from: `desktop`, `agent`, `api`, `mcp` or `cloud_worker`; null when unknown.", "examples": [ "api" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member who made it, or null when unknown.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ] } }, "required": [ "id", "channel", "api_key_id" ], "type": "object" }, "commit_id": { "description": "The history entry this version was captured at.", "examples": [ "commit_d42e4a6b3b74003ed5031158a1847494" ], "type": "string" }, "created_at": { "description": "When the version's history entry was made.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" }, "field_count": { "description": "Fields at this version.", "examples": [ 9 ], "minimum": 0, "type": "integer" }, "id": { "description": "The version's id.", "examples": [ "ver_commit_d42e4a6b3b74003ed5031158a1847494" ], "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The message of the entry this version was captured at, if any.", "examples": [ "Enriched 212 work emails" ] }, "object": { "const": "table_version", "description": "Always `table_version`.", "type": "string" }, "record_count": { "description": "Records at this version.", "examples": [ 212 ], "minimum": 0, "type": "integer" }, "ref": { "deprecated": true, "description": "Deprecated name of `short_id`.", "examples": [ "de6127v" ], "type": "string", "x-sunset": "2027-02-01" }, "restorable": { "description": "Whether the table can be restored or forked from this version.", "examples": [ true ], "type": "boolean" }, "short_id": { "description": "The history entry's short id, the same as its `short_id` in the history.", "examples": [ "de6127v" ], "type": "string" } }, "required": [ "object", "id", "commit_id", "short_id", "ref", "message", "created_at", "actor", "record_count", "field_count", "restorable" ], "type": "object" }, "TableVersionPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/TableVersion" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "TableVersionResponse": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "actor": { "description": "Who made the history entry.", "properties": { "api_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The API key the change was made with, or null when it was made in the app.", "examples": [ "ak_184992130055f27f212a3582fc736e9e" ] }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where it came from: `desktop`, `agent`, `api`, `mcp` or `cloud_worker`; null when unknown.", "examples": [ "api" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member who made it, or null when unknown.", "examples": [ "user_17e9c7164b4f3ae302c6b1dc88fc6b34" ] } }, "required": [ "id", "channel", "api_key_id" ], "type": "object" }, "commit_id": { "description": "The history entry this version was captured at.", "examples": [ "commit_d42e4a6b3b74003ed5031158a1847494" ], "type": "string" }, "created_at": { "description": "When the version's history entry was made.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" }, "field_count": { "description": "Fields at this version.", "examples": [ 9 ], "minimum": 0, "type": "integer" }, "fields": { "description": "The fields the table had at this version, in order.", "items": { "$ref": "#/components/schemas/HistoricalField" }, "maxItems": 1000, "type": "array" }, "id": { "description": "The version's id.", "examples": [ "ver_commit_d42e4a6b3b74003ed5031158a1847494" ], "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The message of the entry this version was captured at, if any.", "examples": [ "Enriched 212 work emails" ] }, "object": { "const": "table_version", "description": "Always `table_version`.", "type": "string" }, "record_count": { "description": "Records at this version.", "examples": [ 212 ], "minimum": 0, "type": "integer" }, "ref": { "deprecated": true, "description": "Deprecated name of `short_id`.", "examples": [ "de6127v" ], "type": "string", "x-sunset": "2027-02-01" }, "restorable": { "description": "Whether the table can be restored or forked from this version.", "examples": [ true ], "type": "boolean" }, "short_id": { "description": "The history entry's short id, the same as its `short_id` in the history.", "examples": [ "de6127v" ], "type": "string" } }, "required": [ "object", "id", "commit_id", "short_id", "ref", "message", "created_at", "actor", "record_count", "field_count", "restorable", "fields" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "TableWrite": { "additionalProperties": false, "properties": { "name": { "description": "The table's name.", "examples": [ "Series B SaaS accounts" ], "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "UrlOptions": { "additionalProperties": false, "properties": { "add_scheme": { "description": "Add `https://` to a URL without a scheme.", "examples": [ true ], "type": "boolean" }, "domain_only": { "description": "Keep only the domain of a URL.", "examples": [ false ], "type": "boolean" }, "linkedin_canonical": { "description": "Rewrite profile URLs to their canonical form.", "examples": [ true ], "type": "boolean" }, "strip_query": { "description": "Remove the query string from a URL.", "examples": [ true ], "type": "boolean" }, "strip_scheme": { "description": "Remove `https://` from a URL.", "examples": [ false ], "type": "boolean" }, "strip_trailing_slash": { "description": "Remove a trailing slash from a URL.", "examples": [ true ], "type": "boolean" }, "strip_www": { "description": "Remove `www.` from a URL.", "examples": [ true ], "type": "boolean" } }, "required": [], "type": "object" }, "ValueFormat": { "oneOf": [ { "additionalProperties": false, "properties": { "precision": { "anyOf": [ { "maximum": 20, "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Decimal places, 0 to 20, or null for the default.", "examples": [ 2 ] }, "style": { "const": "number", "description": "How the number is shown: a plain `number`, a `percent`, a `currency` or a `duration_ms`." } }, "required": [ "style" ], "type": "object" }, { "additionalProperties": false, "properties": { "precision": { "anyOf": [ { "maximum": 20, "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Decimal places, 0 to 20, or null for the default.", "examples": [ 2 ] }, "style": { "const": "percent", "description": "How the number is shown: a plain `number`, a `percent`, a `currency` or a `duration_ms`." } }, "required": [ "style" ], "type": "object" }, { "additionalProperties": false, "properties": { "currency": { "description": "The currency: an ISO 4217 code, or a symbol of up to eight bytes for display.", "examples": [ "USD" ], "pattern": "^[A-Z]{3}$", "type": "string" }, "precision": { "anyOf": [ { "maximum": 20, "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Decimal places, 0 to 20, or null for the default.", "examples": [ 2 ] }, "style": { "const": "currency", "description": "How the number is shown: a plain `number`, a `percent`, a `currency` or a `duration_ms`." } }, "required": [ "style", "currency" ], "type": "object" }, { "additionalProperties": false, "properties": { "style": { "const": "duration_ms", "description": "How the number is shown: a plain `number`, a `percent`, a `currency` or a `duration_ms`." } }, "required": [ "style" ], "type": "object" } ] }, "ViaAgent": { "additionalProperties": false, "description": "The agent tool that sent this request for you. The request is then decided under your role as an agent tool's: where your role asks before agents spend, it answers `approval_required` instead of running.", "properties": { "kind": { "description": "The agent tool: `claude_code`, `codex` or `cursor`. Any other value is refused.", "enum": [ "claude_code", "codex", "cursor", "gemini", "github_copilot", "grok", "antigravity" ], "examples": [ "claude_code" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "View": { "properties": { "created_at": { "description": "When it was created.", "examples": [ "2026-09-14T09:12:44.000Z" ], "format": "date-time", "type": "string" }, "filter": { "anyOf": [ { "$ref": "#/components/schemas/PublicFilter" }, { "$ref": "#/components/schemas/FilterSpec" } ], "description": "Only the records this filter keeps; null or omitted keeps every record." }, "id": { "description": "The view's id.", "examples": [ "view_a013e65c011b856c46e9d282545f1211" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "is_default": { "description": "Whether this is the table's default view, which cannot be renamed, changed or deleted.", "examples": [ false ], "type": "boolean" }, "name": { "description": "The view's name.", "examples": [ "Hot leads" ], "type": "string" }, "object": { "const": "view", "description": "Always `view`.", "type": "string" }, "sort": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicSortKey" }, "maxItems": 3, "type": "array" }, { "$ref": "#/components/schemas/SortSpec" } ], "description": "The order of the records; omitted keeps table order." }, "table_id": { "description": "The table the view belongs to.", "examples": [ "tbl_67ad65ba34a7bbfc643711b8531cba3f" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "updated_at": { "description": "When it last changed.", "examples": [ "2026-10-21T13:58:02.000Z" ], "format": "date-time", "type": "string" } }, "required": [ "object", "id", "table_id", "name", "is_default", "filter", "sort" ], "type": "object" }, "ViewCreate": { "additionalProperties": false, "properties": { "filter": { "anyOf": [ { "$ref": "#/components/schemas/PublicFilter" }, { "$ref": "#/components/schemas/FilterSpec" } ], "description": "Only the records this filter keeps; null or omitted keeps every record." }, "name": { "description": "The view's name, 1 to 64 characters after trimming.", "examples": [ "Hot leads" ], "maxLength": 256, "minLength": 1, "type": "string" }, "sort": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicSortKey" }, "maxItems": 3, "type": "array" }, { "$ref": "#/components/schemas/SortSpec" } ], "description": "The order of the records; omitted keeps table order." } }, "required": [ "name" ], "type": "object" }, "ViewDuplicate": { "additionalProperties": false, "description": "Without a name the copy is named `Copy of `.", "examples": [ { "name": "Hot leads (EMEA)" } ], "properties": { "name": { "description": "The copy's name. Defaults to `Copy of `.", "examples": [ "Hot leads (EMEA)" ], "maxLength": 256, "minLength": 1, "type": "string" } }, "required": [], "type": "object" }, "ViewMutation": { "properties": { "data": { "$ref": "#/components/schemas/View", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "ViewPage": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "items": { "$ref": "#/components/schemas/View" }, "maxItems": 100, "type": "array" }, "meta": { "description": "Paging for a list: `next_cursor` and `has_more`; a bulk write's counts.", "properties": { "has_more": { "description": "Whether `next_cursor` names another page.", "examples": [ false ], "type": "boolean" }, "next_cursor": { "anyOf": [ { "maxLength": 16384, "type": "string" }, { "type": "null" } ], "description": "An opaque cursor bound to this list and its filters; `null` on the last page.", "examples": [ null ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" }, "ViewResponse": { "properties": { "data": { "$ref": "#/components/schemas/View", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "ViewUpdate": { "additionalProperties": false, "description": "At least one property. A rename adds an entry to version history; a filter or sort change alone does not.", "examples": [ { "name": "Hot leads EMEA" } ], "properties": { "filter": { "anyOf": [ { "$ref": "#/components/schemas/PublicFilter" }, { "$ref": "#/components/schemas/FilterSpec" } ], "description": "Only the records this filter keeps; null or omitted keeps every record." }, "name": { "description": "A new name, 1 to 64 characters after trimming.", "examples": [ "Hot leads" ], "maxLength": 256, "minLength": 1, "type": "string" }, "sort": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PublicSortKey" }, "maxItems": 3, "type": "array" }, { "$ref": "#/components/schemas/SortSpec" } ], "description": "The order of the records; omitted keeps table order." } }, "required": [], "type": "object" }, "Waterfall": { "description": "A waterfall field: steps tried in order, stopping at the first accepted result.", "properties": { "config": { "description": "The waterfall's capability, inputs and steps.", "properties": { "capability": { "description": "What every step finds.", "examples": [ "email_finder" ], "type": "string" }, "inputs": { "description": "The capability's inputs, each read from a field by key.", "examples": [ { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "full_name": { "field": "full_name" }, "last_name": { "field": "last_name" } } ], "type": "object" }, "max_credits_per_row": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The per-record credit cap checked when the steps were saved.", "examples": [ null ] }, "steps": { "description": "The steps in order.", "items": { "properties": { "accept": { "description": "The results that stop the waterfall at this step.", "examples": [ [ "valid", "catch_all" ] ], "items": { "type": "string" }, "type": "array" }, "action": { "description": "The action's id.", "examples": [ "email_finder" ], "type": "string" }, "credential": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workspace key the step runs with; null for the provider's default key.", "examples": [ "cred_971e3efd6924ee8db473896da8f1c630" ] }, "credits_per_call": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Credits one call spends: 0 on the workspace's own key, the action's price on Appenda's.", "examples": [ 2 ] }, "id": { "description": "The step's id.", "examples": [ "fld_7aa2ec62bf3badc48f63684017b448ef" ], "type": "string" }, "inputs": { "description": "The action's inputs, each read from a field by key.", "examples": [ { "firstname": { "field": "first_name" } } ], "type": "object" }, "object": { "description": "Always `waterfall_step`.", "enum": [ "waterfall_step" ], "examples": [ "waterfall_step" ], "type": "string" }, "position": { "description": "The step's place in the order, from 1.", "examples": [ 1 ], "type": "integer" }, "provider": { "description": "The integration's id.", "examples": [ "icypeas" ], "type": "string" } }, "type": "object" }, "type": "array" }, "stop_on": { "description": "Always `first_accepted`: later steps run only while no earlier step gave an accepted result. A lost answer stops the record.", "examples": [ "first_accepted" ], "type": "string" } }, "type": "object" }, "id": { "description": "The merged field's id.", "examples": [ "fld_c0b164fe5c18cba45982317d1144de3e" ], "type": "string" }, "key": { "description": "The merged field's key.", "examples": [ "work_email" ], "type": "string" }, "name": { "description": "The merged field's name.", "examples": [ "Work email" ], "type": "string" }, "object": { "description": "Always `field`.", "enum": [ "field" ], "examples": [ "field" ], "type": "string" }, "position": { "description": "The field's place among the table's fields.", "examples": [ 7 ], "type": "integer" }, "type": { "description": "Always `waterfall`.", "enum": [ "waterfall" ], "examples": [ "waterfall" ], "type": "string" } }, "required": [ "object", "id", "type", "config" ], "type": "object" }, "WaterfallCreate": { "additionalProperties": false, "description": "A waterfall: provider actions for one capability, tried in order until one gives an accepted result.", "properties": { "capability": { "description": "What every step finds: `email_finder`, `phone_finder` or `email_validation`.", "examples": [ "email_finder" ], "type": "string" }, "dry_run": { "description": "Check the waterfall and answer it without creating anything. Defaults to false.", "examples": [ false ], "type": "boolean" }, "inputs": { "additionalProperties": { "additionalProperties": false, "properties": { "field": { "description": "The key of the field to read.", "examples": [ "first_name" ], "type": "string" } }, "required": [ "field" ], "type": "object" }, "description": "The capability's inputs, each read from a field by key.", "examples": [ { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "full_name": { "field": "full_name" }, "last_name": { "field": "last_name" } } ], "type": "object" }, "max_credits_per_row": { "description": "The most credits one record may spend across the steps; required when a step spends Appenda credits.", "examples": [ 4 ], "type": "number" }, "name": { "description": "The merged field's name.", "examples": [ "Work email" ], "maxLength": 80, "minLength": 1, "type": "string" }, "steps": { "description": "The steps in the order they are tried: 2 to 8, each a different action.", "examples": [ [ { "action": "email_finder", "provider": "icypeas" }, { "action": "email_finder", "credential": "cred_971e3efd6924ee8db473896da8f1c630", "provider": "findymail" } ] ], "items": { "$ref": "#/components/schemas/WaterfallStepWrite" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "name", "capability", "inputs", "steps" ], "type": "object" }, "WaterfallResponse": { "properties": { "data": { "$ref": "#/components/schemas/Waterfall", "description": "The object or list of objects this operation returns." } }, "required": [ "data" ], "type": "object" }, "WaterfallStepWrite": { "additionalProperties": false, "description": "A step: a new one names `provider` and `action`; a kept one is named by `id` alone.", "properties": { "accept": { "description": "The results that stop the waterfall at this step; the capability's default when left out.", "examples": [ [ "valid", "catch_all" ] ], "items": { "type": "string" }, "type": "array" }, "action": { "description": "An action that declares the waterfall's capability.", "examples": [ "email_finder" ], "type": "string" }, "credential": { "deprecated": true, "description": "Deprecated: use `credential_id`. One of the workspace's own keys for the provider.", "examples": [ "cred_971e3efd6924ee8db473896da8f1c630" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "credential_id": { "description": "One of the workspace's own keys for the provider; its default key when left out.", "examples": [ "cred_971e3efd6924ee8db473896da8f1c630" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "id": { "description": "A step the waterfall already has, to keep it; left out to add a step.", "examples": [ "fld_78edafc0ed9045ae7250f043e9894baa" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" }, "provider": { "description": "The integration's id.", "examples": [ "leadmagic" ], "type": "string" } }, "required": [], "type": "object" }, "WaterfallUpdate": { "additionalProperties": false, "description": "A waterfall's full ordered list of steps.", "properties": { "dry_run": { "description": "Check the change and answer it without saving it. Defaults to false.", "examples": [ false ], "type": "boolean" }, "max_credits_per_row": { "description": "The most credits one record may spend across the steps; required when a step spends Appenda credits.", "examples": [ 4 ], "type": "number" }, "steps": { "description": "Every step in order: kept by `id`, added without one; steps left out are removed. 2 to 8, each a different action.", "examples": [ [ { "id": "fld_7aa2ec62bf3badc48f63684017b448ef" }, { "action": "email_finder", "provider": "icypeas" } ] ], "items": { "$ref": "#/components/schemas/WaterfallStepWrite" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "steps" ], "type": "object" }, "WorkspaceCreate": { "additionalProperties": false, "description": "A new workspace in this instance. The caller names its id (a replay of the same id answers 200); the owner is not the client's to choose.", "properties": { "name": { "description": "The workspace's name.", "examples": [ "Northbeam EMEA" ], "maxLength": 255, "minLength": 1, "type": "string" }, "workspaceId": { "description": "The new workspace's id, chosen by you; sending the same id again returns the same workspace.", "examples": [ "ws_068ceadbd4d62272d7c97b97258e72eb" ], "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, "required": [ "workspaceId", "name" ], "type": "object" }, "WorkspaceCreated": { "properties": { "data": { "description": "The object or list of objects this operation returns.", "properties": { "instanceId": { "description": "The instance.", "examples": [ "inst_9e815b66d1186bb90d2d77fbd69009df" ], "type": "string" }, "ownerUserId": { "description": "The instance owner for a token's create; the creating instance admin for a session's.", "examples": [ "user_1ccece3aa6e3f736614f0238ca636876" ], "type": "string" }, "workspaceId": { "description": "The new workspace's id.", "examples": [ "ws_068ceadbd4d62272d7c97b97258e72eb" ], "type": "string" } }, "required": [ "workspaceId", "instanceId", "ownerUserId" ], "type": "object" } }, "required": [ "data" ], "type": "object" } }, "securitySchemes": { "bearer": { "description": "An API user token or a super-admin token, sent as `Authorization: Bearer `. See [Authentication](#description/authentication).", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "Product guides", "url": "https://appenda.app/docs" }, "info": { "description": "Appenda's API reads and changes the tables, records and enrichment runs in your workspace. Every request is HTTPS, sends JSON and answers JSON.\n\n## Quickstart\n\n1. Create an API key: sign in at [appenda.app/account](https://appenda.app/account), pick the workspace and choose **Create key**. Copy the secret; it is shown once. The key reaches that workspace only.\n2. List the workspace's tables:\n\n```bash\ncurl https://api.appenda.app/v1/tables \\\n -H \"Authorization: Bearer $APPENDA_API_KEY\"\n```\n\n3. Read the reply. Lists answer `data` plus `meta` (see [Pagination](#description/pagination)):\n\n```json\n{\n \"data\": [\n { \"id\": \"tbl_67ad65ba34a7bbfc643711b8531cba3f\", \"name\": \"Series B SaaS accounts\", \"created_at\": \"2026-09-14T09:12:44.000Z\", \"updated_at\": \"2026-10-21T13:58:02.000Z\" }\n ],\n \"meta\": { \"next_cursor\": null, \"has_more\": false }\n}\n```\n\n## Authentication\n\nSend a key in the `Authorization` header: `Authorization: Bearer `. Keys work over HTTPS only and never in a query string.\n\nThere are two types of key (`appenda_sk_live_…`), and no others:\n\n- **API user token** (`api-user`, recommended): reaches one workspace and acts as the member who created it, with that member's current role, admin settings included. It stops working when the member leaves.\n- **Super-admin token** (`super-admin`, developer use only): reaches every workspace of the instance and acts as an Admin in each, while the instance administrator who created it stays one. It names its workspace with the `Appenda-Workspace` header.\n\nKeys made before these two types existed are listed as API user tokens; personal tokens can no longer be created.\n\nKeys have no scopes: what a key may do follows from its type and its owner's role. An operation a kind cannot call says so in its description. Create and revoke keys with the [API keys](#tag/api-keys) operations or on your account page. If a key leaks, revoke it at once and create a new one; a revoked key is refused immediately.\n\n## Conventions\n\n- **Base URL:** `https://api.appenda.app/v1`. Every path in this reference is written from the host and includes the version, so `/v1/tables` is `https://api.appenda.app/v1/tables`. The workspace comes from the key, never from the path; a super-admin key names it with the `Appenda-Workspace` header.\n- **Ids** are opaque strings such as `tbl_67ad65ba34a7bbfc643711b8531cba3f`: a type prefix and a random part. An object made in the desktop app keeps the id it was made with (`table_…`, `record_…`), so do not parse ids or match their prefix or length. An id from another workspace answers 404, the same as one that does not exist.\n- **Timestamps** are RFC 3339 strings in UTC, such as `2026-10-21T14:03:12.000Z`.\n- **Missing values** are `null`. Numbers and booleans are JSON numbers and booleans.\n- **Names are snake_case**: properties, query parameters and enum values (`created_at`, `single_select`). A request key spelled camelCase is refused with `422`, except on the older `/api/v1/…` paths, which keep their own names until they move.\n- **Single objects** answer `{\"data\": {…}}`. Nothing else sits beside `data` except `meta`: list paging, or a bulk write's counts (`created`, `skipped`, `replaced`).\n- **Requests** are `application/json`, at most 16 levels deep and at most 96 KiB, on every operation. A larger body answers `413`. An unknown field is refused.\n- **Responses grow.** New fields and new enum values can appear at any time. Ignore what you do not know. A breaking change is deprecated first and keeps working until its Sunset date; see [Versioning](https://appenda.app/docs/api/versioning).\n- **Download this spec** as [openapi.json](https://api.appenda.app/v1/openapi.json) or [openapi.yaml](https://api.appenda.app/v1/openapi.yaml).\n- **Approvals:** a request from an API user token whose role requires approval is held instead of run. It answers the operation's usual status with an approval to poll, named in `Location`; see [Approvals](#tag/approvals).\n\n## Pagination\n\nList operations return up to 50 items, or `limit` items up to 100, as `{\"data\": […], \"meta\": {\"next_cursor\": …, \"has_more\": …}}`. When `meta.has_more` is true, pass `meta.next_cursor` as `cursor` to get the next page, and stop when it is `null`. A record page can hold fewer than `limit` items even when `meta.has_more` is true, because it stops near 4 MiB, so keep following `meta.next_cursor`. A cursor works only with the operation and filters that produced it. Pages follow a stable order, but edits made while you page can move items between pages.\n\n## Errors\n\nA refused request answers `application/json` with one `error` object:\n\n```json\n{\n \"error\": {\n \"status\": 422,\n \"code\": \"invalid_request\",\n \"message\": \"A value in the request breaks a rule; param names the field. Fix that value and retry.\",\n \"param\": \"name\",\n \"docs_url\": \"https://appenda.app/docs/api/errors#invalid_request\",\n \"request_id\": \"req_1888ee34e3fa99e71430e3072c54c339\"\n }\n}\n```\n\nBranch on `code`, never on `message`. `param` names the field at fault, or is `null`. `request_id` is also sent as `X-Request-Id` on every response; quote it when you contact support. A `401` also carries `WWW-Authenticate`, a `405` carries `Allow`, and a `429`, `503` or `504` carries `Retry-After`.\n\n| Status | Code | Message |\n|---|---|---|\n| 400 | `credentials_in_query` | Send credentials in the Authorization header, never in the URL. Rotate a credential sent in a URL. |\n| 400 | `https_required` | Use HTTPS for this request. Plain HTTP is refused instead of redirected. |\n| 400 | `idempotency_key_invalid` | The Idempotency-Key header must be 1 to 200 visible ASCII characters. Fix the header and retry. |\n| 400 | `workspace_required` | This key works across workspaces. Send the Appenda-Workspace header naming the workspace and retry. |\n| 401 | `unauthorized` | The credential is missing, unknown, expired or revoked. Send a valid API key, or sign in again. |\n| 402 | `insufficient_credits` | The workspace doesn't have enough credits for this run. Buy credits or lower the run's size, then retry. |\n| 402 | `subscription_inactive` | The workspace's plan isn't active: its subscription is unpaid, paused or cancelled. Pay in Billing. The same key works again once the workspace reopens. |\n| 403 | `approval_required` | Your role needs an Admin's approval for this action. Ask an Admin to approve the request. |\n| 403 | `forbidden` | Your role or key can't call this operation in this workspace. Ask a workspace Admin for access. |\n| 403 | `instance_unavailable` | This Appenda account isn't available. Contact support with the request id. |\n| 403 | `key_paused` | This API key was paused because it spent far more than usual. A workspace admin can un-pause it. |\n| 403 | `plan_not_active` | This workspace's plan isn't active. Renew or reactivate the plan in Billing, then retry. |\n| 403 | `plan_required` | This workspace's plan doesn't include this feature. Upgrade the plan to use it. |\n| 403 | `plan_upgrade_required` | This integration needs a higher plan. Upgrade the workspace's plan to use it. |\n| 403 | `region_not_offered` | That data region isn't offered on this plan. Pick an offered region or upgrade the plan. |\n| 403 | `role_change_denied` | Your role can't change Settings → Permissions. Ask a workspace Owner or Admin to make the change. |\n| 403 | `trial_card_required` | People and Company Search on a trial need a card on file. Add a card in Billing, or choose a plan. |\n| 403 | `trial_search_limit_reached` | This trial has used all its People and Company Search records. Choose a plan to keep searching. |\n| 403 | `workspace_limit_reached` | Your plan's workspace limit is reached. Delete a workspace or upgrade the plan to create another. |\n| 403 | `workspace_mismatch` | This key belongs to a different workspace. Use a key from this workspace, or drop the Appenda-Workspace header. |\n| 404 | `not_found` | The object doesn't exist in this workspace, or you can't see it. Check the id and the workspace. |\n| 404 | `version_not_found` | No version with this id exists for the table. List the table's versions to find the id. |\n| 405 | `method_not_allowed` | This path doesn't serve that HTTP method. Use one of the methods in the Allow header. |\n| 408 | `request_timeout` | The request body arrived too slowly. Send it again in one go. |\n| 409 | `admin_locked` | The Admin role's permissions can't be changed. |\n| 409 | `approval_stale` | The approved request no longer matches what would run. Send the request again for a new approval. |\n| 409 | `conflict` | The request conflicts with the object's current state. Read the object again, then retry. |\n| 409 | `dedupe_too_many_matches` | More than one record matches the dedupe key. Make the key unique or update the records by id. |\n| 409 | `dedupe_unchanged` | The table already uses these dedupe settings, so nothing changed. |\n| 409 | `enrichment_already_running` | A run is already in progress on this field. Wait for it to finish or stop it first. |\n| 409 | `enrichment_config_changed` | The field this run uses was deleted or changed after you set up the run. Nothing ran. Set up the run again. |\n| 409 | `enrichment_paused` | Enrichment is paused for this workspace. Resume it in the app, then retry. |\n| 409 | `field_key_conflict` | A field with this key already exists with a different type. Choose another key or delete the old field. |\n| 409 | `idempotency_key_reused` | This Idempotency-Key was already used for a different request. Use a new key for a new request. |\n| 409 | `import_fields_changed` | The table's fields changed during the import. Start the import again. |\n| 409 | `import_finished` | The import already finished. Start a new import to add more rows. |\n| 409 | `integration_connected` | An integration with this name is already connected. Use the existing connection or remove it first. |\n| 409 | `job_finished` | The run already finished, so there is nothing to stop. |\n| 409 | `monthly_spend_cap_exceeded` | The workspace reached its monthly spend cap. Raise the cap in Billing or wait for the next month. |\n| 409 | `not_ended` | The import is still running. Wait for it to end, then retry. |\n| 409 | `preview_stale` | The table changed since the preview. Preview again, then confirm. |\n| 409 | `quote_mismatch` | The import quote no longer matches the request. Ask for a new quote and confirm it. |\n| 409 | `role_limit_reached` | The workspace has the most custom roles allowed. Delete a role before adding another. |\n| 409 | `role_name_taken` | A role with this name already exists. Choose another name. |\n| 409 | `role_protected` | Built-in roles can't be renamed or deleted. |\n| 409 | `route_model_unsupported` | This workspace can't serve the request yet. Update the app and retry. |\n| 409 | `route_stale` | The workspace moved to another region. Retry the request. |\n| 409 | `run_group_preview_stale` | The run group changed since its preview. Preview the run group again, then start it. |\n| 409 | `schema_version_mismatch` | The table's schema changed. Read the table again, then retry. |\n| 409 | `schema_version_stale` | The action's parameters changed incompatibly since that schema_version. Read them again and rebuild the inputs. |\n| 409 | `selection_changed` | The records you confirmed changed before the run started. Preview again and confirm the new count. |\n| 409 | `sole_owner` | You're the only Owner of a shared workspace. Make someone else an Owner first. |\n| 409 | `spend_cap_exceeded` | This run would spend more than its cap allows. Raise the cap or run fewer records. |\n| 409 | `table_changed` | The table changed after the history entry named in if_unchanged_since. Read its history and try again. |\n| 409 | `transcript_head_mismatch` | The transcript has moved on since these events were sent. Send them again from the head this error names. |\n| 409 | `upstream_not_run` | A field this field reads has rows it has not run yet. Run that field first, or run both in one run group. |\n| 409 | `view_name_conflict` | A view with this name already exists on the table. Choose another name. |\n| 409 | `workspace_create_conflict` | A workspace is already being created with this request. Wait a moment, then list your workspaces. |\n| 409 | `workspace_delete_blocked` | The workspace can't be deleted while it has an active subscription or other members. Resolve those first. |\n| 409 | `workspace_unprovisioned` | The workspace has no cloud copy yet. Sync it from the desktop app first. |\n| 410 | `token_type_retired` | Personal access tokens are retired. Create an API user token instead. |\n| 413 | `batch_too_large` | Too much to write at once. Split the request into smaller batches. |\n| 413 | `fork_too_large` | The version has more records than one copy allows. Copy a smaller table or version. |\n| 413 | `import_too_large` | The file is larger than one import allows. Split it into smaller files. |\n| 413 | `payload_too_large` | The request body is larger than the API accepts. Send a smaller body. |\n| 413 | `response_too_large` | The answer would be larger than this operation can send. Ask for fewer records or fields. |\n| 413 | `restore_too_large` | The restore would change more records than one restore allows. Restore a narrower version. |\n| 413 | `run_group_too_large` | The run group has more fields than one run allows. Split it into smaller groups. |\n| 415 | `unsupported_media_type` | The request body must be JSON. Send it with Content-Type: application/json. |\n| 421 | `residency_mismatch` | The request reached the wrong data region. Send it to the workspace's own region. |\n| 422 | `agent_bot_limit_reached` | Your plan holds at most this many bots in a workspace. Delete a bot or upgrade to add another. |\n| 422 | `agent_memory_limit_reached` | Memory is full for this scope: delete some or keep fewer. |\n| 422 | `aggregate_formula_override` | A chart can't override a formula field's calculation. Remove the override. |\n| 422 | `cell_invalid` | A cell value doesn't fit its field; param names the field. Send a value the field accepts. |\n| 422 | `condition_must_be_boolean` | A run condition must be a true/false formula. Change it to a formula that returns true or false. |\n| 422 | `constant_not_allowed` | The input doesn't take that kind of value; param names it. Bind it the way its accepts list allows. |\n| 422 | `credential_not_applicable` | This method runs inside Appenda and takes no credential. Leave the credential out. |\n| 422 | `credential_not_found` | The credential doesn't exist for this provider in this workspace. List credentials and pick one, or leave it out. |\n| 422 | `credential_shape_unsupported` | This provider doesn't take one pasted API key. Connect it in the desktop app instead. |\n| 422 | `credits_unavailable` | This step's action can't run on Appenda credits; param names it. Use the workspace's own key. |\n| 422 | `custom_http_configuration_unsupported` | HTTP request fields can't be created with an API key yet. Create them in the app. |\n| 422 | `custom_http_key_reentry_required` | A Cloud HTTP request column's key must be saved again for this endpoint before it can run. Re-save the key in the app. |\n| 422 | `digest_mismatch` | The uploaded content doesn't match its digest. Upload it again. |\n| 422 | `endpoint_not_allowed` | The URL isn't allowed: use a public https address with no credentials in it. |\n| 422 | `enrichment_field_limit` | The table already has as many enrichment fields as it allows. Delete one before adding another. |\n| 422 | `field_config_invalid` | The field's config doesn't fit its type. Fix the config and retry. |\n| 422 | `field_conversion_required` | This change rewrites the field's values. Send it again with convert set to true; a dry run shows what changes first. |\n| 422 | `field_conversion_too_large` | The field holds too many values to convert in one request. Create a new field of the type you want instead. |\n| 422 | `field_limit_reached` | The table has the most fields allowed. Delete a field before adding another. |\n| 422 | `field_not_found` | A field the request names doesn't exist in this table. Check the field ids. |\n| 422 | `field_read_only` | Formula and lookup fields are calculated, so their cells can't be written. Remove them from the request. |\n| 422 | `field_type_change_unsupported` | A field can't change to that type. Create a new field of the type you want instead. |\n| 422 | `field_type_mismatch` | A value doesn't fit its field's type. Send a value of the field's type. |\n| 422 | `field_type_unsupported` | The API can't create or edit fields of this type. Use the desktop app for this field type. |\n| 422 | `force_confirmation_required` | Re-running records that already have values needs confirmation. Send confirm_force: true with force: true. |\n| 422 | `formula_invalid` | The formula doesn't parse or names a field that doesn't exist. Fix the formula and retry. |\n| 422 | `formula_read_only` | A run condition written as a formula can only be read. Send it as rules. |\n| 422 | `interface_invalid` | The interface definition isn't valid; param names the part at fault. Fix it and save again. |\n| 422 | `interface_limit_reached` | The workspace has the most interfaces allowed. Delete an interface before adding another. |\n| 422 | `invalid_enrichment_config` | The enrichment field's configuration isn't valid. Edit the field's settings and save again. |\n| 422 | `invalid_request` | A value in the request breaks a rule; param names the field. Fix that value and retry. |\n| 422 | `invalid_shared_interface` | This interface can't be shared as it is. Fix its blocks, then share it again. |\n| 422 | `invalid_waterfall` | The waterfall isn't valid; param names the part at fault and reason says why. Fix it and save again. |\n| 422 | `matching_import_requires_atomic_batch` | An import that matches existing records must run as one batch. Send it without chunking. |\n| 422 | `matching_import_requires_existing_fields` | An import that matches existing records can only use fields the table already has. Map columns to existing fields. |\n| 422 | `max_credits_per_row_required` | A step spends Appenda credits, so the waterfall needs max_credits_per_row. Add a cap. |\n| 422 | `missing_one_of` | None of an input group's alternatives is given. Add one set of inputs from requires.one_of. |\n| 422 | `missing_required` | A required input is missing; param names it. Add it and retry. |\n| 422 | `no_eligible_rows` | No records match what the request selects. Change the filter or selection. |\n| 422 | `numeric_overflow` | A number is outside the range its field can hold. Send a smaller number. |\n| 422 | `operator_not_supported` | A run_when rule uses an operator it can't use; param names the rule. Use a view filter operator. |\n| 422 | `output_path_empty` | Name the output's path: a dotted path into the field's result, such as company.size. |\n| 422 | `own_key_required` | This integration needs your own API key. Add the key in Settings → Integrations. |\n| 422 | `provider_key_refused` | The integration refused your API key. Check the key in Settings → Integrations. |\n| 422 | `provider_not_available_in_cloud` | This integration runs only in the desktop app. Run it from the desktop instead. |\n| 422 | `quote_invalid` | The import quote is invalid or expired. Ask for a new quote. |\n| 422 | `region_required` | Choose a data region for the new workspace. |\n| 422 | `role_invalid` | The role's name or permissions aren't valid. Fix them and save again. |\n| 422 | `run_dependency_cycle` | The run group's fields depend on each other in a loop. Remove one of the dependencies. |\n| 422 | `schema_version_required` | Name the schema_version of the action parameters the inputs were built from. |\n| 422 | `selection_too_large` | The run selects more records than one run allows. Select fewer records. |\n| 422 | `step_over_row_cap` | Running every step up to this one could spend more than max_credits_per_row; param names the step. Raise the cap or drop the step. |\n| 422 | `stored_data_limit_reached` | Your account is at its plan's stored data limit. Nothing was written or charged. Delete data or upgrade before adding more. |\n| 422 | `table_enrichment_cycle` | This field would send rows back into a table that feeds it. Pick a target table outside the loop. |\n| 422 | `table_row_limit_reached` | The table is at your plan's limit of rows per table. Nothing was written or charged. Delete rows or upgrade before adding more. |\n| 422 | `too_many_records` | The selection exceeds max_records. Narrow the filter or increase max_records up to 1,000. |\n| 422 | `unknown_input` | The action has no input with that key; param names it. Read the action's parameters and fix the key. |\n| 422 | `unsupported_interface_page` | This interface page type can't be shared. Share a different page. |\n| 422 | `unsupported_method` | This integration doesn't offer that action. Pick an action the integration lists. |\n| 422 | `usage_range_too_wide` | The usage range is too wide. Ask for a shorter date range. |\n| 422 | `view_default_read_only` | A table's default view can't be changed or deleted. Create a new view instead. |\n| 422 | `view_limit_reached` | The table has the most views allowed. Delete a view before adding another. |\n| 422 | `wrong_type` | A value doesn't fit its input's type or allowed values; param names the input. Send a value of that type. |\n| 423 | `write_fenced` | Writes to this workspace are paused for maintenance. Retry after the Retry-After seconds. |\n| 429 | `admission_saturated` | Too many runs are starting at once. Wait the Retry-After seconds, then retry. |\n| 429 | `invite_quota_exceeded` | This workspace sent too many invitations recently. Wait a while, then send more. |\n| 429 | `key_credit_limit_exceeded` | This API key reached its daily credit limit. Wait for older spend to age out, or raise the key's limit. |\n| 429 | `provider_rate_limited` | The integration's service is rate-limiting your key. Wait the Retry-After seconds, then retry. |\n| 429 | `rate_limited` | Too many requests. Wait the Retry-After seconds, then retry. |\n| 429 | `search_limit_reached` | This plan's People and Company Search records are used up for now. They come back when the limit resets, or choose a larger plan. |\n| 429 | `too_many_jobs` | Too many list imports or CSV imports are open in this workspace. Wait for one to finish or stop one, then retry. |\n| 500 | `internal` | Something failed on our side. Retry; if it keeps failing, contact support with the request id. |\n| 503 | `commit_outcome_unknown` | The write may or may not have been saved. Retry with the same Idempotency-Key to find out. |\n| 503 | `lock_not_available` | Another write is changing this object right now. Retry in a moment. |\n| 503 | `provider_unavailable` | The integration's service is unavailable. Retry later. |\n| 503 | `public_api_disabled` | The public API is turned off for maintenance. Retry later. |\n| 503 | `region_unavailable` | That data region can't take new workspaces right now. Retry later or pick another region. |\n| 503 | `service_unavailable` | Sign-up verification is briefly unavailable. Retry in a minute. |\n| 503 | `shared_writes_disabled` | Cloud writes are briefly turned off. Retry in a few minutes. |\n| 503 | `stop_unavailable` | The run couldn't be stopped right now. Retry in a few seconds. |\n| 503 | `unavailable` | The service is briefly unavailable. Retry after the Retry-After seconds. |\n| 503 | `workspace_create_unavailable` | Workspaces can't be created right now. Retry in a few minutes. |\n| 504 | `query_timeout` | The query took too long. Narrow the filter or ask for fewer records, then retry. |\n\nA refused request runs nothing and costs no credits.\n\n**Retrying safely.** Send the same request again: an identical request (same API key, path and body) within ten minutes is answered with the first response instead of acting twice. Without an `Idempotency-Key`, creating a table, field or view that already exists returns the existing one, and starting a run on a field whose identical run is still going returns that run. To control this yourself, send an `Idempotency-Key` header (any 1 to 200 visible characters): the same key always returns the first response, and a new key always acts, even under a name already in use.\n\n## Rate limits\n\nRequests are counted per minute in two buckets: one that every read and write spends (`read` and `write` in an operation's description), and one for starts of runs and list imports (`provider`). A bucket is counted for your key, for your workspace and for your whole instance, and a request must fit all three. Requests per minute by plan, as key / workspace / instance:\n\n| Plan | Requests | Run starts |\n|---|---|---|\n| Trial | 300 / 600 / 1200 | 25 / 50 / 100 |\n| Starter | 300 / 600 / 1200 | 25 / 50 / 100 |\n| Pro | 600 / 1200 / 2400 | 50 / 100 / 200 |\n| Business | 1200 / 2400 / 4800 | 50 / 100 / 200 |\n| Enterprise | 1200 / 2400 / 4800 | 50 / 100 / 200 |\n\nThe Free plan has no API access.\n\nEvery response to a request whose key was checked carries `RateLimit-Limit` and `RateLimit-Remaining` for the bucket closest to its limit, `RateLimit-Reset` (seconds until that window resets) and `RateLimit-Policy` (`;w=60`: the limit and its window in seconds). Before your key is checked, only `RateLimit-Policy: 120;w=60` is sent: the per-address limit every request meets first. On `429`, wait `Retry-After` seconds before you retry.\n\n## Credits\n\nA run on Appenda's own provider keys spends credits from the workspace's balance; a run on a key you connected spends none. Preview a run to see `billing_quote.maximum_credits` before it starts, or start it in one call with `spend_cap.max_credits` and it is admitted only if the price fits. Rows a provider finds nothing for are charged only where the quote says so. A provider answer that is lost is never sent again and is not charged. A workspace's monthly credit cap, when set, stops runs that would pass it.\n\nStarting a run or a run group, or approving a held one, answers `X-Credits-Cost`: the credits that call set aside from the balance, which is the most the run can spend (`0` on a key you connected, and `0` when you send the same start again, since nothing more is set aside). Credits a run does not use return to the balance when it ends.\n\n## Callbacks\n\nStart a run with a `callback_url` (HTTPS, a public address) and Appenda POSTs to it once when the job ends, whatever its status. The body is the ended job as Get a run or Get a list import answers it, without its records: `{\"type\": \"job.ended\", \"data\": {\"id\": …, \"workspace_id\": …, \"object\": \"run\", \"status\": \"succeeded\", …}}`. If the job cannot be read when the callback is sent, `data` holds only `id` and `workspace_id`; read the job with Get a run then. Read the records themselves from the table. Each callback carries `webhook-id` (the job's id, the same on every attempt, so you can drop repeats), `webhook-timestamp` (Unix seconds) and `webhook-signature` (one or more space-separated `v1,` entries, each an HMAC-SHA256 of `..`). Answer any `2xx` to acknowledge it. A timeout, `408`, `429` or `5xx` is retried for about a day, never sooner than your `Retry-After`; other answers are not retried. A workspace's signing secret is not yet available to callers, so treat a callback as unverified and confirm anything you act on with your own key.\n\n## Changelog\n\n- **2026-11-08:** A callback's `data` is the ended job as Get a run or Get a list import answers it, beside its `id` and `workspace_id`.\n- **2026-10-22:** Every name is snake_case, in requests and answers; camelCase request keys are refused. Lists move their paging under `meta` (`next_cursor`, `has_more`), and answers no longer carry `commitId` or `revision` beside `data`.\n- **2026-10-21:** The reference lists only operations an API key can call, with short titles, a description and an example on every operation, and errors documented once on this page. `Idempotency-Key` is optional: identical requests within ten minutes are answered once.\n- **Deprecation policy:** a deprecated operation is marked deprecated, names its replacement and keeps working for at least 90 days, answering `Deprecation` and `Sunset` headers.", "title": "Appenda API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/api/v1/instances/{instance_id}/api-keys": { "get": { "description": "Returns the instance's super-admin tokens, newest first, ties by descending ID, never the secrets. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Create API keys. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listInstanceApiKeys", "parameters": [ { "description": "The instance: the account that holds one or more workspaces.", "example": "inst_9e815b66d1186bb90d2d77fbd69009df", "in": "path", "name": "instance_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-09-14T09:12:44.000Z", "expires_at": "2027-10-21T14:03:12.000Z", "id": "ak_6d024656917ac2cb714ebd17b5244270", "last_four": "x7Qa", "last_used_at": "2026-10-21T13:58:02.000Z", "max_credits_per_day": 500, "name": "CRM sync", "paused_at": null, "prefix": "appenda_sk_live_", "revoked_at": null, "role": "admin", "type": "api-user" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/ApiKeyPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List super-admin tokens", "tags": [ "API keys" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates a super-admin token that reaches every workspace of the instance and acts as an Admin in each, while you stay an instance administrator. Only the instance owner can call it. The secret is in this response only.\n\nPermission: Create API keys. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createInstanceApiKey", "parameters": [ { "description": "The instance: the account that holds one or more workspaces.", "example": "inst_9e815b66d1186bb90d2d77fbd69009df", "in": "path", "name": "instance_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "CRM sync" }, "schema": { "$ref": "#/components/schemas/CreateApiKey" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "ak_6d024656917ac2cb714ebd17b5244270", "last_four": "x7Qa", "max_credits_per_day": 500, "name": "CRM sync", "prefix": "appenda_sk_live_", "role": "admin", "secret": "appenda_sk_live_EXAMPLEnotARealKey0000000000000000000", "type": "api-user" } }, "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a super-admin token", "tags": [ "API keys" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/instances/{instance_id}/api-keys/{key_id}": { "delete": { "description": "Revokes a super-admin token; requests with it are refused at once. Cannot be undone.\n\nPermission: Create API keys. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "revokeInstanceApiKey", "parameters": [ { "description": "The instance: the account that holds one or more workspaces.", "example": "inst_9e815b66d1186bb90d2d77fbd69009df", "in": "path", "name": "instance_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The API key.", "example": "ak_6d024656917ac2cb714ebd17b5244270", "in": "path", "name": "key_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "204": { "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Revoke a super-admin token", "tags": [ "API keys" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/instances/{instance_id}/workspaces": { "post": { "description": "Creates a workspace in the instance. A workspace created with a key is owned by the instance owner.\n\nPermission: Instance admin, or a super-admin token. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createWorkspace", "parameters": [ { "description": "The instance: the account that holds one or more workspaces.", "example": "inst_9e815b66d1186bb90d2d77fbd69009df", "in": "path", "name": "instance_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Northbeam EMEA", "workspaceId": "ws_068ceadbd4d62272d7c97b97258e72eb" }, "schema": { "$ref": "#/components/schemas/WorkspaceCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "instanceId": "inst_9e815b66d1186bb90d2d77fbd69009df", "ownerUserId": "user_1ccece3aa6e3f736614f0238ca636876", "workspaceId": "ws_068ceadbd4d62272d7c97b97258e72eb" } }, "schema": { "$ref": "#/components/schemas/WorkspaceCreated" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a workspace", "tags": [ "Workspaces" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/users/{user_id}/api-keys": { "get": { "deprecated": true, "description": "Deprecated. Use List API user tokens instead; this operation keeps working until at least 2027-02-01. See [Versioning](https://appenda.app/docs/api/versioning).\n\nReturns your personal access tokens, newest first, ties by descending ID, never the secrets. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Create API keys. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listPersonalApiKeys", "parameters": [ { "description": "The member.", "example": "user_1ccece3aa6e3f736614f0238ca636876", "in": "path", "name": "user_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-09-14T09:12:44.000Z", "expires_at": "2027-10-21T14:03:12.000Z", "id": "ak_6d024656917ac2cb714ebd17b5244270", "last_four": "x7Qa", "last_used_at": "2026-10-21T13:58:02.000Z", "max_credits_per_day": 500, "name": "CRM sync", "paused_at": null, "prefix": "appenda_sk_live_", "revoked_at": null, "role": "admin", "type": "api-user" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/ApiKeyPage" } } }, "description": "Success", "headers": { "Deprecation": { "description": "When this operation was deprecated: `@` and seconds since 1970-01-01 UTC.", "example": "@1793664000", "schema": { "type": "string" } }, "Link": { "description": "The changelog entry that names the replacement.", "example": "; rel=\"deprecation\"", "schema": { "type": "string" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Sunset": { "description": "The day after which this operation may stop working.", "example": "Mon, 01 Feb 2027 00:00:00 GMT", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List personal access tokens (deprecated)", "tags": [ "API keys" ], "x-badges": [ { "name": "Deprecated" } ], "x-sunset": "2027-02-01" }, "post": { "deprecated": true, "description": "Retired. Use Create API user token instead; this operation no longer works and answers 410 until it is removed after 2027-01-19. See [Versioning](https://appenda.app/docs/api/versioning).\n\nCreates a personal access token that acts as you, with your current role in each workspace. The secret is in this response only.\n\nPermission: Create API keys. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createPersonalApiKey", "parameters": [ { "description": "The member.", "example": "user_1ccece3aa6e3f736614f0238ca636876", "in": "path", "name": "user_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "CRM sync" }, "schema": { "$ref": "#/components/schemas/CreateApiKey" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "ak_6d024656917ac2cb714ebd17b5244270", "last_four": "x7Qa", "max_credits_per_day": 500, "name": "CRM sync", "prefix": "appenda_sk_live_", "role": "admin", "secret": "appenda_sk_live_EXAMPLEnotARealKey0000000000000000000", "type": "api-user" } }, "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } }, "description": "Success", "headers": { "Deprecation": { "description": "When this operation was deprecated: `@` and seconds since 1970-01-01 UTC.", "example": "@1792540800", "schema": { "type": "string" } }, "Link": { "description": "The changelog entry that names the replacement.", "example": "; rel=\"deprecation\"", "schema": { "type": "string" } }, "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Sunset": { "description": "The day after which this operation may stop working.", "example": "Tue, 19 Jan 2027 00:00:00 GMT", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create personal access token (deprecated)", "tags": [ "API keys" ], "x-badges": [ { "name": "Deprecated" } ], "x-sunset": "2027-01-19" } }, "/api/v1/users/{user_id}/api-keys/{key_id}": { "delete": { "deprecated": true, "description": "Deprecated. Use Revoke API user token instead; this operation keeps working until at least 2027-02-01. See [Versioning](https://appenda.app/docs/api/versioning).\n\nRevokes one of your personal access tokens; requests with it are refused at once. Cannot be undone.\n\nPermission: Create API keys. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "revokePersonalApiKey", "parameters": [ { "description": "The member.", "example": "user_1ccece3aa6e3f736614f0238ca636876", "in": "path", "name": "user_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The API key.", "example": "ak_6d024656917ac2cb714ebd17b5244270", "in": "path", "name": "key_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "204": { "description": "Success", "headers": { "Deprecation": { "description": "When this operation was deprecated: `@` and seconds since 1970-01-01 UTC.", "example": "@1793664000", "schema": { "type": "string" } }, "Link": { "description": "The changelog entry that names the replacement.", "example": "; rel=\"deprecation\"", "schema": { "type": "string" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Sunset": { "description": "The day after which this operation may stop working.", "example": "Mon, 01 Feb 2027 00:00:00 GMT", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Revoke personal access token (deprecated)", "tags": [ "API keys" ], "x-badges": [ { "name": "Deprecated" } ], "x-sunset": "2027-02-01" } }, "/api/v1/workspaces/{workspace_id}/instance/logo": { "delete": { "description": "Removes the instance logo. Cannot be undone; upload a new logo to replace it.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "removeInstanceLogo", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "204": { "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Remove the instance logo", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/instance/logo/confirm": { "post": { "description": "Makes the uploaded image the instance logo.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "confirmInstanceLogo", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/EmptyObject" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "logoUrl": "https://images.appenda.app/logos/ws_2e056e042c3953f816e10bb208432f9e.png" } }, "schema": { "$ref": "#/components/schemas/LogoConfirmed" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Confirm instance logo upload", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/instance/logo/mint": { "post": { "description": "Starts an instance logo upload and returns a one-time upload URL. Upload the image there, then call Confirm instance logo upload.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "mintInstanceLogo", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/EmptyObject" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "imageId": "workspace/ws_2e056e042c3953f816e10bb208432f9e/logo", "uploadURL": "https://upload.appenda.app/workspace/ws_2e056e042c3953f816e10bb208432f9e/logo?signature=9f2c4b1e" } }, "schema": { "$ref": "#/components/schemas/LogoUpload" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Start instance logo upload", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/logo": { "delete": { "description": "Removes the workspace logo. Cannot be undone; upload a new logo to replace it.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "removeWorkspaceLogo", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "204": { "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Remove the logo", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/logo/confirm": { "post": { "description": "Makes the uploaded image the workspace logo.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "confirmWorkspaceLogo", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/EmptyObject" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "logoUrl": "https://images.appenda.app/logos/ws_2e056e042c3953f816e10bb208432f9e.png" } }, "schema": { "$ref": "#/components/schemas/LogoConfirmed" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Confirm a logo upload", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/logo/mint": { "post": { "description": "Starts a workspace logo upload and returns a one-time upload URL. Upload the image there, then call Confirm a logo upload.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "mintWorkspaceLogo", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/EmptyObject" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "imageId": "workspace/ws_2e056e042c3953f816e10bb208432f9e/logo", "uploadURL": "https://upload.appenda.app/workspace/ws_2e056e042c3953f816e10bb208432f9e/logo?signature=9f2c4b1e" } }, "schema": { "$ref": "#/components/schemas/LogoUpload" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Start a logo upload", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/role-assignments/{user_id}": { "put": { "description": "Gives a member a custom role, or clears it so that the member's built-in role applies.\n\nPermission: Manage team. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "assignMemberRole", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The member.", "example": "user_1ccece3aa6e3f736614f0238ca636876", "in": "path", "name": "user_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "roleKey": null }, "schema": { "$ref": "#/components/schemas/RoleAssignment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "key": "role_7c1f4e2a9b3d4c5e8f6a0b1c2d3e4f5a", "outcome": "valid" } }, "schema": { "$ref": "#/components/schemas/RoleMutation" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Assign a custom role", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/roles": { "get": { "description": "Returns the workspace's roles: the four built-in roles, any custom roles and what each may do. Built-in roles first, then custom roles oldest first, ties by role key. Not paged: one answer holds every role, at most 36.\n\nPermission: Manage team. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "listRoles", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "canDefineRoles": true, "privilegesApplicable": [ "canInviteMembers", "canExport" ], "roles": [ { "baseRole": "admin", "bundle": { "allowedSessionModes": [ "read_only" ], "canCreateApiKeys": false, "canCreatePersonalAccessTokens": true, "canDeleteWorkspace": false, "canExport": true, "canGrantApprovals": false, "canInviteMembers": false, "canManageAgentAccess": false, "canManageBilling": false, "canManageIntegrations": false, "canManageTeam": false, "maxRowsWithoutApproval": 1000, "providerRowCaps": { "appenda": 1000 }, "providersAllowed": { "appenda": true }, "toolClasses": { "mutate_rows": "ask", "read_table": "allow" } }, "customised": false, "defaultBundle": { "allowedSessionModes": [ "read_only" ], "canCreateApiKeys": false, "canCreatePersonalAccessTokens": true, "canDeleteWorkspace": false, "canExport": true, "canGrantApprovals": false, "canInviteMembers": false, "canManageAgentAccess": false, "canManageBilling": false, "canManageIntegrations": false, "canManageTeam": false, "maxRowsWithoutApproval": 1000, "providerRowCaps": { "appenda": 1000 }, "providersAllowed": { "appenda": true }, "toolClasses": { "mutate_rows": "ask", "read_table": "allow" } }, "key": "editor", "lockedSessionModes": [ "read_only" ], "name": "Research analyst" } ], "templates": [ { "baseRole": "admin", "bundle": { "allowedSessionModes": [ "read_only" ], "canCreateApiKeys": false, "canCreatePersonalAccessTokens": true, "canDeleteWorkspace": false, "canExport": true, "canGrantApprovals": false, "canInviteMembers": false, "canManageAgentAccess": false, "canManageBilling": false, "canManageIntegrations": false, "canManageTeam": false, "maxRowsWithoutApproval": 1000, "providerRowCaps": { "appenda": 1000 }, "providersAllowed": { "appenda": true }, "toolClasses": { "mutate_rows": "ask", "read_table": "allow" } }, "customised": false, "defaultBundle": { "allowedSessionModes": [ "read_only" ], "canCreateApiKeys": false, "canCreatePersonalAccessTokens": true, "canDeleteWorkspace": false, "canExport": true, "canGrantApprovals": false, "canInviteMembers": false, "canManageAgentAccess": false, "canManageBilling": false, "canManageIntegrations": false, "canManageTeam": false, "maxRowsWithoutApproval": 1000, "providerRowCaps": { "appenda": 1000 }, "providersAllowed": { "appenda": true }, "toolClasses": { "mutate_rows": "ask", "read_table": "allow" } }, "key": "editor", "lockedSessionModes": [ "read_only" ], "name": "Research analyst" } ] } }, "schema": { "$ref": "#/components/schemas/RoleConfiguration" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List roles", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates a custom role based on a built-in role, with its own permissions. You cannot grant more than you hold.\n\nPermission: Manage team. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createRole", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "baseRole": "admin", "name": "Research analyst" }, "schema": { "$ref": "#/components/schemas/RoleCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "key": "role_7c1f4e2a9b3d4c5e8f6a0b1c2d3e4f5a", "outcome": "valid" } }, "schema": { "$ref": "#/components/schemas/RoleMutation" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a role", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] } }, "/api/v1/workspaces/{workspace_id}/roles/{role_id}": { "delete": { "description": "Deletes a custom role. Cannot be undone.\n\nPermission: Manage team. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteRole", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The role: a built-in role name or a custom role id.", "example": "editor", "in": "path", "name": "role_id", "required": true, "schema": { "pattern": "^(admin|creator|editor|viewer|role_[0-9a-f]{32})$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "204": { "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Delete a role", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] }, "put": { "description": "Changes a role's permissions, or a custom role's name. You cannot grant more than you hold.\n\nPermission: Manage team. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateRole", "parameters": [ { "description": "The workspace to act in.", "example": "ws_2e056e042c3953f816e10bb208432f9e", "in": "path", "name": "workspace_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The role: a built-in role name or a custom role id.", "example": "editor", "in": "path", "name": "role_id", "required": true, "schema": { "pattern": "^(admin|creator|editor|viewer|role_[0-9a-f]{32})$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Research analyst" }, "schema": { "$ref": "#/components/schemas/RoleUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "key": "role_7c1f4e2a9b3d4c5e8f6a0b1c2d3e4f5a", "outcome": "valid" } }, "schema": { "$ref": "#/components/schemas/RoleMutation" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update a role", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/account": { "get": { "description": "Returns the member who owns the calling token, with their live role in its workspace.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getAccount", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "email": "priya.raman@northbeam.io", "id": "user_8ca9b929ed7fa6a7b845bae69edb9f29", "name": "Priya Raman", "object": "account", "role": "admin", "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "$ref": "#/components/schemas/AccountResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get account", "tags": [ "Account" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/api-keys": { "get": { "description": "Returns the workspace's API keys, newest first, ties by descending ID: names, prefixes, last four characters and last use, never the secrets. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Create API keys. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listWorkspaceApiKeys", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-09-14T09:12:44.000Z", "expires_at": "2027-10-21T14:03:12.000Z", "id": "ak_6d024656917ac2cb714ebd17b5244270", "last_four": "x7Qa", "last_used_at": "2026-10-21T13:58:02.000Z", "max_credits_per_day": 500, "name": "CRM sync", "paused_at": null, "prefix": "appenda_sk_live_", "revoked_at": null, "role": "admin", "type": "api-user" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/ApiKeyPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List API user tokens", "tags": [ "API keys" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates an API user token for this workspace. It acts as you, with your current role, and stops working when you leave the workspace. The secret is in this response only; store it safely.\n\nPermission: Create API keys. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createWorkspaceApiKey", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "CRM sync" }, "schema": { "$ref": "#/components/schemas/CreateApiKey" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "ak_6d024656917ac2cb714ebd17b5244270", "last_four": "x7Qa", "max_credits_per_day": 500, "name": "CRM sync", "prefix": "appenda_sk_live_", "role": "admin", "secret": "appenda_sk_live_EXAMPLEnotARealKey0000000000000000000", "type": "api-user" } }, "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create API user token", "tags": [ "API keys" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/api-keys/{key_id}": { "delete": { "description": "Revokes an API user token; requests with it are refused at once. Cannot be undone.\n\nPermission: Create API keys. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "revokeWorkspaceApiKey", "parameters": [ { "description": "The API key.", "example": "ak_6d024656917ac2cb714ebd17b5244270", "in": "path", "name": "key_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "204": { "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Revoke API user token", "tags": [ "API keys" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/approvals": { "get": { "description": "Returns held requests, newest first, ties by descending ID: your own, or every one in the workspace if you can grant approvals. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables; members see their own requests, approvers see all. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listApprovals", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "completed_at": null, "created_at": "2026-09-14T09:12:44.000Z", "decided_at": null, "decided_by": null, "expires_at": "2026-10-28T14:03:12.000Z", "id": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "operation_id": "createJob", "request": { "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "requester_id": "user_1ccece3aa6e3f736614f0238ca636876", "result": null, "status": "pending", "summary": { "maximum_credits": 500, "operation_id": "createJob", "rows": 500, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/ApprovalPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List approvals", "tags": [ "Approvals" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/approvals/{approval_id}": { "get": { "description": "Returns one held request: what will run, its state and, once it ran, its result.\n\nPermission: Read tables; members see their own requests, approvers see all. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getApproval", "parameters": [ { "description": "The held request.", "example": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "in": "path", "name": "approval_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "completed_at": null, "created_at": "2026-09-14T09:12:44.000Z", "decided_at": null, "decided_by": null, "expires_at": "2026-10-28T14:03:12.000Z", "id": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "operation_id": "createJob", "request": { "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "requester_id": "user_1ccece3aa6e3f736614f0238ca636876", "result": null, "status": "pending", "summary": { "maximum_credits": 500, "operation_id": "createJob", "rows": 500, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } } }, "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get an approval", "tags": [ "Approvals" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/approvals/{approval_id}/approve": { "post": { "description": "Approves another member's held request, which then runs once, with the same effects it would have had, such as spending credits. If something it depends on changed since it was held, it goes `stale` instead and must be sent again. Needs an API user token or a signed-in member; super-admin tokens are refused.\n\nPermission: Grant approvals. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "approveApproval", "parameters": [ { "description": "The held request.", "example": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "in": "path", "name": "approval_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "reason": "Over this month's budget for this table." }, "schema": { "$ref": "#/components/schemas/ApprovalDecision" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "completed_at": null, "created_at": "2026-09-14T09:12:44.000Z", "decided_at": null, "decided_by": null, "expires_at": "2026-10-28T14:03:12.000Z", "id": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "operation_id": "createJob", "request": { "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "requester_id": "user_1ccece3aa6e3f736614f0238ca636876", "result": null, "status": "approved", "summary": { "maximum_credits": 500, "operation_id": "createJob", "rows": 500, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } } }, "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Approve a request", "tags": [ "Approvals" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/approvals/{approval_id}/reject": { "post": { "description": "Rejects another member's held request; nothing runs. Needs an API user token or a signed-in member; super-admin tokens are refused.\n\nPermission: Grant approvals. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "rejectApproval", "parameters": [ { "description": "The held request.", "example": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "in": "path", "name": "approval_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "reason": "Over this month's budget for this table." }, "schema": { "$ref": "#/components/schemas/ApprovalDecision" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "completed_at": null, "created_at": "2026-09-14T09:12:44.000Z", "decided_at": null, "decided_by": null, "expires_at": "2026-10-28T14:03:12.000Z", "id": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "operation_id": "createJob", "request": { "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "requester_id": "user_1ccece3aa6e3f736614f0238ca636876", "result": null, "status": "rejected", "summary": { "maximum_credits": 500, "operation_id": "createJob", "rows": 500, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } } }, "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Reject a request", "tags": [ "Approvals" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/approvals/{approval_id}/withdraw": { "post": { "description": "Withdraws your own held request before it is decided; nothing runs.\n\nPermission: Read tables; members see their own requests, approvers see all. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "withdrawApproval", "parameters": [ { "description": "The held request.", "example": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "in": "path", "name": "approval_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "reason": "Over this month's budget for this table." }, "schema": { "$ref": "#/components/schemas/ApprovalDecision" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "completed_at": null, "created_at": "2026-09-14T09:12:44.000Z", "decided_at": null, "decided_by": null, "expires_at": "2026-10-28T14:03:12.000Z", "id": "apr_3f9c2b7e4d1a4c6e8b0f2a5d7c9e1b3f", "operation_id": "createJob", "request": { "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "requester_id": "user_1ccece3aa6e3f736614f0238ca636876", "result": null, "status": "cancelled", "summary": { "maximum_credits": 500, "operation_id": "createJob", "rows": 500, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } } }, "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Withdraw a request", "tags": [ "Approvals" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/commits": { "get": { "description": "Returns the workspace's history entries, newest first, ties by descending ID: who changed what, when and from where. Filter by table, member, channel or time. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listCommits", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } }, { "description": "Only commits on this table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "query", "name": "table_id", "required": false, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Only commits by this actor.", "example": "user_1ccece3aa6e3f736614f0238ca636876", "in": "query", "name": "actor_id", "required": false, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Only commits from this channel.", "example": "api", "in": "query", "name": "channel", "required": false, "schema": { "enum": [ "desktop", "agent", "api", "mcp", "cloud_worker" ], "type": "string" } }, { "description": "Only commits at or after this RFC 3339 time.", "example": "2026-10-01T00:00:00.000Z", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only commits at or before this RFC 3339 time; not before `since`.", "example": "2026-10-21T23:59:59.000Z", "in": "query", "name": "until", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "action_type": "enrichment", "actor": { "api_key_id": "ak_184992130055f27f212a3582fc736e9e", "channel": "api", "id": "user_1ccece3aa6e3f736614f0238ca636876" }, "actor_id": "user_1ccece3aa6e3f736614f0238ca636876", "channel": "api", "created_at": "2026-09-14T09:12:44.000Z", "id": "commit_d42e4a6b3b74003ed5031158a1847494", "kind": "enrichment_run", "message": "Enriched 212 work emails", "short_id": "de6127v", "summary": { "method_id": "email_finder", "provider_id": "appenda", "rows_enriched": 212, "status": "succeeded" }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "version_id": "ver_commit_d42e4a6b3b74003ed5031158a1847494" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/CommitPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List commits", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/commits/{commit_id}": { "get": { "description": "Returns one history entry with its counts and the tables it changed.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getCommit", "parameters": [ { "description": "The history entry's id.", "example": "commit_d42e4a6b3b74003ed5031158a1847494", "in": "path", "name": "commit_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "action_type": "enrichment", "actor": { "api_key_id": "ak_184992130055f27f212a3582fc736e9e", "channel": "api", "id": "user_1ccece3aa6e3f736614f0238ca636876" }, "actor_id": "user_1ccece3aa6e3f736614f0238ca636876", "channel": "api", "created_at": "2026-09-14T09:12:44.000Z", "id": "commit_d42e4a6b3b74003ed5031158a1847494", "kind": "enrichment_run", "message": "Enriched 212 work emails", "short_id": "de6127v", "summary": { "method_id": "email_finder", "provider_id": "appenda", "rows_enriched": 212, "status": "succeeded" }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "version_id": "ver_commit_d42e4a6b3b74003ed5031158a1847494" } }, "schema": { "$ref": "#/components/schemas/CommitResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a commit", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/credentials": { "get": { "description": "Returns the workspace's provider keys, newest first, ties by descending ID: their names, providers and status, never the secrets. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Manage integrations. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listProviderCredentials", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-09-14T09:12:44.000Z", "id": "cred_772ad6fd9b6f3d01a25cb34c169bf1b9", "is_default": true, "name": "Outbound team key", "ownership_scope": "workspace", "owning_workspace_id": "ws_2e056e042c3953f816e10bb208432f9e", "provider": "leadmagic", "provider_id": "appenda", "status": "pending" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/CredentialPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List provider keys", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Adds another key for a provider without changing which key is the default. The key is stored encrypted and never returned.\n\nPermission: Manage integrations. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createProviderCredential", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_key": "your-provider-api-key", "name": "Outbound team key", "provider": "leadmagic" }, "schema": { "$ref": "#/components/schemas/CredentialCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "cred_772ad6fd9b6f3d01a25cb34c169bf1b9", "owning_workspace_id": "ws_2e056e042c3953f816e10bb208432f9e", "provider": "leadmagic", "provider_id": "appenda", "status": "active" } }, "schema": { "$ref": "#/components/schemas/CredentialMutation" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Add a provider key", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/credits": { "get": { "description": "Returns the credits the workspace can spend, the plan's allotment and rollover, what was used this period and the workspace's spend cap. The balance is shared by every workspace in the instance. Any member's token may read it.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getCreditBalance", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "available": 18450, "available_decimal": 18450, "object": "credit_balance", "period": { "end": "2026-11-01T00:00:00.000Z", "start": "2026-10-01T00:00:00.000Z" }, "plan": "pro", "plan_allotment": 25000, "plan_allotment_decimal": 25000, "renews_at": "2026-11-01T00:00:00.000Z", "rollover": 4000, "rollover_decimal": 4000, "spend_cap": { "monthly_credits": 5000, "monthly_credits_decimal": 5000, "used_this_period": 1320 }, "used_this_period": 6550, "used_this_period_decimal": 6550 } }, "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get credit balance", "tags": [ "Credits" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/credits/transactions": { "get": { "description": "Returns the grants, charges, expiries and revocations that moved the balance, newest first, ties by descending ID, optionally only those of one run or a time range. They add up to the balance. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listCreditTransactions", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } }, { "description": "Only transactions at or after this RFC 3339 time.", "example": "2026-10-01T00:00:00.000Z", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only transactions before this RFC 3339 time; not before `since`.", "example": "2026-10-21T23:59:59.000Z", "in": "query", "name": "until", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only the charges of this run.", "example": "job_f799d04594ff4df5347c941a1018d24f", "in": "query", "name": "run_id", "required": false, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "action": "email_finder", "at": "2026-10-21T14:03:12.000Z", "created_at": "2026-10-21T14:03:12.000Z", "credits": -48, "credits_decimal": -48, "field_key": "work_email", "id": "lc_4485eb6d46e82821bb463595494d1f30", "kind": "charge", "object": "credit_transaction", "provider": "leadmagic", "run_id": "job_f799d04594ff4df5347c941a1018d24f", "scope": "workspace", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/CreditTransactionPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List credit transactions", "tags": [ "Credits" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/csv-imports/{csv_import_id}": { "get": { "description": "Returns a chunked import's progress: chunks applied, rows and fields added and values left empty.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getCsvImportJob", "parameters": [ { "description": "The CSV import, as returned when it started.", "example": "csvi_9d229e20444e16908d120ce7d6bcc6de", "in": "path", "name": "csv_import_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "chunks_applied": 12, "commit_id": null, "created_at": "2026-10-21T14:03:12.000Z", "fields_added": 2, "id": "csvi_71bdd9226218f46867d26a5795bc2041", "records_added": 980, "rows_added": 980, "state": "running", "status": "running", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:04:01.000Z", "values_emptied": 3 } }, "schema": { "$ref": "#/components/schemas/CsvImportJobResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a CSV import", "tags": [ "CSV" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/csv-imports/{csv_import_id}/chunks": { "post": { "description": "Imports one chunk of up to 1,000 data rows into a chunked import. Chunks may arrive in any order and rows land in chunk order; sending the same chunk again changes nothing. Its rows join the import's one entry in version history.\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "appendCsvImportChunk", "parameters": [ { "description": "The CSV import, as returned when it started.", "example": "csvi_9d229e20444e16908d120ce7d6bcc6de", "in": "path", "name": "csv_import_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "csv": "ledgerline.com,marcus.lee@ledgerline.com\r\nfernhill.ai,ana.sousa@fernhill.ai\r\n", "index": 1 }, "schema": { "$ref": "#/components/schemas/CsvImportChunk" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "chunks_applied": 12, "commit_id": null, "created_at": "2026-10-21T14:03:12.000Z", "fields_added": 2, "id": "csvi_71bdd9226218f46867d26a5795bc2041", "records_added": 980, "rows_added": 980, "state": "running", "status": "running", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:04:01.000Z", "values_emptied": 3 } }, "schema": { "$ref": "#/components/schemas/CsvImportJobResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Upload a CSV chunk", "tags": [ "CSV" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/csv-imports/{csv_import_id}/finish": { "post": { "description": "Ends a chunked import once every chunk is in. Adds one entry to version history for the whole file.\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "finishCsvImportJob", "parameters": [ { "description": "The CSV import, as returned when it started.", "example": "csvi_9d229e20444e16908d120ce7d6bcc6de", "in": "path", "name": "csv_import_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/CsvImportFinish" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "chunks_applied": 12, "commit_id": null, "created_at": "2026-10-21T14:03:12.000Z", "fields_added": 2, "id": "csvi_71bdd9226218f46867d26a5795bc2041", "records_added": 980, "rows_added": 980, "state": "completed", "status": "running", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:04:01.000Z", "values_emptied": 3 } }, "schema": { "$ref": "#/components/schemas/CsvImportJobResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Finish a CSV import", "tags": [ "CSV" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/csv-imports/{csv_import_id}/stop": { "post": { "description": "Stops a chunked import and keeps the rows already imported. Adds one entry to version history.\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "stopCsvImportJob", "parameters": [ { "description": "The CSV import, as returned when it started.", "example": "csvi_9d229e20444e16908d120ce7d6bcc6de", "in": "path", "name": "csv_import_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "chunks_applied": 12, "commit_id": null, "created_at": "2026-10-21T14:03:12.000Z", "fields_added": 2, "id": "csvi_71bdd9226218f46867d26a5795bc2041", "records_added": 980, "rows_added": 980, "state": "stopped", "status": "running", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:04:01.000Z", "values_emptied": 3 } }, "schema": { "$ref": "#/components/schemas/CsvImportJobResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Stop a CSV import", "tags": [ "CSV" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/instance": { "patch": { "description": "Renames the instance.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "renameInstance", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Northbeam GTM" }, "schema": { "$ref": "#/components/schemas/RenameRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "inst_9e815b66d1186bb90d2d77fbd69009df", "name": "Northbeam GTM", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/RenameResult" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Rename the instance", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/integrations": { "get": { "description": "Returns the providers the workspace's plan allows, their actions, and whether the workspace has connected its own key for each. Keys are never returned. Integrations come in the catalog's fixed order. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read integrations. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listIntegrations", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "auth_mode": "api_key", "category": "people", "connected": true, "connection": "built_in", "connection_fields": [ { "help": "Paste the API key from your account settings.", "kind": "secret", "label": "API key", "name": "api_key", "required": true } ], "credential_shape": "api_key", "key_source": "either", "key_sources": [ "appenda", "own" ], "logo_key": "appenda", "methods": [ { "category": "tables", "id": "send_row", "kind": "row_action", "label": "Send row to table", "name": "Send row to table", "price": "free", "runs_on": "local_and_cloud" } ], "name": "Appenda", "provider": "leadmagic", "provider_id": "appenda" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/IntegrationPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List integrations", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/integrations/{provider_id}/actions": { "get": { "description": "Returns an integration's actions: what each does, whether it can be an enrichment field and the `schema_version` of its parameters. An integration the workspace's plan does not include is not found. Actions come in the catalog's fixed order. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read integrations. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listIntegrationActions", "parameters": [ { "description": "The provider, as listed by List integrations.", "example": "appenda", "in": "path", "name": "provider_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "can_be_field": true, "description": "Finds a person's work email from their name and company domain.", "id": "email_finder", "key_source": "either", "key_sources": [ "appenda", "own" ], "kind": "row_enrich", "name": "Find work email", "object": "action", "schema_version": 2 } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/IntegrationActionPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List integration actions", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/integrations/{provider_id}/actions/{action_id}": { "get": { "description": "Returns one action's parameters: each input's type, whether it is required, which alternatives satisfy it and whether it takes a field, a fixed value or a template, plus its outputs and `schema_version`. Use it to build Create an enrichment field.\n\nPermission: Read integrations. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getIntegrationAction", "parameters": [ { "description": "The provider, as listed by List integrations.", "example": "appenda", "in": "path", "name": "provider_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The action, as listed by List integration actions.", "example": "find_work_email", "in": "path", "name": "action_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "action": "email_finder", "input_schema": { "required": [ "domain" ] }, "inputs": [ { "accepts": { "field": true, "template": false, "value": true }, "description": "The company's website domain.", "example": "northbeam.io", "key": "domain", "label": "Company domain", "one_of_groups": [], "required": true, "type": "template" } ], "key_source": "either", "key_sources": [ "appenda", "own" ], "outputs": [ "email", "status" ], "outputs_from": { "input": "schema" }, "provider": "leadmagic", "requires": { "one_of": [ [ [ "first_name", "last_name" ], [ "full_name" ] ] ] }, "schema_digest": "5e1f0c2a9b7d", "schema_version": 2 } }, "schema": { "$ref": "#/components/schemas/ActionParametersResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get action parameters", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/integrations/{provider_id}/credential": { "delete": { "description": "Disconnects a provider: revokes its default key and erases the stored secret. Cannot be undone; to connect again, send the key again.\n\nPermission: Manage integrations. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "disconnectIntegration", "parameters": [ { "description": "The provider, as listed by List integrations.", "example": "appenda", "in": "path", "name": "provider_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "connected": false, "provider": "leadmagic", "provider_id": "appenda" } }, "schema": { "$ref": "#/components/schemas/IntegrationConnection" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Disconnect an integration", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] }, "put": { "description": "Connects a provider with the workspace's own API key, which becomes that provider's default key. The key is stored encrypted and never returned. A provider that is already connected must be disconnected first.\n\nPermission: Manage integrations. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "connectIntegration", "parameters": [ { "description": "The provider, as listed by List integrations.", "example": "appenda", "in": "path", "name": "provider_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_key": "your-provider-api-key" }, "schema": { "$ref": "#/components/schemas/IntegrationCredentialWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "connected": true, "provider": "leadmagic", "provider_id": "appenda" } }, "schema": { "$ref": "#/components/schemas/IntegrationConnection" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Connect an integration", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/integrations/{provider_id}/options": { "get": { "description": "Returns a picker input's live choices from the connected provider, such as the campaigns a sending action can add leads to, in the provider's own order. An input whose choices depend on another takes that one in `values`. `cursor` carries the provider's own cursor; without `limit`, a page holds the provider's page as it comes.\n\nPermission: Read integrations. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "getInputOptions", "parameters": [ { "description": "The provider, as listed by List integrations.", "example": "appenda", "in": "path", "name": "provider_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The provider action whose input this is.", "example": "find_rows", "in": "query", "name": "action", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The input whose choices to list.", "example": "target_table", "in": "query", "name": "input", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The connected key to read with. Default: the workspace's default key for the provider.", "example": "cred_8629e5e3b92eb2d1f2c315121b30bdee", "in": "query", "name": "credential_id", "required": false, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Only choices whose label contains this text.", "example": "outbound", "in": "query", "name": "search", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "description": "JSON object of the other inputs this input's choices depend on, by input key. URL-encode it in the query string.", "example": "{\"target_table\":\"tbl_67ad65ba34a7bbfc643711b8531cba3f\"}", "in": "query", "name": "values", "required": false, "schema": { "contentMediaType": "application/json", "contentSchema": { "type": "object" }, "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "label": "Leads", "value": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/InputOptionPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get input options", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/interfaces": { "get": { "description": "Returns the workspace's interfaces: dashboards of charts, filters and sections over its tables, ordered by ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listInterfaces", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/InterfaceList" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List interfaces", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates an interface with its pages and blocks, for the whole workspace or for one table. A table's interface is deleted with its table. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createInterface", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Pipeline overview", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "schema": { "$ref": "#/components/schemas/InterfaceCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "block_errors": [ { "block_id": "block_72554c079aeac4c4e25acb33100ddf2d", "page_id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "reason": "Over this month's budget for this table." } ], "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "pages": [ { "blocks": [ { "display": { "chart_kind": "kpi", "color_style": "appenda", "group_label": "Stage", "hide_legend": false, "series": [ { "format": { "precision": 2, "style": "number" }, "label": "Meetings booked", "palette_slot": 2 } ], "title": "Meetings by month" }, "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "layout": { "column": 1, "height": 3, "new_row": false, "row": 1, "width": 6 }, "position": 2, "query": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "group_by": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "found_by": true, "json_path": "/company/size", "time_bucket": "day" }, "limit": 50, "metrics": [ { "expression": "{first_name} & \" \" & {last_name}", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23", "json_path": "/company/size", "label": "Pipeline value", "operation": "count" } ], "order": { "by": "group", "direction": "asc", "metric_index": 1 }, "series": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "json_path": "/company/size", "limit": 5 }, "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "section_id": "block_c35d83a7a2e46c143a700d469509ab98", "title": "Meetings by month", "use_page_filter": true } ], "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "name": "This quarter", "page_type": "dashboard", "position": 2, "source_table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "source_view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/InterfaceMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create an interface", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/interfaces/{interface_id}": { "delete": { "description": "Deletes an interface. Adds an entry to version history. Cannot be undone. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteInterface", "parameters": [ { "description": "The interface.", "example": "iface_e75642bd5fc3eba043f27a2c87459bef", "in": "path", "name": "interface_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true, "id": "iface_e75642bd5fc3eba043f27a2c87459bef" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Delete an interface", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] }, "get": { "description": "Returns one interface with its pages and blocks, and names any block whose table or fields changed underneath it.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getInterface", "parameters": [ { "description": "The interface.", "example": "iface_e75642bd5fc3eba043f27a2c87459bef", "in": "path", "name": "interface_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "block_errors": [ { "block_id": "block_72554c079aeac4c4e25acb33100ddf2d", "page_id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "reason": "Over this month's budget for this table." } ], "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "pages": [ { "blocks": [ { "display": { "chart_kind": "kpi", "color_style": "appenda", "group_label": "Stage", "hide_legend": false, "series": [ { "format": { "precision": 2, "style": "number" }, "label": "Meetings booked", "palette_slot": 2 } ], "title": "Meetings by month" }, "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "layout": { "column": 1, "height": 3, "new_row": false, "row": 1, "width": 6 }, "position": 2, "query": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "group_by": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "found_by": true, "json_path": "/company/size", "time_bucket": "day" }, "limit": 50, "metrics": [ { "expression": "{first_name} & \" \" & {last_name}", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23", "json_path": "/company/size", "label": "Pipeline value", "operation": "count" } ], "order": { "by": "group", "direction": "asc", "metric_index": 1 }, "series": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "json_path": "/company/size", "limit": 5 }, "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "section_id": "block_c35d83a7a2e46c143a700d469509ab98", "title": "Meetings by month", "use_page_filter": true } ], "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "name": "This quarter", "page_type": "dashboard", "position": 2, "source_table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "source_view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/InterfaceResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get an interface", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Renames an interface or replaces its pages and blocks. To change one block, use Update an interface block. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateInterface", "parameters": [ { "description": "The interface.", "example": "iface_e75642bd5fc3eba043f27a2c87459bef", "in": "path", "name": "interface_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Pipeline overview Q4" }, "schema": { "$ref": "#/components/schemas/InterfaceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "block_errors": [ { "block_id": "block_72554c079aeac4c4e25acb33100ddf2d", "page_id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "reason": "Over this month's budget for this table." } ], "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "pages": [ { "blocks": [ { "display": { "chart_kind": "kpi", "color_style": "appenda", "group_label": "Stage", "hide_legend": false, "series": [ { "format": { "precision": 2, "style": "number" }, "label": "Meetings booked", "palette_slot": 2 } ], "title": "Meetings by month" }, "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "layout": { "column": 1, "height": 3, "new_row": false, "row": 1, "width": 6 }, "position": 2, "query": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "group_by": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "found_by": true, "json_path": "/company/size", "time_bucket": "day" }, "limit": 50, "metrics": [ { "expression": "{first_name} & \" \" & {last_name}", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23", "json_path": "/company/size", "label": "Pipeline value", "operation": "count" } ], "order": { "by": "group", "direction": "asc", "metric_index": 1 }, "series": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "json_path": "/company/size", "limit": 5 }, "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "section_id": "block_c35d83a7a2e46c143a700d469509ab98", "title": "Meetings by month", "use_page_filter": true } ], "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "name": "This quarter", "page_type": "dashboard", "position": 2, "source_table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "source_view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/InterfaceMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update an interface", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/interfaces/{interface_id}/blocks": { "post": { "description": "Adds one block (a chart, a filter control or a section) to an interface page. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "addInterfaceBlock", "parameters": [ { "description": "The interface.", "example": "iface_e75642bd5fc3eba043f27a2c87459bef", "in": "path", "name": "interface_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The interface page the block is on.", "example": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "in": "query", "name": "page_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "block": { "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "position": 0, "query": { "limit": 50, "metrics": [ { "label": "Meetings", "operation": "count" } ], "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "title": "Meetings booked" } }, "schema": { "$ref": "#/components/schemas/InterfaceBlockWrite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "block_errors": [ { "block_id": "block_72554c079aeac4c4e25acb33100ddf2d", "page_id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "reason": "Over this month's budget for this table." } ], "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "pages": [ { "blocks": [ { "display": { "chart_kind": "kpi", "color_style": "appenda", "group_label": "Stage", "hide_legend": false, "series": [ { "format": { "precision": 2, "style": "number" }, "label": "Meetings booked", "palette_slot": 2 } ], "title": "Meetings by month" }, "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "layout": { "column": 1, "height": 3, "new_row": false, "row": 1, "width": 6 }, "position": 2, "query": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "group_by": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "found_by": true, "json_path": "/company/size", "time_bucket": "day" }, "limit": 50, "metrics": [ { "expression": "{first_name} & \" \" & {last_name}", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23", "json_path": "/company/size", "label": "Pipeline value", "operation": "count" } ], "order": { "by": "group", "direction": "asc", "metric_index": 1 }, "series": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "json_path": "/company/size", "limit": 5 }, "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "section_id": "block_c35d83a7a2e46c143a700d469509ab98", "title": "Meetings by month", "use_page_filter": true } ], "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "name": "This quarter", "page_type": "dashboard", "position": 2, "source_table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "source_view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/InterfaceMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Add a block", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/interfaces/{interface_id}/blocks/{block_id}": { "delete": { "description": "Removes one block from an interface page. Adds an entry to version history. Cannot be undone; add the block again to bring it back. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteInterfaceBlock", "parameters": [ { "description": "The interface.", "example": "iface_e75642bd5fc3eba043f27a2c87459bef", "in": "path", "name": "interface_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The block on the page.", "example": "block_72554c079aeac4c4e25acb33100ddf2d", "in": "path", "name": "block_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The interface page the block is on.", "example": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "in": "query", "name": "page_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "block_errors": [ { "block_id": "block_72554c079aeac4c4e25acb33100ddf2d", "page_id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "reason": "Over this month's budget for this table." } ], "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "pages": [ { "blocks": [ { "display": { "chart_kind": "kpi", "color_style": "appenda", "group_label": "Stage", "hide_legend": false, "series": [ { "format": { "precision": 2, "style": "number" }, "label": "Meetings booked", "palette_slot": 2 } ], "title": "Meetings by month" }, "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "layout": { "column": 1, "height": 3, "new_row": false, "row": 1, "width": 6 }, "position": 2, "query": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "group_by": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "found_by": true, "json_path": "/company/size", "time_bucket": "day" }, "limit": 50, "metrics": [ { "expression": "{first_name} & \" \" & {last_name}", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23", "json_path": "/company/size", "label": "Pipeline value", "operation": "count" } ], "order": { "by": "group", "direction": "asc", "metric_index": 1 }, "series": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "json_path": "/company/size", "limit": 5 }, "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "section_id": "block_c35d83a7a2e46c143a700d469509ab98", "title": "Meetings by month", "use_page_filter": true } ], "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "name": "This quarter", "page_type": "dashboard", "position": 2, "source_table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "source_view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/InterfaceMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Delete a block", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Replaces one block on an interface page. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateInterfaceBlock", "parameters": [ { "description": "The interface.", "example": "iface_e75642bd5fc3eba043f27a2c87459bef", "in": "path", "name": "interface_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The block on the page.", "example": "block_72554c079aeac4c4e25acb33100ddf2d", "in": "path", "name": "block_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The interface page the block is on.", "example": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "in": "query", "name": "page_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "block": { "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "position": 0, "query": { "limit": 50, "metrics": [ { "label": "Meetings", "operation": "count" } ], "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "title": "Meetings booked" } }, "schema": { "$ref": "#/components/schemas/InterfaceBlockWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "block_errors": [ { "block_id": "block_72554c079aeac4c4e25acb33100ddf2d", "page_id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "reason": "Over this month's budget for this table." } ], "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "pages": [ { "blocks": [ { "display": { "chart_kind": "kpi", "color_style": "appenda", "group_label": "Stage", "hide_legend": false, "series": [ { "format": { "precision": 2, "style": "number" }, "label": "Meetings booked", "palette_slot": 2 } ], "title": "Meetings by month" }, "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "layout": { "column": 1, "height": 3, "new_row": false, "row": 1, "width": 6 }, "position": 2, "query": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "group_by": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "found_by": true, "json_path": "/company/size", "time_bucket": "day" }, "limit": 50, "metrics": [ { "expression": "{first_name} & \" \" & {last_name}", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23", "json_path": "/company/size", "label": "Pipeline value", "operation": "count" } ], "order": { "by": "group", "direction": "asc", "metric_index": 1 }, "series": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "json_path": "/company/size", "limit": 5 }, "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "section_id": "block_c35d83a7a2e46c143a700d469509ab98", "title": "Meetings by month", "use_page_filter": true } ], "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "name": "This quarter", "page_type": "dashboard", "position": 2, "source_table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "source_view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/InterfaceMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update a block", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/interfaces/{interface_id}/blocks/{block_id}/move": { "post": { "description": "Moves one block to a new position on its page. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "moveInterfaceBlock", "parameters": [ { "description": "The interface.", "example": "iface_e75642bd5fc3eba043f27a2c87459bef", "in": "path", "name": "interface_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The block on the page.", "example": "block_72554c079aeac4c4e25acb33100ddf2d", "in": "path", "name": "block_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The interface page the block is on.", "example": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "in": "query", "name": "page_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "position": 2 }, "schema": { "$ref": "#/components/schemas/InterfaceBlockMove" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "block_errors": [ { "block_id": "block_72554c079aeac4c4e25acb33100ddf2d", "page_id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "reason": "Over this month's budget for this table." } ], "id": "iface_e75642bd5fc3eba043f27a2c87459bef", "name": "Pipeline overview", "pages": [ { "blocks": [ { "display": { "chart_kind": "kpi", "color_style": "appenda", "group_label": "Stage", "hide_legend": false, "series": [ { "format": { "precision": 2, "style": "number" }, "label": "Meetings booked", "palette_slot": 2 } ], "title": "Meetings by month" }, "id": "block_72554c079aeac4c4e25acb33100ddf2d", "kind": "chart", "layout": { "column": 1, "height": 3, "new_row": false, "row": 1, "width": 6 }, "position": 2, "query": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "group_by": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "found_by": true, "json_path": "/company/size", "time_bucket": "day" }, "limit": 50, "metrics": [ { "expression": "{first_name} & \" \" & {last_name}", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23", "json_path": "/company/size", "label": "Pipeline value", "operation": "count" } ], "order": { "by": "group", "direction": "asc", "metric_index": 1 }, "series": { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "json_path": "/company/size", "limit": 5 }, "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "section_id": "block_c35d83a7a2e46c143a700d469509ab98", "title": "Meetings by month", "use_page_filter": true } ], "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "id": "page_06fc6be90b523fa3c79bc2e19ff0d11b", "name": "This quarter", "page_type": "dashboard", "position": 2, "source_table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "source_view_id": "view_a013e65c011b856c46e9d282545f1211" } ], "table_id": null, "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/InterfaceMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Move a block", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/list-imports": { "get": { "description": "Returns the workspace's list imports, newest first, ties by descending ID, optionally by status or start time. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listListImports", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } }, { "description": "Only those in this status.", "example": "succeeded", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "queued", "running", "succeeded", "failed", "stopped", "needs_review" ], "type": "string" } }, { "description": "Only those started at or after this RFC 3339 time.", "example": "2026-10-01T00:00:00.000Z", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "action": "email_finder", "applied": true, "created_at": "2026-10-21T14:03:12.000Z", "id": "lij_d9735a83f6b094787f1fedc1f2703331", "max_rows": 500, "object": "list_import", "pages_done": 3, "provider": "leadmagic", "records_found": 75, "rows_found": 75, "status": "succeeded", "stop_requested": false, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:05:40.000Z" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/ListImportPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List list imports", "tags": [ "List import" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/list-imports/{list_import_id}": { "get": { "description": "Returns a list import's status: pages and rows done, credits reserved and why it ended.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getListImportJob", "parameters": [ { "description": "The list import, as returned when it started.", "example": "lij_29c9ec08f07337778b60535798d71c96", "in": "path", "name": "list_import_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "action": "people_search", "billable_units": 980, "created_at": "2026-09-14T09:12:44.000Z", "credits": { "estimated": 500, "estimated_decimal": 500, "key_source": "appenda", "used": 480, "used_decimal": 480 }, "credits_reserved": 500, "end_reason": "max_rows_reached", "finalized": false, "job_id": "lij_79f45934b99ad0b7ba5d4327e5b80b74", "max_pages": 10, "max_rows": 1000, "method_id": "people_search", "pages_done": 4, "provider": "appenda", "provider_id": "appenda", "records_done": 100, "rows_done": 100, "status": "succeeded", "stop_requested": false, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/ListImportJobResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a list import", "tags": [ "List import" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/list-imports/{list_import_id}/stop": { "post": { "description": "Stops a list import. Pages already fetched are kept. Runs in the background; poll Get a list import until it ends.\n\nPermission: List import. Rate limit: write. See [Rate limits](#description/rate-limits), [Credits](#description/credits).", "operationId": "stopListImportJob", "parameters": [ { "description": "The list import, as returned when it started.", "example": "lij_29c9ec08f07337778b60535798d71c96", "in": "path", "name": "list_import_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "data": { "job_id": "lij_79f45934b99ad0b7ba5d4327e5b80b74", "stop": "stopping" } }, "schema": { "$ref": "#/components/schemas/ListImportStopResponse" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Stop a list import", "tags": [ "List import" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/members": { "get": { "description": "Returns the workspace's members with their roles and when they joined, ordered by user ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read team. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listMembers", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "display_name": "Priya Raman", "email": "priya.raman@northbeam.io", "joined_at": "2026-09-14T09:12:44.000Z", "role": "editor", "role_key": null, "status": "Active", "user_id": "user_1ccece3aa6e3f736614f0238ca636876" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/MemberPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List members", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/members/{user_id}": { "delete": { "description": "Removes a member from the workspace; the last owner cannot be removed. Cannot be undone; invite them again to bring them back.\n\nPermission: Manage team. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "removeMember", "parameters": [ { "description": "The member.", "example": "user_1ccece3aa6e3f736614f0238ca636876", "in": "path", "name": "user_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true, "id": "user_1ccece3aa6e3f736614f0238ca636876", "object": "member" } }, "schema": { "$ref": "#/components/schemas/MemberRemoved" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Remove a member", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Changes a member's role, or adds an existing account to the workspace. An API user token can grant or change Owner only if its creator can; a super-admin token never can.\n\nPermission: Manage team. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateMember", "parameters": [ { "description": "The member.", "example": "user_1ccece3aa6e3f736614f0238ca636876", "in": "path", "name": "user_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "role": "editor" }, "schema": { "$ref": "#/components/schemas/MemberRoleWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "user_1ccece3aa6e3f736614f0238ca636876", "object": "member", "role": "editor" } }, "schema": { "$ref": "#/components/schemas/MemberUpdated" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update a member", "tags": [ "Members" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/provider-actions": { "post": { "description": "Runs one provider action, a single call that changes or reads the connected tool's workspace, such as adding leads to a campaign. Calls the connected provider on the workspace's own key and spends no credits. Runs in the background; poll Get a provider action. It is sent at most once: a byte-identical body, or the same `Idempotency-Key`, returns the same run. A retry that re-serializes its JSON is a new request, so send the key when you retry. A role that needs approval for writes to connected tools is refused with `403 approval_required`.\n\nPermission: Write to connected tools. Rate limit: provider. See [Rate limits](#description/rate-limits).", "operationId": "createProviderAction", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "action": "leads_bulk_add", "input": { "campaign_id": "0199a1b2-0000-7000-8000-000000000001", "leads": [ { "email": "priya.raman@northbeam.io", "first_name": "Priya" } ] }, "provider": "instantly" }, "schema": { "$ref": "#/components/schemas/ProviderActionStartRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "action": "leads_bulk_add", "created_at": "2026-11-02T09:12:44.000Z", "end_reason": "complete", "id": "paj_4b1d2c3e4f5a6b7c8d9e0f1a2b3c4d5e", "object": "provider_action", "outcome": "applied", "provider": "instantly", "result": { "class": "created", "result": { "label": "Leads added: 2", "outcome": "created", "value": 2 }, "status": 200 }, "status": "succeeded", "table_id": null, "updated_at": "2026-11-02T09:12:46.000Z" } }, "schema": { "$ref": "#/components/schemas/ProviderActionResponse" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Start a provider action", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/provider-actions/{provider_action_id}": { "get": { "description": "Returns a provider action's status and, once it ran, its outcome and readable result.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getProviderAction", "parameters": [ { "description": "The provider action, as returned when it started.", "example": "paj_4b1d2c3e4f5a6b7c8d9e0f1a2b3c4d5e", "in": "path", "name": "provider_action_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "action": "leads_bulk_add", "created_at": "2026-11-02T09:12:44.000Z", "end_reason": "complete", "id": "paj_4b1d2c3e4f5a6b7c8d9e0f1a2b3c4d5e", "object": "provider_action", "outcome": "applied", "provider": "instantly", "result": { "class": "created", "result": { "label": "Leads added: 2", "outcome": "created", "value": 2 }, "status": 200 }, "status": "succeeded", "table_id": null, "updated_at": "2026-11-02T09:12:46.000Z" } }, "schema": { "$ref": "#/components/schemas/ProviderActionResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a provider action", "tags": [ "Integrations" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/rate-limits": { "get": { "description": "Returns the calling token's request limits for reads, writes and starts of runs, and how many list imports and CSV imports a workspace may have open at once. The numbers are the ones enforced on your plan.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getRateLimits", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "classes": { "provider": { "per_instance": 1200, "per_key": 300, "per_workspace": 600 }, "read": { "per_instance": 1200, "per_key": 300, "per_workspace": 600 }, "write": { "per_instance": 1200, "per_key": 300, "per_workspace": 600 } }, "concurrent_jobs": { "csv_imports": 50, "list_imports": 50 }, "object": "rate_limits", "window_seconds": 60 } }, "schema": { "$ref": "#/components/schemas/RateLimitsResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get rate limits", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/run-groups": { "post": { "description": "Starts a previewed multi-field run: each field runs after the fields it depends on, and every stage's credits are reserved at once within the ceilings you send. Spends credits when it runs on Appenda's managed keys, and calls the connected providers. Runs in the background; poll Get a multi-field run. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Run enrichments. Rate limit: write. See [Rate limits](#description/rate-limits), [Credits](#description/credits).", "operationId": "createRunGroup", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "field_ids": [ "fld_1e57b877a78db86124936f976015f646", "fld_b00a97266f03cceb43636653c0e40b38" ], "max_calls": 1000, "max_credits": 1000, "options": { "force": false, "mode": { "kind": "all" } }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "schema": { "$ref": "#/components/schemas/CreateGroupRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-21T14:03:12.000Z", "credits_reserved": 500, "id": "group_56ff59d335d64643a037a602c9591144", "stages": [ { "depends_on": [ "fld_1e57b877a78db86124936f976015f646" ], "field_id": "fld_1e57b877a78db86124936f976015f646", "job_id": "job_d60ef6b2d188d2801bd33bf129195874", "requested_rows": 500, "status": "succeeded" } ], "status": "running", "stop_requested": false, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:05:40.000Z", "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RunGroupResponse" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Start a multi-field run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/run-groups/preview": { "post": { "description": "Prices a run over up to 60 enrichment fields that feed each other, in dependency order, without starting it: the rows each field reaches and the most calls and credits. Returns a preview token for Start a multi-field run. Nothing is charged.\n\nPermission: Run enrichments. Rate limit: read. See [Rate limits](#description/rate-limits), [Credits](#description/credits).", "operationId": "previewRunGroup", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "field_ids": [ "fld_1e57b877a78db86124936f976015f646", "fld_3b111e2d329410910aafdbad96ec1f45" ], "options": { "force": false, "mode": { "kind": "all" } }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "schema": { "$ref": "#/components/schemas/PreviewGroupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "approval_required": false, "expires_at": "2026-10-21T14:18:12.000Z", "max_calls": 500, "max_credits": 500, "preview_token": "pvw_v1.EXAMPLE-preview-token-not-a-real-value", "record_count": 500, "skipped": [ { "field_id": "fld_5a1c9e0d7b3f4e2a8c6d1b0e9f7a3c5d", "reason": "own_key_required" } ], "stages": [ { "action": "email_finder", "billing_quote": { "billable_outcomes": [ "success" ], "billing_unit": "row", "credits_per_unit": 1, "maximum_credits": 500, "maximum_units": 500, "method_id": "email_finder", "provider_id": "appenda", "schema_version": 1 }, "configuration": { "action": "email_finder", "credential_id": "cred_772ad6fd9b6f3d01a25cb34c169bf1b9", "credential_source": "managed", "first_n": 100, "inputs": { "domain": "fld_b00a97266f03cceb43636653c0e40b38", "first_name": "fld_3b9ed9139c16536a8e36fd6279b1a510", "last_name": "fld_4ad93454e0feed19f81e719c13744619" }, "method_id": "email_finder", "output": "/email", "output_path": "/email", "provider": "leadmagic", "provider_id": "leadmagic", "run_condition": "{fld_b00a97266f03cceb43636653c0e40b38} != \"\"", "run_when": { "match": "all", "rules": [ { "field": "work_email", "operator": "is_empty" } ] } }, "credential_id": null, "depends_on": [ "fld_1e57b877a78db86124936f976015f646" ], "field_id": "fld_1e57b877a78db86124936f976015f646", "max_calls": 500, "max_credits": 500, "method_id": "email_finder", "provider": "leadmagic", "provider_id": "appenda" } ], "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "schema": { "$ref": "#/components/schemas/RunGroupPreviewResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Preview a multi-field run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/run-groups/{group_id}": { "delete": { "deprecated": true, "description": "Deprecated. Use Stop a multi-field run instead; this operation keeps working until at least 2027-02-01. See [Versioning](https://appenda.app/docs/api/versioning).\n\nDeprecated: use Stop a multi-field run (`POST /v1/run-groups/{group_id}/stop`), which does the same. Stops a multi-field run you started. Stages not yet sent do not run; answers already received are kept and unused credits are released. Runs in the background; poll Get a multi-field run until it ends.\n\nPermission: Run enrichments, or be the member who started the run. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "stopRunGroup", "parameters": [ { "description": "The multi-field run.", "example": "group_56ff59d335d64643a037a602c9591144", "in": "path", "name": "group_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-21T14:03:12.000Z", "credits_reserved": 500, "id": "group_56ff59d335d64643a037a602c9591144", "stages": [ { "depends_on": [ "fld_1e57b877a78db86124936f976015f646" ], "field_id": "fld_1e57b877a78db86124936f976015f646", "job_id": "job_d60ef6b2d188d2801bd33bf129195874", "requested_rows": 500, "status": "succeeded" } ], "status": "stopped", "stop_requested": false, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:05:40.000Z", "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "$ref": "#/components/schemas/RunGroupResponse" } } }, "description": "Success", "headers": { "Deprecation": { "description": "When this operation was deprecated: `@` and seconds since 1970-01-01 UTC.", "example": "@1793664000", "schema": { "type": "string" } }, "Link": { "description": "The changelog entry that names the replacement.", "example": "; rel=\"deprecation\"", "schema": { "type": "string" } }, "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Sunset": { "description": "The day after which this operation may stop working.", "example": "Mon, 01 Feb 2027 00:00:00 GMT", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Stop a run group (deprecated)", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Deprecated" } ], "x-sunset": "2027-02-01" }, "get": { "description": "Returns a multi-field run's status and each stage's status, in dependency order.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getRunGroup", "parameters": [ { "description": "The multi-field run.", "example": "group_56ff59d335d64643a037a602c9591144", "in": "path", "name": "group_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-21T14:03:12.000Z", "credits_reserved": 500, "id": "group_56ff59d335d64643a037a602c9591144", "stages": [ { "depends_on": [ "fld_1e57b877a78db86124936f976015f646" ], "field_id": "fld_1e57b877a78db86124936f976015f646", "job_id": "job_d60ef6b2d188d2801bd33bf129195874", "requested_rows": 500, "status": "succeeded" } ], "status": "running", "stop_requested": false, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:05:40.000Z", "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "$ref": "#/components/schemas/RunGroupResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a multi-field run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/run-groups/{group_id}/stop": { "post": { "description": "Stops a multi-field run you started. Stages not yet sent do not run; answers already received are kept and unused credits are released. Runs in the background; poll Get a multi-field run until it ends.\n\nPermission: Run enrichments, or be the member who started the run. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "stopMultiFieldRun", "parameters": [ { "description": "The multi-field run.", "example": "group_56ff59d335d64643a037a602c9591144", "in": "path", "name": "group_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-21T14:03:12.000Z", "credits_reserved": 500, "id": "group_56ff59d335d64643a037a602c9591144", "stages": [ { "depends_on": [ "fld_1e57b877a78db86124936f976015f646" ], "field_id": "fld_1e57b877a78db86124936f976015f646", "job_id": "job_d60ef6b2d188d2801bd33bf129195874", "requested_rows": 500, "status": "succeeded" } ], "status": "stopped", "stop_requested": false, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:05:40.000Z", "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "$ref": "#/components/schemas/RunGroupResponse" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Stop a multi-field run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/runs": { "get": { "description": "Returns your enrichment runs, newest first, ties by descending ID, optionally by status, table or start time. Get a run answers one run's progress. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listRuns", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } }, { "description": "Only those in this status.", "example": "succeeded", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "queued", "running", "succeeded", "failed", "stopped", "needs_review" ], "type": "string" } }, { "description": "Only runs on this table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "query", "name": "table_id", "required": false, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Only those started at or after this RFC 3339 time.", "example": "2026-10-01T00:00:00.000Z", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "action": "email_finder", "created_at": "2026-10-21T14:03:12.000Z", "field_id": "fld_1e57b877a78db86124936f976015f646", "id": "job_f799d04594ff4df5347c941a1018d24f", "object": "run", "provider": "leadmagic", "record_count": 250, "requested_rows": 250, "status": "succeeded", "stop_requested": false, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:05:40.000Z" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/RunPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List runs", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Starts an enrichment run on one field. Send either the preview token from Preview a run, or the selection with `spend_cap`: the server then prices the run and starts it in this one call only if the price fits the cap. Spends credits when it runs on Appenda's managed keys, and calls the connected provider. Runs in the background; poll Get a run. Its results add one entry to version history. When every selected record is missing an input, nothing runs and no credits are spent: the answer is `200` with no run id, the records counted in `missing_input_count` and the history entry that records them. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Run enrichments. Rate limit: provider. See [Rate limits](#description/rate-limits), [Credits](#description/credits).", "operationId": "createJob", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "callback_url": "https://hooks.example.com/appenda", "credential_id": "cred_772ad6fd9b6f3d01a25cb34c169bf1b9", "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "options": { "force": false, "mode": { "count": 500, "kind": "first" } }, "spend_cap": { "max_rows": 500 }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "id": "job_d60ef6b2d188d2801bd33bf129195874", "kind": "enrichment", "missing_input_count": 12, "object": "run", "record_count": 250, "requested_rows": 250, "spend": { "billing_quote": { "billable_outcomes": [ "success" ], "billing_unit": "row", "credits_per_unit": 1, "maximum_credits": 500, "maximum_units": 500, "method_id": "email_finder", "provider_id": "appenda", "schema_version": 1 }, "max_credits": 500, "max_rows": 500, "reserved_credits": 500 }, "status": "queued", "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/JobAcceptedResponse" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Start a run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/runs/preview": { "post": { "description": "Prices an enrichment run on one field without starting it: the rows it reaches, the most calls and credits it may spend, and a preview token for Start a run. Nothing is charged.\n\nPermission: Run enrichments. Rate limit: provider. See [Rate limits](#description/rate-limits), [Credits](#description/credits).", "operationId": "previewJob", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "field_id": "fld_1e57b877a78db86124936f976015f646", "kind": "enrichment", "options": { "force": false, "mode": { "kind": "all" } }, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" }, "schema": { "$ref": "#/components/schemas/JobPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "approval_required": false, "billing_quote": { "billable_outcomes": [ "success" ], "billing_unit": "row", "credits_per_unit": 1, "maximum_credits": 500, "maximum_units": 500, "method_id": "email_finder", "provider_id": "appenda", "schema_version": 1 }, "credential_id": null, "expires_at": "2026-10-21T14:18:12.000Z", "intent_id": "run_oct_emails", "max_calls": 500, "preview_token": "pvw_v1.EXAMPLE-preview-token-not-a-real-value", "requested_rows": 500 } }, "schema": { "$ref": "#/components/schemas/JobPreviewResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Preview a run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/runs/{run_id}": { "get": { "description": "Returns an enrichment run: its status, the field it fills and its record counts (done, found, empty, skipped and failed).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getJob", "parameters": [ { "description": "The run. On List credit transactions, only that run's charges.", "example": "job_f799d04594ff4df5347c941a1018d24f", "in": "path", "name": "run_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "action": "email_finder", "completed_rows": 240, "created_at": "2026-09-14T09:12:44.000Z", "credits": { "estimated": 50, "estimated_decimal": 50, "key_source": "appenda", "used": 48, "used_decimal": 48 }, "failed_rows": 8, "field_id": "fld_1e57b877a78db86124936f976015f646", "id": "job_d60ef6b2d188d2801bd33bf129195874", "kind": "enrichment", "needs_review_rows": 2, "no_result_rows": 30, "object": "run", "outcome_class_counts": { "error_internal": 1, "error_no_credits": 2, "error_provider": 8, "stopped_by_user": 4 }, "provider": "leadmagic", "record_count": 250, "records_done": 240, "records_empty": 30, "records_failed": 8, "records_found": 198, "records_skipped": 4, "requested_rows": 250, "skipped_rows": 4, "status": "succeeded", "stop_requested": false, "succeeded_rows": 198, "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z", "waiting_for": [], "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/runs/{run_id}/stop": { "post": { "description": "Stops an enrichment run. Rows not yet sent are not run and not charged; answers already received are kept. Runs in the background; poll Get a run until it ends.\n\nPermission: Run enrichments. Rate limit: write. See [Rate limits](#description/rate-limits), [Credits](#description/credits).", "operationId": "stopJob", "parameters": [ { "description": "The run. On List credit transactions, only that run's charges.", "example": "job_f799d04594ff4df5347c941a1018d24f", "in": "path", "name": "run_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "data": { "id": "job_d60ef6b2d188d2801bd33bf129195874", "stop_requested": true, "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "$ref": "#/components/schemas/JobStopResponse" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Stop a run", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables": { "get": { "description": "Returns the tables in the workspace, oldest first, ties by ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listTables", "parameters": [ { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-09-14T09:12:44.000Z", "dedupe": { "enabled": true, "keep_newest": false, "tiers": [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] }, "forked_from": { "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "version_id": "ver_commit_d42e4a6b3b74003ed5031158a1847494" }, "id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "name": "Series B SaaS accounts", "updated_at": "2026-10-21T13:58:02.000Z" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/TablePage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List tables", "tags": [ "Tables" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates an empty table with the given name. Adds an entry to version history. Without an `Idempotency-Key`, if a table with this name already exists, returns it with 200 and writes nothing, so a retried create never makes a second table. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Create and delete tables. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createTable", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Series B SaaS accounts" }, "schema": { "$ref": "#/components/schemas/TableWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "dedupe": { "enabled": true, "keep_newest": false, "tiers": [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] }, "id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "name": "Series B SaaS accounts" } }, "schema": { "$ref": "#/components/schemas/TableMutation" } } }, "description": "It already existed: the existing object, and nothing was written.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "201": { "content": { "application/json": { "example": { "data": { "dedupe": { "enabled": true, "keep_newest": false, "tiers": [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] }, "id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "name": "Series B SaaS accounts" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a table", "tags": [ "Tables" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}": { "delete": { "description": "Deletes a table with its fields, records, views and table interfaces. Adds an entry to version history. Cannot be undone through the API: restoring or forking a version needs the table, so both answer 404 once it is deleted. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Create and delete tables. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteTable", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true, "id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Delete a table", "tags": [ "Tables" ], "x-badges": [ { "name": "Beta" } ] }, "get": { "description": "Returns one table: its name, timestamps and deduplication setting.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getTable", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-09-14T09:12:44.000Z", "dedupe": { "enabled": true, "keep_newest": false, "tiers": [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] }, "forked_from": { "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "version_id": "ver_commit_d42e4a6b3b74003ed5031158a1847494" }, "id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "name": "Series B SaaS accounts", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/TableResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a table", "tags": [ "Tables" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Renames a table. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateTable", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Series B SaaS accounts" }, "schema": { "$ref": "#/components/schemas/TableWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "dedupe": { "enabled": true, "keep_newest": false, "tiers": [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] }, "id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "name": "Series B SaaS accounts" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Rename a table", "tags": [ "Tables" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/aggregate": { "post": { "description": "Counts, sums or averages a table's records for a chart or dashboard, optionally filtered by field key and grouped by a field or a time bucket, and returns up to 100 result rows. Nothing is saved.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "aggregateTable", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "spec": { "metrics": [ { "label": "Pipeline value", "operation": "count" } ], "source": { "kind": "table", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f" } } }, "schema": { "$ref": "#/components/schemas/AggregateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "rows": [ { "group": "Meeting booked", "series": "Enterprise", "values": [ 1250000 ] } ], "truncated": false } }, "schema": { "$ref": "#/components/schemas/AggregateResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Aggregate table data", "tags": [ "Interfaces" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/auto-run": { "delete": { "description": "Turns off auto-run for a table. Nothing new starts; answers already on their way are kept.\n\nPermission: Manage integrations. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "disableAutoRun", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "state": "disabled", "status": "off", "trigger": "new_records" } }, "schema": { "$ref": "#/components/schemas/AutoRunResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Turn off auto-run", "tags": [ "Automatic runs" ], "x-badges": [ { "name": "Beta" } ] }, "get": { "description": "Returns a table's auto-run settings: whether new records start enrichment runs on their own, on which fields and view, and the budgets left.\n\nPermission: Manage integrations. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getAutoRun", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "state": "disabled", "status": "off", "trigger": "new_records" } }, "schema": { "$ref": "#/components/schemas/AutoRunResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get auto-run settings", "tags": [ "Automatic runs" ], "x-badges": [ { "name": "Beta" } ] }, "put": { "description": "Turns on auto-run for a table: new records that enter the given view run the given enrichment fields, within per-batch and per-day budgets, until you turn it off. Existing records are never backfilled. Spends credits and calls the connected provider as new records arrive. Up to 10 fields. Replaces earlier settings; a changed field configuration or view filter needs a new call. Only an Admin or Owner who can manage integrations can call it.\n\nPermission: Manage integrations. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "configureAutoRun", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "field_ids": [ "fld_1e57b877a78db86124936f976015f646" ], "max_credits_per_batch": 100, "max_credits_per_day": 1000, "max_rows_per_batch": 50, "max_rows_per_day": 500, "trigger": "new_records", "view_id": "view_a013e65c011b856c46e9d282545f1211" }, "schema": { "$ref": "#/components/schemas/AutoRunConfig" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "expires_at": "9999-01-01T00:00:00.000Z", "field_ids": [ "fld_1e57b877a78db86124936f976015f646" ], "generation": 1, "grant_id": "autorun_10436b01cc2eeedb48cab490da15de75", "instance_id": "inst_9e815b66d1186bb90d2d77fbd69009df", "max_credits_per_batch": 100, "max_credits_per_day": 1000, "max_rows_per_batch": 50, "max_rows_per_day": 500, "state": "pending", "status": "on", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "trigger": "new_records", "view_id": "view_a013e65c011b856c46e9d282545f1211", "workspace_id": "ws_2e056e042c3953f816e10bb208432f9e" } }, "schema": { "$ref": "#/components/schemas/AutoRunResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Turn on auto-run", "tags": [ "Automatic runs" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/csv-export": { "post": { "description": "Exports a table's or a view's records as CSV, one page per call, in the sort the request or view gives, then table order, ties by ID; send `cursor` for the next page. Each page is recorded in the workspace's audit log.\n\nPermission: Export. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "exportCsv", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "delimiter": "comma", "limit": 100, "view_id": "view_a013e65c011b856c46e9d282545f1211" }, "schema": { "$ref": "#/components/schemas/CsvExportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "csv": "Company domain,Work email\r\nnorthbeam.io,priya.raman@northbeam.io\r\n", "rows": 100 }, "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/CsvExportPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Export a CSV", "tags": [ "CSV" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/csv-import": { "post": { "deprecated": true, "description": "Deprecated. Use Start a CSV import instead; this operation keeps working until at least 2027-02-01. See [Versioning](https://appenda.app/docs/api/versioning).\n\nImports a CSV into a table, creating fields as mapped. Set `dry_run` to see the proposed import without writing anything. A `preview_token` from Preview a CSV import, if sent, refuses a file, mapping or table that changed since. For files over 1,000 rows, use Start a CSV import. Adds one entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "importCsv", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "csv": "Company domain,Lead stage,Notes\r\nledgerline.com,Meeting booked,Asked for pricing\r\n", "mappings": [ { "field": "company_domain", "kind": "existing" }, { "field": "lead_stage", "kind": "existing" }, { "kind": "skip" } ], "match": { "field": "company_domain", "overwrite": "fill_empty" } }, "schema": { "$ref": "#/components/schemas/CsvImportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "duplicates_removed": 4, "fields_added": 2, "records_added": 980, "rows_added": 980, "values_emptied": 3 } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/CsvImportResult" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Deprecation": { "description": "When this operation was deprecated: `@` and seconds since 1970-01-01 UTC.", "example": "@1793577600", "schema": { "type": "string" } }, "Link": { "description": "The changelog entry that names the replacement.", "example": "; rel=\"deprecation\"", "schema": { "type": "string" } }, "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Sunset": { "description": "The day after which this operation may stop working.", "example": "Mon, 01 Feb 2027 00:00:00 GMT", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Import a CSV (deprecated)", "tags": [ "CSV" ], "x-badges": [ { "name": "Deprecated" } ], "x-sunset": "2027-02-01" } }, "/v1/tables/{table_id}/csv-imports": { "post": { "description": "Starts a chunked import from the first part of a CSV. Set `dry_run` to see the proposed import without starting one. Send the remaining rows with Upload a CSV chunk and end with Finish a CSV import. A file may hold up to 100,000 rows and 50 MiB. The finished import adds one entry to version history.\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "startCsvImportJob", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "csv": "Company domain,Deal stage,Notes\r\nledgerline.com,Meeting booked,Asked for pricing\r\n", "mappings": [ { "field": "company_domain", "kind": "existing" }, { "key": "deal_stage", "kind": "create", "name": "Deal stage", "type": "text" }, { "kind": "skip" } ] }, "schema": { "$ref": "#/components/schemas/CsvImportRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "chunks_applied": 12, "commit_id": null, "created_at": "2026-10-21T14:03:12.000Z", "fields_added": 2, "id": "csvi_71bdd9226218f46867d26a5795bc2041", "records_added": 980, "rows_added": 980, "state": "running", "status": "running", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T14:04:01.000Z", "values_emptied": 3 } }, "schema": { "$ref": "#/components/schemas/CsvImportJobResponse" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Start a CSV import", "tags": [ "CSV" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/csv-imports/preview": { "post": { "description": "Reads a CSV file of up to 1,000 data rows and proposes how its columns map to the table's fields, with the rows to add, the fields to create and the values that would be left empty. Returns a preview token for Import a CSV. Nothing is written.\n\nPermission: Edit records. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "previewCsvImport", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "csv": "Company domain,Lead stage,Notes\r\nledgerline.com,Meeting booked,Asked for pricing\r\n", "mappings": [ { "field": "company_domain", "kind": "existing" }, { "field": "lead_stage", "kind": "existing" }, { "kind": "skip" } ], "match": { "field": "company_domain", "overwrite": "fill_empty" } }, "schema": { "$ref": "#/components/schemas/CsvImportPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "columns": [ { "header": "Company domain", "match": "existing", "suggest_select": false, "suggested_mapping": { "kind": "skip" } } ], "duplicates_to_remove": 4, "fields_to_add": 2, "mappings": [ { "kind": "skip" } ], "preview_token": "pvw_v1.EXAMPLE-preview-token-not-a-real-value", "records_read": 980, "records_to_add": 976, "rows_read": 980, "rows_to_add": 976, "sample": [ [ "northbeam.io", "priya.raman@northbeam.io" ] ], "values_emptied": 3 } }, "schema": { "$ref": "#/components/schemas/CsvImportPreview" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Preview a CSV import", "tags": [ "CSV" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/dedupe": { "put": { "description": "Turns deduplication of new records on or off for a table and sets which fields make two records the same. While it is on, a created or imported record that matches a kept one is dropped, or replaces it when `keep_newest` is true. Existing records are not changed. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "setTableDedupe", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "enabled": true, "tiers": [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] }, "schema": { "$ref": "#/components/schemas/TableDedupeWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "dedupe": { "enabled": true, "keep_newest": false, "tiers": [ [ "fld_b00a97266f03cceb43636653c0e40b38" ], [ "fld_1e57b877a78db86124936f976015f646" ] ] }, "id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "name": "Series B SaaS accounts" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Set table deduplication", "tags": [ "Tables" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/enrichment-fields": { "post": { "description": "Adds an enrichment field that fills each record from a provider action. Build it from Get action parameters: name the action and its `schema_version`, and map each input to a field, a fixed value or a template. Each mistake is refused naming the input in `param`. The field's key comes from `name`: lowercased, with each run of other characters as one `_` (`Work email` is `work_email`); a key the table already has gets `_2`, `_3` and so on. Send `dry_run: true` to check the field without creating it. Nothing runs and nothing is charged until you start a run. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createEnrichmentField", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "action": "email_finder", "inputs": { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "last_name": { "field": "last_name" } }, "name": "Work email", "provider": "leadmagic", "schema_version": 2 }, "schema": { "$ref": "#/components/schemas/EnrichmentFieldCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "config": { "action": "email_finder", "inputs": { "domain": "fld_b00a97266f03cceb43636653c0e40b38", "first_name": "fld_3b9ed9139c16536a8e36fd6279b1a510", "last_name": "fld_4ad93454e0feed19f81e719c13744619" }, "output": null, "provider": "leadmagic" }, "id": "fld_1e57b877a78db86124936f976015f646", "key": "work_email", "name": "Work email", "object": "field", "position": 4, "read_only": true, "type": "enrichment", "updated_at": "2026-10-21T14:03:12.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/FieldMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create an enrichment field", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/enrichment-fields/{field_id}": { "patch": { "description": "Replaces an enrichment field's configuration: its provider action, inputs, output and run condition. Values already in the field stay until a run replaces them. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateEnrichmentField", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The field.", "example": "fld_1e57b877a78db86124936f976015f646", "in": "path", "name": "field_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "action": "email_finder", "inputs": { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "last_name": { "field": "last_name" } }, "name": "Work email", "provider": "leadmagic", "schema_version": 2 }, "schema": { "$ref": "#/components/schemas/EnrichmentFieldWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "config": { "action": "email_finder", "inputs": { "domain": "fld_b00a97266f03cceb43636653c0e40b38", "first_name": "fld_3b9ed9139c16536a8e36fd6279b1a510", "last_name": "fld_4ad93454e0feed19f81e719c13744619" }, "output": null, "provider": "leadmagic" }, "id": "fld_1e57b877a78db86124936f976015f646", "key": "work_email", "name": "Work email", "object": "field", "position": 4, "read_only": true, "type": "enrichment", "updated_at": "2026-10-21T14:03:12.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/FieldMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update an enrichment field", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/enrichment-fields/{field_id}/credential": { "patch": { "description": "Chooses which key an enrichment field runs with: Appenda's managed key or one of the workspace's own keys for the provider. The rest of its configuration is unchanged. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateEnrichmentCredential", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The field.", "example": "fld_1e57b877a78db86124936f976015f646", "in": "path", "name": "field_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "credential_source": "managed" }, "schema": { "$ref": "#/components/schemas/EnrichmentCredentialBinding" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "config": { "action": "email_finder", "inputs": { "domain": "fld_b00a97266f03cceb43636653c0e40b38", "first_name": "fld_3b9ed9139c16536a8e36fd6279b1a510", "last_name": "fld_4ad93454e0feed19f81e719c13744619" }, "output": null, "provider": "leadmagic" }, "id": "fld_1e57b877a78db86124936f976015f646", "key": "work_email", "name": "Work email", "object": "field", "position": 4, "read_only": true, "type": "enrichment", "updated_at": "2026-10-21T14:03:12.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/FieldMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Set enrichment field key", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/fields": { "get": { "description": "Returns a table's fields in display order, ties by ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listFields", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/FieldPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List fields", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Adds a field to a table: `type` chooses its kind and `config` its settings (a number's display format, a select's choices, a formula's `expressions` in priority order, a lookup's path). Formulas and lookups name other fields by `{field_key}`. With `dry_run`, checks the field and returns it without creating it. To add an enrichment field, use Create an enrichment field. Adds an entry to version history. Without an `Idempotency-Key`, if a field with this key, name and type already exists, returns it with 200 and writes nothing. Any other field under the key is refused. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createField", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "config": { "format": { "currency": "USD", "decimals": 2, "style": "currency" } }, "key": "arr", "name": "ARR", "type": "number" }, "schema": { "$ref": "#/components/schemas/FieldCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/FieldMutation" } } }, "description": "It already existed: the existing object, and nothing was written.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "201": { "content": { "application/json": { "example": { "data": { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/FieldMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a field", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/fields/{field_id}": { "delete": { "description": "Deletes a field and its value in every record. Deleting a waterfall also deletes its step fields. Adds an entry to version history. To undo it, restore an earlier version of the table. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteField", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The field.", "example": "fld_1e57b877a78db86124936f976015f646", "in": "path", "name": "field_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true, "id": "fld_1e57b877a78db86124936f976015f646" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Delete a field", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] }, "get": { "description": "Returns one field: its name, key, type and options.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getField", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The field.", "example": "fld_1e57b877a78db86124936f976015f646", "in": "path", "name": "field_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/FieldResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a field", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Renames a field, changes its settings or converts it to another type. A new `config.format` only changes how values show and rewrites none. A new `type` that rewrites values needs `convert: true`: each value is read as text and parsed as the new type, and a value that doesn't fit is emptied. With `dry_run`, returns what would convert and empty, with samples, and changes nothing. Formula and enrichment fields are never converted to or from. To change an enrichment field's configuration, use Update an enrichment field. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateField", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The field.", "example": "fld_1e57b877a78db86124936f976015f646", "in": "path", "name": "field_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "convert": true, "dry_run": true, "type": "number" }, "schema": { "$ref": "#/components/schemas/FieldUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/FieldMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update a field", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/fields/{field_id}/outputs": { "get": { "description": "Returns the paths a JSON or enrichment field's values hold, most covered first, ties by path, from up to 50 records spread evenly over the table among those that have a value, with an example of each. To make fields from them, use Create output fields. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listFieldOutputs", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The field.", "example": "fld_1e57b877a78db86124936f976015f646", "in": "path", "name": "field_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "coverage": 0.96, "declared": true, "example": "northbeam.io", "field_id": "fld_1e57b877a78db86124936f976015f646", "object": "field_output", "path": "company.domain", "type": "text" } ], "meta": { "has_more": false, "next_cursor": null, "sampled_records": 50 } }, "schema": { "$ref": "#/components/schemas/FieldOutputPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List field outputs", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates one field per output, each reading its path from the source field and following it as the source changes. All or nothing, up to 50 per request. Adds an entry to version history.\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createOutputFields", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The field.", "example": "fld_1e57b877a78db86124936f976015f646", "in": "path", "name": "field_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "outputs": [ { "path": "company.domain" }, { "name": "Current title", "path": "experience.0.title" } ] }, "schema": { "$ref": "#/components/schemas/OutputFieldsCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": [ { "config": { "path": "company.domain", "result_type": "text", "source_field": "company_profile" }, "id": "fld_7aa2ec62bf3badc48f63684017b448ef", "key": "company_domain", "name": "Company domain", "object": "field", "position": 8, "read_only": true, "type": "lookup", "updated_at": "2026-10-21T14:03:12.000Z" }, { "config": { "path": "experience.0.title", "result_type": "text", "source_field": "company_profile" }, "id": "fld_3c81e6f4a9d2470b8e15c7a2906bd4f1", "key": "current_title", "name": "Current title", "object": "field", "position": 9, "read_only": true, "type": "lookup", "updated_at": "2026-10-21T14:03:12.000Z" } ] }, "schema": { "$ref": "#/components/schemas/OutputFieldsCreated" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create output fields", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/formulas/preview": { "post": { "description": "Checks a formula against a table and returns its values for up to 12 records, without saving anything. Use it before you create or update a formula field.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "previewFormula", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expression": "{first_name} & \" \" & {last_name}" }, "schema": { "$ref": "#/components/schemas/FormulaPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "error": null, "referenced_field_ids": [ "fld_3b9ed9139c16536a8e36fd6279b1a510", "fld_4ad93454e0feed19f81e719c13744619" ], "rows": [ { "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "value": "Priya Raman" } ] } }, "schema": { "$ref": "#/components/schemas/FormulaPreviewResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Preview a formula", "tags": [ "Fields" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/records": { "get": { "description": "Returns a table's records in table order, ties by ID, with every field's value. Optionally filter using field keys. To sort or search, use Search records. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listRecords", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } }, { "description": "JSON filter using field keys. URL-encode it in the query string.", "example": "{\"match\":\"all\",\"rules\":[{\"field\":\"work_email\",\"operator\":\"contains\",\"value\":\"@northbeam.io\"}]}", "in": "query", "name": "filter", "required": false, "schema": { "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/FilterSpec" }, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "cells": { "fld_4ac9744e5c4b96172195f7f2f070a486": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" }, "fld_7a852289ea2135b37304ae3217fa47e0": "2026-10-21", "fld_b00a97266f03cceb43636653c0e40b38": "northbeam.io" }, "fields": { "company_domain": "northbeam.io", "last_contacted": "2026-10-21", "lead_stage": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" } }, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "updated_at": "2026-10-21T13:58:02.000Z", "version": 7 } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/RecordPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List records", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates one record. While the table deduplicates new records, a record that matches a kept one is not written and the request answers `409`. Adds one entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createRecord", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "fields": { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } }, "schema": { "$ref": "#/components/schemas/RecordWrite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RecordCreated" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a record", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/records/bulk": { "patch": { "description": "Updates up to 100 records in one request; each names its record and the fields to change, and fields left out keep their values. To change one record, use Update a record. Adds one entry to version history. `data` has one entry per input, in input order; a refused request writes nothing and names the input at fault in `param`. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateRecords", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "records": [ { "fields": { "lead_stage": "Contacted" }, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" } ] }, "schema": { "$ref": "#/components/schemas/RecordsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "index": 2, "outcome": "updated" } ] }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RecordsUpdated" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Bulk update records", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates up to 100 records in one request, and at most 256 KiB once written. While the table deduplicates new records, inputs that match a kept record are dropped or replace it, and `meta` counts them; overlapping creates of one record still write it once. Adds one entry to version history for the whole request. `data` has one entry per input, in input order. A refused request writes nothing and names the input at fault in `param`, such as `records[17].fields.work_email`. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createRecords", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "records": [ { "fields": { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } } ] }, "schema": { "$ref": "#/components/schemas/RecordsCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": [ { "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "index": 2, "matched_id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "outcome": "skipped" } ], "meta": { "created": 2, "replaced": 1, "skipped": 1 } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RecordsMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Bulk create records", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/records/bulk-delete": { "post": { "description": "Deletes up to 100 records by id, or every record a view or filter keeps, up to `max_records` (at most 1,000). If the selection keeps more than `max_records`, nothing is deleted. Send `expected_count` to also refuse a selection whose count changed. Send exactly one of `record_ids`, `view_id` or `filter`. Adds one entry to version history. To undo it, restore an earlier version of the table. Deleting by `record_ids` answers them in the order sent; an unknown or repeated id fails the request, named in `param` (`record_ids[3]`). An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteRecords", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "record_ids": [ "rec_ec89f0cdf353cb742933bb0c607f918c", "rec_47a0f9d1a76df13293377a1be53f515f" ] }, "schema": { "$ref": "#/components/schemas/RecordsDelete" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "deleted": true, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" } ] }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RecordsDeleted" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Bulk delete records", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/records/query": { "post": { "description": "Returns the records that match a filter, optionally narrowed by a text search across text fields, in the order you sort them, then table order, ties by ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "queryRecords", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "filter": { "root": { "combinator": "and", "items": [ { "field_id": "fld_4ac9744e5c4b96172195f7f2f070a486", "operator": "is", "value": { "kind": "text", "value": "Meeting booked" } } ] } }, "limit": 50, "search": "northbeam", "sort": { "keys": [ { "direction": "desc", "field_id": "fld_5e8f73060c995895e07dfe7f6f6edd23" } ] } }, "schema": { "$ref": "#/components/schemas/RecordQuery" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "cells": { "fld_4ac9744e5c4b96172195f7f2f070a486": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" }, "fld_7a852289ea2135b37304ae3217fa47e0": "2026-10-21", "fld_b00a97266f03cceb43636653c0e40b38": "northbeam.io" }, "fields": { "company_domain": "northbeam.io", "last_contacted": "2026-10-21", "lead_stage": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" } }, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "updated_at": "2026-10-21T13:58:02.000Z", "version": 7 } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/RecordPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Search records", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/records/upsert": { "post": { "description": "Updates the records whose match field equals an input's value and creates the rest, up to 100 inputs in one request; `meta` counts the records created and updated. Send `dry_run: true` to see how many records it would create and update without writing anything. Adds one entry to version history. `data` has one entry per input, in input order; a refused request writes nothing and names the input at fault in `param`. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "upsertRecords", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "match_field": "company_domain", "records": [ { "fields": { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } } ] }, "schema": { "$ref": "#/components/schemas/RecordsUpsert" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "index": 2, "outcome": "updated" } ], "meta": { "created": 1, "updated": 1 } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RecordsUpsertResult" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Bulk upsert records", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/records/{record_id}": { "delete": { "description": "Deletes one record. Adds an entry to version history. To undo it, restore an earlier version of the table. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteRecord", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The record.", "example": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "in": "path", "name": "record_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "deleted": true, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4" } ] }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RecordsDeleted" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Delete a record", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] }, "get": { "description": "Returns one record with every field's value. An enrichment field's value is the provider's answer, or, when the record failed, an object holding `_appenda_error` with its `type`, `class`, `label`, `message` and optional `action`. Treat an unknown `class` as a failure. See [Enrichment fields](https://appenda.app/docs/api/enrichment-fields).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getRecord", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The record.", "example": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "in": "path", "name": "record_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "cells": { "fld_4ac9744e5c4b96172195f7f2f070a486": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" }, "fld_7a852289ea2135b37304ae3217fa47e0": "2026-10-21", "fld_b00a97266f03cceb43636653c0e40b38": "northbeam.io" }, "fields": { "company_domain": "northbeam.io", "last_contacted": "2026-10-21", "lead_stage": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" } }, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "updated_at": "2026-10-21T13:58:02.000Z", "version": 7 } }, "schema": { "$ref": "#/components/schemas/RecordResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a record", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Changes some field values of one record; fields left out keep their values. To change many records, use Bulk update records. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateRecord", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The record.", "example": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "in": "path", "name": "record_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "fields": { "company_domain": "northbeam.io", "lead_stage": "Meeting booked" } }, "schema": { "$ref": "#/components/schemas/RecordWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "index": 2, "outcome": "updated" } ] }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RecordsUpdated" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update a record", "tags": [ "Records" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/versions": { "get": { "description": "Returns a table's restorable versions, newest first, ties by descending ID, each with who made its history entry and from which API key. Every version is kept for 7 days, then the newest of each day for 30 days; a table's newest version is always kept. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listTableVersions", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "actor": { "api_key_id": "ak_184992130055f27f212a3582fc736e9e", "channel": "api", "id": "user_1ccece3aa6e3f736614f0238ca636876" }, "commit_id": "commit_d42e4a6b3b74003ed5031158a1847494", "created_at": "2026-10-21T13:58:02.000Z", "field_count": 9, "id": "ver_commit_d42e4a6b3b74003ed5031158a1847494", "message": "Enriched 212 work emails", "object": "table_version", "record_count": 212, "ref": "de6127v", "restorable": true, "short_id": "de6127v" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/TableVersionPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List table versions", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/versions/{version_id}": { "get": { "description": "Returns one version of a table with the fields it had then. Read its records with List a version's records.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getTableVersion", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The version: the history entry it was captured at.", "example": "ver_commit_d42e4a6b3b74003ed5031158a1847494", "in": "path", "name": "version_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "actor": { "api_key_id": "ak_184992130055f27f212a3582fc736e9e", "channel": "api", "id": "user_17e9c7164b4f3ae302c6b1dc88fc6b34" }, "commit_id": "commit_d42e4a6b3b74003ed5031158a1847494", "created_at": "2026-10-21T13:58:02.000Z", "field_count": 9, "fields": [ { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" } ], "id": "ver_commit_d42e4a6b3b74003ed5031158a1847494", "message": "Enriched 212 work emails", "object": "table_version", "record_count": 212, "ref": "de6127v", "restorable": true, "short_id": "de6127v" } }, "schema": { "$ref": "#/components/schemas/TableVersionResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a table version", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/versions/{version_id}/changes": { "get": { "description": "Compares a table version with another version or with the table as it is now (`compare_to=current`) and returns the fields and records added, removed or changed, with the counts a restore would report. Lists field changes first, then record changes, each ordered by ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "getVersionChanges", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The version: the history entry it was captured at.", "example": "ver_commit_d42e4a6b3b74003ed5031158a1847494", "in": "path", "name": "version_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } }, { "description": "What to compare the version with: another version's id, or `current` for the table as it is now.", "example": "current", "in": "query", "name": "compare_to", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "after": { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" }, "before": { "config": { "expressions": [ "{work_email_score}", "{fallback_score}" ], "output_format": { "number": { "decimals": 0 } }, "references": [ "fallback_score", "work_email_score" ], "result_type": "number" }, "id": "fld_b00a97266f03cceb43636653c0e40b38", "key": "lead_score", "name": "Lead score", "object": "field", "position": 7, "read_only": true, "type": "formula", "updated_at": "2026-10-21T13:58:02.000Z" }, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "kind": "field_added" } ], "meta": { "counts": { "cells_changed": 212, "fields_added": 2, "fields_changed": 1, "fields_removed": 1, "records_added": 980, "records_changed": 212, "records_removed": 3, "rows_added": 980, "rows_changed": 212, "rows_removed": 3, "values_changed": 212 }, "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/HistoricalChangePage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Compare table versions", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/versions/{version_id}/fork": { "post": { "description": "Creates a new table from a version of this one, with all its records, the records a view showed then, or none, and answers it as Create a table does, with `records_added`. The new table records where it came from. Nothing runs on the new table. Adds an entry to version history. Copies up to about 6,800 records; for a larger table, fork a view's records or none.\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "forkTable", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The version: the history entry it was captured at.", "example": "ver_commit_d42e4a6b3b74003ed5031158a1847494", "in": "path", "name": "version_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "rows": "all" }, "schema": { "$ref": "#/components/schemas/ForkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-21T14:03:12.000Z", "forked_from": { "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "version_id": "ver_commit_d42e4a6b3b74003ed5031158a1847494" }, "id": "tbl_c9b4f80d3721cb7401bb23ae8643e40c", "name": "Series B SaaS accounts (October)", "object": "table", "records_added": 980, "rows_added": 980, "table_id": "tbl_c9b4f80d3721cb7401bb23ae8643e40c", "updated_at": "2026-10-21T14:03:12.000Z" } }, "schema": { "$ref": "#/components/schemas/ForkResult" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Fork a version", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/versions/{version_id}/records": { "get": { "description": "Returns the records a table had at a version, ordered by record ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "getVersionRecords", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The version: the history entry it was captured at.", "example": "ver_commit_d42e4a6b3b74003ed5031158a1847494", "in": "path", "name": "version_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "cells": { "fld_4ac9744e5c4b96172195f7f2f070a486": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" }, "fld_7a852289ea2135b37304ae3217fa47e0": "2026-10-21", "fld_b00a97266f03cceb43636653c0e40b38": "northbeam.io" }, "fields": { "company_domain": "northbeam.io", "last_contacted": "2026-10-21", "lead_stage": { "id": "choice_c376ae596decf98b88afd886d1777cb2", "name": "Meeting booked" } }, "id": "rec_e5d09fb0300a5d1ce095e03b7d6d1de4", "position": 2 } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/HistoricalRecordPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List a version's records", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/versions/{version_id}/restore": { "post": { "description": "Restores a table to a version in one call, as a new entry in version history; the entries before it are kept. Send `dry_run: true` to get the counts without writing anything. With `expected_commit_id`, a table whose newest history entry has changed is refused with `table_changed`. A table already equal to the version answers `changed: false` and writes nothing. Nothing is sent to providers again.\n\nPermission: Edit records. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "restoreTable", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The version: the history entry it was captured at.", "example": "ver_commit_d42e4a6b3b74003ed5031158a1847494", "in": "path", "name": "version_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "dry_run": true }, "schema": { "$ref": "#/components/schemas/RestoreRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "cells_changed": 212, "changed": true, "commit_id": "commit_da351ef8de3782b2c6c7632fd2ae9945", "dry_run": false, "fields_added": 2, "fields_changed": 1, "fields_removed": 1, "object": "restore", "records_added": 980, "records_changed": 212, "records_removed": 3, "rows_added": 980, "rows_changed": 212, "rows_removed": 3, "values_changed": 212, "version_id": "ver_commit_d42e4a6b3b74003ed5031158a1847494" } }, "schema": { "$ref": "#/components/schemas/RestoreResult" } } }, "description": "A dry run, or a table already equal to the version: the counts, and nothing was written.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "201": { "content": { "application/json": { "example": { "data": { "cells_changed": 212, "changed": true, "commit_id": "commit_da351ef8de3782b2c6c7632fd2ae9945", "dry_run": false, "fields_added": 2, "fields_changed": 1, "fields_removed": 1, "object": "restore", "records_added": 980, "records_changed": 212, "records_removed": 3, "rows_added": 980, "rows_changed": 212, "rows_removed": 3, "values_changed": 212, "version_id": "ver_commit_d42e4a6b3b74003ed5031158a1847494" } }, "schema": { "$ref": "#/components/schemas/RestoreResult" } } }, "description": "Success", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Restore a version", "tags": [ "Version control" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/views": { "get": { "description": "Returns a table's views, including its default view, oldest first, ties by ID. This list is paginated; see [Pagination](#description/pagination).\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits), [Pagination](#description/pagination).", "operationId": "listViews", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size, 1 to 100. A value outside that range is refused, not clamped.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The previous page's `meta.next_cursor`.", "example": "eyJhdCI6MTcyOTUxOTM5MiwiaWQiOiJ0YmxfOGYyYzFhIn0", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-09-14T09:12:44.000Z", "filter": { "match": "all", "rules": [ { "field": "company_name", "operator": "is_any_of", "value": [ "Northbeam", "Acme" ] }, { "field": "employee_count", "operator": "gte", "value": 50 } ] }, "id": "view_a013e65c011b856c46e9d282545f1211", "is_default": false, "name": "Hot leads", "object": "view", "sort": [ { "direction": "desc", "field": "employee_count" } ], "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z" } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/ViewPage" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "List views", "tags": [ "Views" ], "x-badges": [ { "name": "Beta" } ] }, "post": { "description": "Creates a named view: a saved filter and sort over a table's records. Adds an entry to version history. Without an `Idempotency-Key`, if a view with this name, filter and sort already exists, returns it with 200 and writes nothing. Any other view under the name is refused. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createView", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Hot leads" }, "schema": { "$ref": "#/components/schemas/ViewCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-09-14T09:12:44.000Z", "filter": { "match": "all", "rules": [ { "field": "company_name", "operator": "is_any_of", "value": [ "Northbeam", "Acme" ] }, { "field": "employee_count", "operator": "gte", "value": 50 } ] }, "id": "view_a013e65c011b856c46e9d282545f1211", "is_default": false, "name": "Hot leads", "object": "view", "sort": [ { "direction": "desc", "field": "employee_count" } ], "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/ViewMutation" } } }, "description": "It already existed: the existing object, and nothing was written.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "201": { "content": { "application/json": { "example": { "data": { "created_at": "2026-09-14T09:12:44.000Z", "filter": { "match": "all", "rules": [ { "field": "company_name", "operator": "is_any_of", "value": [ "Northbeam", "Acme" ] }, { "field": "employee_count", "operator": "gte", "value": 50 } ] }, "id": "view_a013e65c011b856c46e9d282545f1211", "is_default": false, "name": "Hot leads", "object": "view", "sort": [ { "direction": "desc", "field": "employee_count" } ], "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/ViewMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a view", "tags": [ "Views" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/views/{view_id}": { "delete": { "description": "Deletes a view; the records it showed are not affected. The default view cannot be deleted. Adds an entry to version history. Cannot be undone; create the view again to bring it back. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "deleteView", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The view.", "example": "view_a013e65c011b856c46e9d282545f1211", "in": "path", "name": "view_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true, "id": "view_a013e65c011b856c46e9d282545f1211" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Delete a view", "tags": [ "Views" ], "x-badges": [ { "name": "Beta" } ] }, "get": { "description": "Returns one view: its name, filter and sort.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getView", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The view.", "example": "view_a013e65c011b856c46e9d282545f1211", "in": "path", "name": "view_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-09-14T09:12:44.000Z", "filter": { "match": "all", "rules": [ { "field": "company_name", "operator": "is_any_of", "value": [ "Northbeam", "Acme" ] }, { "field": "employee_count", "operator": "gte", "value": 50 } ] }, "id": "view_a013e65c011b856c46e9d282545f1211", "is_default": false, "name": "Hot leads", "object": "view", "sort": [ { "direction": "desc", "field": "employee_count" } ], "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/ViewResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a view", "tags": [ "Views" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Renames a view or changes its filter and sort. A rename adds an entry to version history; a filter or sort change alone does not. The default view cannot be changed. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateView", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The view.", "example": "view_a013e65c011b856c46e9d282545f1211", "in": "path", "name": "view_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Hot leads EMEA" }, "schema": { "$ref": "#/components/schemas/ViewUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-09-14T09:12:44.000Z", "filter": { "match": "all", "rules": [ { "field": "company_name", "operator": "is_any_of", "value": [ "Northbeam", "Acme" ] }, { "field": "employee_count", "operator": "gte", "value": 50 } ] }, "id": "view_a013e65c011b856c46e9d282545f1211", "is_default": false, "name": "Hot leads EMEA", "object": "view", "sort": [ { "direction": "desc", "field": "employee_count" } ], "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/ViewMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update a view", "tags": [ "Views" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/views/{view_id}/duplicate": { "post": { "description": "Copies a view with its filter and sort. Without a name the copy is called `Copy of `. Adds an entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Edit views and interfaces. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "duplicateView", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The view.", "example": "view_a013e65c011b856c46e9d282545f1211", "in": "path", "name": "view_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Hot leads (EMEA)" }, "schema": { "$ref": "#/components/schemas/ViewDuplicate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "created_at": "2026-09-14T09:12:44.000Z", "filter": { "match": "all", "rules": [ { "field": "company_name", "operator": "is_any_of", "value": [ "Northbeam", "Acme" ] }, { "field": "employee_count", "operator": "gte", "value": 50 } ] }, "id": "view_5c2f8e1a9b7d4e3f6a0c1b2d3e4f5a6b", "is_default": false, "name": "Hot leads (EMEA)", "object": "view", "sort": [ { "direction": "desc", "field": "employee_count" } ], "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/ViewMutation" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Duplicate a view", "tags": [ "Views" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/waterfalls": { "post": { "description": "Creates a waterfall: an ordered list of provider actions for one capability (find an email, find a phone, validate an email) that stops at the first result a step accepts. Every step runs on the workspace's own key. Send `dry_run: true` to check it without creating it. Nothing runs and nothing is charged until you start a run. Adds one entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "createWaterfall", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "capability": "email_finder", "inputs": { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "full_name": { "field": "full_name" }, "last_name": { "field": "last_name" } }, "name": "Work email", "steps": [ { "action": "email_finder", "provider": "icypeas" }, { "action": "email_finder", "credential": "cred_971e3efd6924ee8db473896da8f1c630", "provider": "findymail" } ] }, "schema": { "$ref": "#/components/schemas/WaterfallCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "config": { "capability": "email_finder", "inputs": { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "full_name": { "field": "full_name" }, "last_name": { "field": "last_name" } }, "max_credits_per_row": null, "steps": [ { "accept": [ "valid", "catch_all" ], "action": "email_finder", "credential": null, "credits_per_call": 0, "id": "fld_0f3c5a9e8b2d4716a5c9e1b7d3f60a28", "inputs": { "domain_or_company": { "field": "company_domain" }, "firstname": { "field": "first_name" }, "lastname": { "field": "last_name" } }, "object": "waterfall_step", "position": 1, "provider": "icypeas" }, { "accept": [ "valid", "catch_all" ], "action": "email_finder", "credential": "cred_971e3efd6924ee8db473896da8f1c630", "credits_per_call": 0, "id": "fld_7aa2ec62bf3badc48f63684017b448ef", "inputs": { "domain": { "field": "company_domain" }, "name": { "field": "full_name" } }, "object": "waterfall_step", "position": 2, "provider": "findymail" } ], "stop_on": "first_accepted" }, "id": "fld_c0b164fe5c18cba45982317d1144de3e", "key": "work_email", "name": "Work email", "object": "field", "position": 7, "type": "waterfall" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/WaterfallResponse" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Create a waterfall", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/tables/{table_id}/waterfalls/{waterfall_id}": { "get": { "description": "Returns a waterfall field: its capability, inputs and steps in order, with what each step accepts.\n\nPermission: Read tables. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getWaterfall", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The waterfall's merged field id (`fld_…`), the `id` Create a waterfall returns.", "example": "fld_c0b164fe5c18cba45982317d1144de3e", "in": "path", "name": "waterfall_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "config": { "capability": "email_finder", "inputs": { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "full_name": { "field": "full_name" }, "last_name": { "field": "last_name" } }, "max_credits_per_row": null, "steps": [ { "accept": [ "valid", "catch_all" ], "action": "email_finder", "credential": null, "credits_per_call": 0, "id": "fld_0f3c5a9e8b2d4716a5c9e1b7d3f60a28", "inputs": { "domain_or_company": { "field": "company_domain" }, "firstname": { "field": "first_name" }, "lastname": { "field": "last_name" } }, "object": "waterfall_step", "position": 1, "provider": "icypeas" }, { "accept": [ "valid", "catch_all" ], "action": "email_finder", "credential": "cred_971e3efd6924ee8db473896da8f1c630", "credits_per_call": 0, "id": "fld_7aa2ec62bf3badc48f63684017b448ef", "inputs": { "domain": { "field": "company_domain" }, "name": { "field": "full_name" } }, "object": "waterfall_step", "position": 2, "provider": "findymail" } ], "stop_on": "first_accepted" }, "id": "fld_c0b164fe5c18cba45982317d1144de3e", "key": "work_email", "name": "Work email", "object": "field", "position": 7, "type": "waterfall" } }, "schema": { "$ref": "#/components/schemas/WaterfallResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get a waterfall", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] }, "patch": { "description": "Replaces a waterfall's steps with the ordered list you send: a step with an `id` is kept, one without is added, and one left out is removed. Send `dry_run: true` to check the change without saving it. Adds one entry to version history. An API user token whose role requires approval gets the same status with an approval to poll instead. See [Approvals](#tag/approvals).\n\nPermission: Add and delete fields. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "updateWaterfall", "parameters": [ { "description": "The table.", "example": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "in": "path", "name": "table_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "The waterfall's merged field id (`fld_…`), the `id` Create a waterfall returns.", "example": "fld_c0b164fe5c18cba45982317d1144de3e", "in": "path", "name": "waterfall_id", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "steps": [ { "id": "fld_7aa2ec62bf3badc48f63684017b448ef" }, { "action": "email_finder", "provider": "icypeas" } ] }, "schema": { "$ref": "#/components/schemas/WaterfallUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "config": { "capability": "email_finder", "inputs": { "domain": { "field": "company_domain" }, "first_name": { "field": "first_name" }, "full_name": { "field": "full_name" }, "last_name": { "field": "last_name" } }, "max_credits_per_row": null, "steps": [ { "accept": [ "valid", "catch_all" ], "action": "email_finder", "credential": "cred_971e3efd6924ee8db473896da8f1c630", "credits_per_call": 0, "id": "fld_7aa2ec62bf3badc48f63684017b448ef", "inputs": { "domain": { "field": "company_domain" }, "name": { "field": "full_name" } }, "object": "waterfall_step", "position": 1, "provider": "findymail" }, { "accept": [ "valid", "catch_all" ], "action": "email_finder", "credential": null, "credits_per_call": 0, "id": "fld_0f3c5a9e8b2d4716a5c9e1b7d3f60a28", "inputs": { "domain_or_company": { "field": "company_domain" }, "firstname": { "field": "first_name" }, "lastname": { "field": "last_name" } }, "object": "waterfall_step", "position": 2, "provider": "icypeas" } ], "stop_on": "first_accepted" }, "id": "fld_c0b164fe5c18cba45982317d1144de3e", "key": "work_email", "name": "Work email", "object": "field", "position": 7, "type": "waterfall" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/WaterfallResponse" }, { "$ref": "#/components/schemas/ApprovalHeld" } ] } } }, "description": "Success, or held for an approver: nothing ran yet. Poll the approval named in `Location`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Update waterfall steps", "tags": [ "Enrichment" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/usage": { "get": { "description": "Returns runs, outcomes and credits per provider action, key source and UTC day, for a range of up to 366 days, ordered by day, then provider, action, capability and key source. Usage is kept after its field or table is deleted. Not paged: one answer holds the whole range, and a range too large to answer at once is refused; narrow it and ask again.\n\nPermission: Read integrations. Rate limit: read. See [Rate limits](#description/rate-limits).", "operationId": "getProviderUsage", "parameters": [ { "description": "First UTC day, `YYYY-MM-DD`.", "example": "2026-10-01", "in": "query", "name": "from", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Last UTC day, `YYYY-MM-DD`; not before `from`, at most 366 days after it.", "example": "2026-10-21", "in": "query", "name": "to", "required": true, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "action": "email_finder", "capability": "work_email", "credits": 870, "credits_decimal": 120, "credits_per_found": 1, "day": "2026-10-20", "found_rate": 0.7, "found_rows": 870, "key_source": "appenda", "method_id": "email_finder", "outcomes": [ { "outcome": "valid", "record_count": 870, "rows": 870 } ], "provider": "leadmagic", "provider_id": "appenda", "record_count": 1240, "rows": 1240, "runs": 6 } ], "meta": { "has_more": false, "next_cursor": null } }, "schema": { "$ref": "#/components/schemas/ProviderUsageResponse" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Get credit usage", "tags": [ "Credits" ], "x-badges": [ { "name": "Beta" } ] } }, "/v1/workspace": { "patch": { "description": "Renames the workspace.\n\nPermission: Admin or Owner; instance settings need an instance admin. Rate limit: write. See [Rate limits](#description/rate-limits).", "operationId": "renameWorkspace", "parameters": [ { "description": "Optional. 1–200 visible characters; a repeat returns the first response. See [Errors](#description/errors).", "example": "retry-2026-10-21-0001", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Northbeam GTM" }, "schema": { "$ref": "#/components/schemas/RenameRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "ws_2e056e042c3953f816e10bb208432f9e", "name": "Northbeam GTM", "updated_at": "2026-10-21T13:58:02.000Z" } }, "schema": { "$ref": "#/components/schemas/RenameResult" } } }, "description": "Success", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "summary": "Rename the workspace", "tags": [ "Settings" ], "x-badges": [ { "name": "Beta" } ] } } }, "security": [ { "bearer": [] } ], "servers": [ { "url": "https://api.appenda.app" } ], "tags": [ { "description": "Manage the tables in a workspace: list, create, rename, deduplicate and delete them.", "name": "Tables" }, { "description": "Manage a table's fields, including formula fields, and check a formula before you save it.", "name": "Fields" }, { "description": "Read, search, count, create, update and delete a table's records, one at a time or up to 100 per request.", "name": "Records" }, { "description": "Manage a table's named views: saved filters and sorts over its records.", "name": "Views" }, { "description": "Import CSV files into a table, small ones in one call and large ones in chunks, and export a table or view as CSV.", "name": "CSV" }, { "description": "Manage interfaces: dashboards of charts, filters and sections built over your tables.", "name": "Interfaces" }, { "description": "Add enrichment fields and run them: preview what a run costs, start it, follow it and stop it. Deleting an enrichment field with Delete a field removes its results from every record; fields made from its outputs stay.", "name": "Enrichment" }, { "description": "Let new records in a table start enrichment runs on their own, within budgets you set.", "name": "Automatic runs" }, { "description": "Read and stop the workspace's list imports. An API token can't start one yet.", "name": "List import" }, { "description": "See which providers your plan allows, connect your own provider keys and read provider usage.", "name": "Integrations" }, { "description": "Read a table's history and versions, compare versions, and restore or fork one.", "name": "Version control" }, { "description": "Review requests held for approval: approve, reject or withdraw them.", "name": "Approvals" }, { "description": "Rename the workspace or instance and manage their logos.", "name": "Settings" }, { "description": "Manage a workspace's members and roles.", "name": "Members" }, { "description": "Create workspaces in an instance.", "name": "Workspaces" }, { "description": "Create, list and revoke API user tokens and super-admin tokens. Personal tokens are retired.", "name": "API keys" }, { "description": "Read the member who owns the calling token.", "name": "Account" }, { "description": "Read the credit balance your workspace spends from and the transactions that moved it.", "name": "Credits" } ], "x-tagGroups": [ { "name": "Data", "tags": [ "Tables", "Fields", "Records", "Views", "CSV", "Interfaces" ] }, { "name": "Enrichment", "tags": [ "Enrichment", "Automatic runs", "List import", "Integrations" ] }, { "name": "History", "tags": [ "Version control", "Approvals" ] }, { "name": "Workspace", "tags": [ "Settings", "Members", "Workspaces", "API keys", "Account", "Credits" ] } ] }