Skip to Content

API

The JSON API behind the app — operations, API keys, errors, undo and approvals.

The app, the copilot and the MCP server all run on one typed API, open to scripts with an API key. /openapi.json (OpenAPI 3.1) has every operation's input and response schema.

Basics

  • Every operation is a POST to https://<your-dataembed>/api/v1/<namespace>/<operation> with a JSON body: /api/v1/records/list.
  • The body names the workspace by its short name, "workspace": "acme-k3x9q0", the first part of its pages' URLs. A key works only in its own workspace.
  • Responses are validated against their schema: what the spec says is what comes back, nothing more.
  • Each operation's x-dataembed-access says who may call it: callers (agents for keys, people for someone signed in only, anyone), scope, ownerOnly and irreversible.

Authentication

Send a workspace API key (create one) as a bearer token:

-H "Authorization: Bearer de_your_api_key"

A key acts for its creator, with their role now and its scope; its changes are logged under its name. Apps connected by signing in (deo_… tokens) reach the MCP server only. The app's own endpoint, /api/orpc, takes the session cookie only. Browser requests from other sites are refused. Each key makes at most 300 requests a minute.

Examples

Read an object's fields first; inputs name objects and fields by slug (or id), and records come back keyed by field id:

curl -X POST https://<your-dataembed>/api/v1/objects/get \
  -H "Authorization: Bearer de_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"workspace":"acme-k3x9q0","object":"companies"}'

Its object.writeAccess says, for create, update and delete, whether its records take that write, or why not (reasons).

List records with a filter (up to 200 a page; pass nextCursor back as cursor):

curl -X POST https://<your-dataembed>/api/v1/records/list \
  -H "Authorization: Bearer de_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "acme-k3x9q0",
    "object": "companies",
    "limit": 50,
    "filter": { "join": "and", "conditions": [
      { "field": "domain", "operator": "isEmpty" }
    ] }
  }'
# → { "records": [{ "id": "…", "values": { "<field id>": … } }],
#     "referenceLabels": {…}, "nextCursor": "…", "total": { "count": 12, "kind": "exact" } }

Every operator but isEmpty and isNotEmpty takes a value: a condition without one is BAD_REQUEST, never read as matching every record. total, on the first page only, is exact, an estimate from table statistics, or at_least when counting stopped. sorts takes up to five { "field", "direction" }; viewId starts from a view's filter and sorts; group narrows to one column of a board; timeZone (IANA, default UTC) is what relative dates mean.

Create up to 100 records in one call, all or none:

curl -X POST https://<your-dataembed>/api/v1/records/create \
  -H "Authorization: Bearer de_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"workspace":"acme-k3x9q0","object":"companies","records":[{"values":{"name":"Acme Corp","domain":"acme.example"}}]}'

records.update and records.delete take up to 500 records; records.import up to 500 rows, with dryRun. Counts and sums: records.aggregate; SQL: sql.query (Query).

Plugin actions: actions.list lists those the caller can run on an object (or the workspace), with their inputs: none without the write scope, and one that changes records isn't listed where that write is refused. actions.run takes the target its kind does (object, plus recordIds or field; nothing for the workspace) and refuses any other field: a target or input it can't work with is BAD_REQUEST, saying what to fix. It answers within 40 seconds with { "kind": "result" }, or with { "kind": "job" } for longer work: follow it with jobs.get (waitSeconds waits for it to end), stop it with jobs.cancel.

Values

Numbers as numbers (a string past the safe-integer range), dates YYYY-MM-DD, timestamps ISO 8601, selects as their option values, references as the target's id. A record's id is its primary key as text (a JSON array for a composite key).

Undo

A write that can be undone returns the activityIds it logged; activity.undo takes up to 500 of them and writes the values from before back, all or none. A record value changed since fails it with CONFLICT; a view, layout, workspace plugin, field or object change puts back only what wasn't changed since, and fails with CONFLICT only when all of it was. activity.list says what each entry changed and whether you may undo it.

  • Undoable: record updates (an import's included), view, layout and workspace plugin changes, object and field settings (not a key), a view's delete.
  • Final: record creates and deletes, the records an import added, creating a view, schema changes, deleting a plugin.

Approvals

An irreversible operation called with a key isn't run. It answers PENDING_APPROVAL (HTTP 403) with data.approval: its id, summary and expiresAt (24 hours). An owner or admin allows it in the app; then it runs as the key. Allowed always, the key's later calls to that operation run at once, until the allowance is revoked, each recorded as an approval with status allowed. approvals.get says whether it ran and what it answered; don't call it again meanwhile.

Errors

Errors are JSON, the HTTP status matching code:

{
  "code": "FORBIDDEN",
  "defined": false,
  "message": "This key doesn't have the Write scope (write). Create a key with it."
}
CodeWhen
BAD_REQUESTInvalid input: "Input validation failed", one entry per problem in data.issues, each with its path
UNAUTHORIZEDNo key, or not a valid one
FORBIDDENA missing scope, a role the creator doesn't have, an operation for people only, or what the database refuses: the message says
NOT_FOUNDNo such object, record, view…
CONFLICTA name or key already taken, or an undo of something changed since
PRECONDITION_FAILEDA table or column is gone (it syncs; try again), a plugin is off or needs configuration, or schema-ran (below)
TOO_MANY_REQUESTSA rate limit: the message says which
BAD_GATEWAYYour database couldn't be reached or failed the query
GATEWAY_TIMEOUTYour database ran out of time
SERVICE_UNAVAILABLEDataembed's own database is down: nothing changed, retry
PENDING_APPROVALHeld for an owner or admin (above)
SQL_ERRORsql.query: Postgres's message, its code and where

A refusal a client acts on carries data.reason: name-taken (read the names again), list-changed (a reorder didn't name the list as it is), not-a-member (the caller left or was removed), table-changed (read the objects again; fieldId names the field), schema-ran (the change stands and a sync has started: don't make it again) or may-have-saved (BAD_GATEWAY: the connection broke while committing, so read what it wrote before writing again). A record write refused over one field carries data.fieldId.

Deleting a workspace answers SERVICE_UNAVAILABLE while any of its copilot threads or jobs can't be stopped yet, including one started during the delete: "N of the workspace's copilot threads and jobs couldn't be stopped yet, so the workspace wasn't deleted. Try again in a few minutes."

Operations

Every operation a key may call, with the scope and role it needs:

OperationWhat it doesScopeWho
actions.listList plugin actionsreadAny member
activity.listList activityreadAny member
ai.modelsList the agents' modelsreadAny member
approvals.getGet an approvalreadAny member
approvals.listList approvalsreadAny member
dataSources.getGet a data sourcereadAny member
dataSources.listList data sourcesreadAny member
jobs.getGet a jobreadAny member
jobs.listList jobsreadAny member
layouts.getGet a page layoutreadAny member
members.listList membersreadAny member
objects.getGet an objectreadAny member
objects.listList objectsreadAny member
plugins.getGet a pluginreadAny member
plugins.listList pluginsreadAny member
plugins.manifestSchemaGet the plugin manifest schemareadAny member
records.aggregateAggregate recordsreadAny member
records.getGet a recordreadAny member
records.listList recordsreadAny member
records.relatedRelated recordsreadAny member
records.searchSearch recordsreadAny member
schema.previewPreview a schema changereadAny member
sql.queryRun a read-only SQL queryreadAny member
workspaces.describeDescribe the workspacereadAny member
workspaces.getGet the workspacereadAny member
actions.runRun a plugin actionwriteAny member
activity.addNoteAdd a note to a record's timelinewriteAny member
activity.undoUndo activitywriteAny member
connectedApps.listList connected appswriteAny member
connectedApps.revokeDisconnect an appwriteAny member
fields.reorderReorder an object's fieldswriteAny member
fields.updateUpdate a fieldwriteAny member
jobs.cancelCancel a jobwriteAny member
layouts.updateUpdate a page layoutwriteAny member
objects.reorderReorder objectswriteAny member
objects.updateUpdate an objectwriteAny member
plugins.createBuild a pluginwriteAny member
plugins.resetReset a workspace pluginwriteAny member
plugins.updateUpdate a workspace pluginwriteAny member
records.createCreate recordswriteAny member
records.deleteDelete recordswriteAny member
records.importImport recordswriteAny member
records.updateUpdate recordswriteAny member
views.updateUpdate a viewwriteAny member
workspaces.leaveLeave the workspacewriteAny member
ai.setModelChoose the agents' modeladminOwners and admins
apiKeys.createCreate an API keyadminOwners and admins
apiKeys.listList API keysadminOwners and admins
apiKeys.revokeRevoke an API keyadminOwners and admins
dataSources.connectConnect a data sourceadminOwners and admins
dataSources.connectSampleUse the sample databaseadminOwners and admins
dataSources.disconnectDisconnect a data sourceadminOwners and admins
dataSources.syncSync a data sourceadminOwners and admins
dataSources.testTest a data sourceadminOwners and admins
dataSources.testConnectionTest connection detailsadminOwners and admins
dataSources.updateUpdate a data sourceadminOwners and admins
dataSources.updateConnectionUpdate a data source's connectionadminOwners and admins
fields.deleteDelete a missing fieldadminOwners and admins
invitations.createInvite someoneadminOwners and admins
invitations.listList pending invitationsadminOwners and admins
invitations.revokeRevoke an invitationadminOwners and admins
layouts.saveForEveryoneSave a page layout for everyoneadminOwners and admins
members.removeRemove a memberadminOwners and admins
members.setRoleUpdate a member's roleadminOwners and admins
objects.setKeySet an object's keyadminOwners and admins
plugins.deleteDelete a workspace pluginadminOwners and admins
plugins.saveForEveryoneSave a workspace plugin for everyoneadminOwners and admins
plugins.setEnabledEnable or disable a pluginadminOwners and admins
plugins.updateSettingsUpdate plugin settingsadminOwners and admins
schema.changeChange a data source's schemaadminOwners and admins
views.createCreate a viewadminOwners and admins
views.deleteDelete a viewadminOwners and admins
views.reorderReorder viewsadminOwners and admins
views.saveForEveryoneSave a view for everyoneadminOwners and admins
workspaces.deleteDelete the workspaceadminOwners
workspaces.setNameRename the workspaceadminOwners and admins

These are for people signed in; a key gets FORBIDDEN with the reason:

OperationWhat it doesWhy agents can't
allowances.listList allowancesA person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents.
allowances.revokeRevoke an allowanceA person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents.
approvals.approveApprove a changeA person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents.
approvals.pendingCountCount waiting approvalsA person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents.
approvals.rejectReject a changeA person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents.
dataSources.tablesList a data source's tablesOnly the SQL console's completion reads it: workspaces_describe names every table and column.
invitations.acceptAccept an invitationIt joins another workspace, which widens the person's own access: only they decide that, from the invitation's link.
invitations.declineDecline an invitationIt answers the person's own invitation to another workspace, outside the workspace a credential is bound to. People answer it from the invitation's link.
invitations.getGet an invitationIt is what an invite link shows its recipient, usually about another workspace than the one a credential is bound to. This workspace's invitations are listed by invitations_list.
threads.deleteDelete a copilot threadA copilot conversation is the person's own: they start, follow and delete it in the copilot panel. Agents reach dataembed through these tools instead.
threads.eventsFollow a copilot threadA copilot conversation is the person's own: they start, follow and delete it in the copilot panel. Agents reach dataembed through these tools instead.
threads.getGet a copilot threadA copilot conversation is the person's own: they start, follow and delete it in the copilot panel. Agents reach dataembed through these tools instead.
threads.interruptStop the copilotA copilot conversation is the person's own: they start, follow and delete it in the copilot panel. Agents reach dataembed through these tools instead.
threads.listList copilot threadsA copilot conversation is the person's own: they start, follow and delete it in the copilot panel. Agents reach dataembed through these tools instead.
threads.sendMessageMessage the copilotA copilot conversation is the person's own: they start, follow and delete it in the copilot panel. Agents reach dataembed through these tools instead.
threads.startStart a copilot threadA copilot conversation is the person's own: they start, follow and delete it in the copilot panel. Agents reach dataembed through these tools instead.
waitlist.approveLet someone inOnly the deployment's operators let people in, signed in on the operator page (/operator): it opens sign-up to someone, outside any workspace.
waitlist.listList the waitlistOnly the deployment's operators let people in, signed in on the operator page (/operator): it opens sign-up to someone, outside any workspace.
workspaces.createCreate a workspaceIt creates another workspace, which a credential bound to this one could never act in. People do it from the sidebar's workspace menu.
workspaces.listList my workspacesIt lists the person's other workspaces, which a credential bound to this one can't act in. People do it from the sidebar's workspace menu.

A database password is write-only: never returned. Agents that speak MCP use the same key at /api/mcp; see Agents.

On this page