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
POSTtohttps://<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-accesssays who may call it:callers(agentsfor keys,peoplefor someone signed in only,anyone),scope,ownerOnlyandirreversible.
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."
}| Code | When |
|---|---|
BAD_REQUEST | Invalid input: "Input validation failed", one entry per problem in data.issues, each with its path |
UNAUTHORIZED | No key, or not a valid one |
FORBIDDEN | A missing scope, a role the creator doesn't have, an operation for people only, or what the database refuses: the message says |
NOT_FOUND | No such object, record, view… |
CONFLICT | A name or key already taken, or an undo of something changed since |
PRECONDITION_FAILED | A table or column is gone (it syncs; try again), a plugin is off or needs configuration, or schema-ran (below) |
TOO_MANY_REQUESTS | A rate limit: the message says which |
BAD_GATEWAY | Your database couldn't be reached or failed the query |
GATEWAY_TIMEOUT | Your database ran out of time |
SERVICE_UNAVAILABLE | Dataembed's own database is down: nothing changed, retry |
PENDING_APPROVAL | Held for an owner or admin (above) |
SQL_ERROR | sql.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:
| Operation | What it does | Scope | Who |
|---|---|---|---|
actions.list | List plugin actions | read | Any member |
activity.list | List activity | read | Any member |
ai.models | List the agents' models | read | Any member |
approvals.get | Get an approval | read | Any member |
approvals.list | List approvals | read | Any member |
dataSources.get | Get a data source | read | Any member |
dataSources.list | List data sources | read | Any member |
jobs.get | Get a job | read | Any member |
jobs.list | List jobs | read | Any member |
layouts.get | Get a page layout | read | Any member |
members.list | List members | read | Any member |
objects.get | Get an object | read | Any member |
objects.list | List objects | read | Any member |
plugins.get | Get a plugin | read | Any member |
plugins.list | List plugins | read | Any member |
plugins.manifestSchema | Get the plugin manifest schema | read | Any member |
records.aggregate | Aggregate records | read | Any member |
records.get | Get a record | read | Any member |
records.list | List records | read | Any member |
records.related | Related records | read | Any member |
records.search | Search records | read | Any member |
schema.preview | Preview a schema change | read | Any member |
sql.query | Run a read-only SQL query | read | Any member |
workspaces.describe | Describe the workspace | read | Any member |
workspaces.get | Get the workspace | read | Any member |
actions.run | Run a plugin action | write | Any member |
activity.addNote | Add a note to a record's timeline | write | Any member |
activity.undo | Undo activity | write | Any member |
connectedApps.list | List connected apps | write | Any member |
connectedApps.revoke | Disconnect an app | write | Any member |
fields.reorder | Reorder an object's fields | write | Any member |
fields.update | Update a field | write | Any member |
jobs.cancel | Cancel a job | write | Any member |
layouts.update | Update a page layout | write | Any member |
objects.reorder | Reorder objects | write | Any member |
objects.update | Update an object | write | Any member |
plugins.create | Build a plugin | write | Any member |
plugins.reset | Reset a workspace plugin | write | Any member |
plugins.update | Update a workspace plugin | write | Any member |
records.create | Create records | write | Any member |
records.delete | Delete records | write | Any member |
records.import | Import records | write | Any member |
records.update | Update records | write | Any member |
views.update | Update a view | write | Any member |
workspaces.leave | Leave the workspace | write | Any member |
ai.setModel | Choose the agents' model | admin | Owners and admins |
apiKeys.create | Create an API key | admin | Owners and admins |
apiKeys.list | List API keys | admin | Owners and admins |
apiKeys.revoke | Revoke an API key | admin | Owners and admins |
dataSources.connect | Connect a data source | admin | Owners and admins |
dataSources.connectSample | Use the sample database | admin | Owners and admins |
dataSources.disconnect | Disconnect a data source | admin | Owners and admins |
dataSources.sync | Sync a data source | admin | Owners and admins |
dataSources.test | Test a data source | admin | Owners and admins |
dataSources.testConnection | Test connection details | admin | Owners and admins |
dataSources.update | Update a data source | admin | Owners and admins |
dataSources.updateConnection | Update a data source's connection | admin | Owners and admins |
fields.delete | Delete a missing field | admin | Owners and admins |
invitations.create | Invite someone | admin | Owners and admins |
invitations.list | List pending invitations | admin | Owners and admins |
invitations.revoke | Revoke an invitation | admin | Owners and admins |
layouts.saveForEveryone | Save a page layout for everyone | admin | Owners and admins |
members.remove | Remove a member | admin | Owners and admins |
members.setRole | Update a member's role | admin | Owners and admins |
objects.setKey | Set an object's key | admin | Owners and admins |
plugins.delete | Delete a workspace plugin | admin | Owners and admins |
plugins.saveForEveryone | Save a workspace plugin for everyone | admin | Owners and admins |
plugins.setEnabled | Enable or disable a plugin | admin | Owners and admins |
plugins.updateSettings | Update plugin settings | admin | Owners and admins |
schema.change | Change a data source's schema | admin | Owners and admins |
views.create | Create a view | admin | Owners and admins |
views.delete | Delete a view | admin | Owners and admins |
views.reorder | Reorder views | admin | Owners and admins |
views.saveForEveryone | Save a view for everyone | admin | Owners and admins |
workspaces.delete | Delete the workspace | admin | Owners |
workspaces.setName | Rename the workspace | admin | Owners and admins |
These are for people signed in; a key gets FORBIDDEN with the reason:
| Operation | What it does | Why agents can't |
|---|---|---|
allowances.list | List allowances | A person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents. |
allowances.revoke | Revoke an allowance | A person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents. |
approvals.approve | Approve a change | A person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents. |
approvals.pendingCount | Count waiting approvals | A person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents. |
approvals.reject | Reject a change | A person decides what agents may do: owners and admins approve or reject held changes and revoke allowances in Settings → AI & agents. |
dataSources.tables | List a data source's tables | Only the SQL console's completion reads it: workspaces_describe names every table and column. |
invitations.accept | Accept an invitation | It joins another workspace, which widens the person's own access: only they decide that, from the invitation's link. |
invitations.decline | Decline an invitation | It 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.get | Get an invitation | It 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.delete | Delete a copilot thread | A 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.events | Follow a copilot thread | A 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.get | Get a copilot thread | A 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.interrupt | Stop the copilot | A 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.list | List copilot threads | A 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.sendMessage | Message the copilot | A 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.start | Start a copilot thread | A 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.approve | Let someone in | Only the deployment's operators let people in, signed in on the operator page (/operator): it opens sign-up to someone, outside any workspace. |
waitlist.list | List the waitlist | Only the deployment's operators let people in, signed in on the operator page (/operator): it opens sign-up to someone, outside any workspace. |
workspaces.create | Create a workspace | It creates another workspace, which a credential bound to this one could never act in. People do it from the sidebar's workspace menu. |
workspaces.list | List my workspaces | It 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.