REST API

Erdo’s REST API lets you integrate your data platform into any application. Query datasets, write data, manage conversations, create automations, and more — all via standard HTTP requests. Base URL: https://api.erdo.ai OpenAPI spec: the API Reference section in the sidebar is generated from the full machine-readable OpenAPI spec — every /v1 endpoint with its request and response schemas. Point a code generator or a coding agent at the spec to build a typed client. Authentication: All requests require a Bearer token in the Authorization header.

curl https://api.erdo.ai/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting an API Key

Click your profile in the bottom-left corner of Erdo and go to API Keys. Create a new key and copy the token — it’s shown only once. To replace a key, choose Rotate beside it and confirm. The old key stops working immediately, and Erdo shows the replacement secret only once. Copy it and update every application that uses the key. If you no longer need a key, choose Revoke instead. Rotation keeps the key’s owner, name, default organization, access mode, and scope. Its original lifetime starts again from the time of rotation, capped at 36,500 days (100 years). For example, rotating a 30-day key gives the replacement 30 days from rotation; it does not carry over only the remaining days. You can also rotate with POST /v1/tokens/{id}/rotate. Only the key’s owner can rotate it, and a scoped or read-only API key cannot initiate rotation. The response includes the new token and replaced_token_id; store the new token when it is returned because it cannot be read again. An admin of a member’s home organization sees that member’s keys and can revoke one, but cannot rotate it. A replacement acts as its owner — in every organization the owner belongs to, including ones the admin cannot reach — so handing the admin a working secret would widen their access. Revoke the key and let its owner create the replacement. An unscoped API key is an account-level credential: it acts as you, and works in any organization you’re a member of. The organization stored on the key is only its default org — the one used when a request doesn’t name one. It is not a hard scope. Scoped API keys have explicit capability and resource limits. To use an unscoped key in a specific organization, send the X-Organization-ID header with the org’s id or slug. The backend validates on every request that you’re a member of that org, so a key cannot reach an org you don’t belong to:

# Uses the key's default org
curl https://api.erdo.ai/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY"

# Targets a specific org you belong to
curl https://api.erdo.ai/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: acme"

Manage keys from the CLI too: erdo token create --name ci, erdo token list, erdo token rotate <id>, erdo token revoke <id>. Set a command’s org with erdo --org acme <command> or change the active default with erdo org use acme.

Project context

Projects are optional work context inside an organization. To run a request in one, send its slug or its UUID as X-Project-ID together with the organization header:

curl https://api.erdo.ai/v1/datasets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: acme" \
  -H "X-Project-ID: launch-2026"

The project must belong to the active organization. Erdo rejects an invalid, inaccessible, or cross-organization project on authenticated API and MCP requests rather than silently falling back to organization-wide scope. Project-aware list endpoints such as datasets and conversations narrow to resources attached to the project; new conversations, datasets, and workflow outputs are attached when the caller has contributor access. Endpoints that are explicitly organization-wide remain organization-wide. List projects with GET /v1/projects (or erdo project list) and pass the same context to the CLI with erdo --org acme --project <slug> <command>. Bounded outreach is stricter: every consent, batch, recipient, and action request requires X-Project-ID. It never falls back to organization-wide scope because consent, suppression, provider receipts, and retries must stay in one authenticated project. The key’s user must also be a persisted owner or admin of the active organization.

Scoped API Keys

A server that only needs part of the API should not hold a key that can do everything. Mint a scoped API key with a capability allowlist (e.g. datasets:query) and optional dataset/workstream slugs — every endpoint outside its grants is denied, and no capability can mint keys, touch managed organizations, or connect/delete integrations.

Scoped Tokens

For building apps where your end-users interact with Erdo, use scoped tokens to restrict access to specific datasets and threads.

API Surface

API keys and scoped tokens work on the documented API surface: every /v1 endpoint, the /mcp endpoint, and the endpoints used by the published SDKs (scoped-token minting, thread messaging, agent invocation, dataset reads). Requests to any other path return 403 permission_denied — other routes are internal to the Erdo app and not a stable contract to build against. If you need a capability that isn’t on /v1 yet, tell us rather than coupling to an internal route.

Errors

A failed request answers with a JSON body carrying a machine-readable code and a message written to be acted on:

{ "code": "invalid_argument", "message": "dataset_slug is required" }

The status code tells you whose problem it is, which is the distinction worth building on. A 4xx means Erdo understood the request and turned it down — retrying it unchanged will fail the same way, so read the message and change something. A 5xx means Erdo itself failed; the same request may well succeed on retry, and it is worth telling us about.

Status	`code`	What it means
400	`invalid_argument`	A field is missing, malformed, or two mutually exclusive options were sent together. Ambiguity lands here too — asking for an app when several instances of it are connected answers with the ids to choose from.
401	`unauthenticated`	No usable credential on the request.
403	`permission_denied`	The credential is valid but may not do this — including a scoped key reaching outside its grants.
404	`not_found`	You named something that does not exist in the active organization: a dataset, a page, a connected integration, an app slug.
409	`already_exists`	The thing you asked to create is already there.
412	`failed_precondition`	The request is well formed, but the organization’s current state does not allow it yet — reading replies before a sending domain is registered, or building a queryable dataset on an integration that cannot back one. The message names the step that unblocks it.
429	`resource_exhausted`	A rate limit or an exhausted credit balance.
500	`internal`	Erdo failed. Retry, and tell us if it persists.

Agent-facing messages name the next tool or endpoint to call where one exists, so a coding agent driving the API can usually recover from a 4xx without a human reading the docs.

Datasets

List Datasets

GET /v1/datasets

Returns all datasets in your organization.

Parameter	Type	Description
`limit`	number	Max results (default 20, max 100)
`offset`	number	Pagination offset

Each thread includes its canonical title, creator ID, creator name and email when that user is still in the organization, and its creation source. New threads without an explicit name are titled from their first user message.

curl "https://api.erdo.ai/v1/datasets?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "datasets": [
    {
      "id": "uuid",
      "slug": "my-org.sales-data",
      "name": "Sales Data",
      "description": "Monthly sales figures",
      "type": "file",
      "status": "active"
    }
  ],
  "total": 42
}

Configure an Integration Dataset

POST /v1/integration-datasets/{dataset_id}/configure

Update an existing integration dataset using the same generic segments returned by Discover Tables. Setting enable_sync materializes sync-capable integrations through Erdo’s canonical data platform; it does not create a snapshot dataset.

Parameter	Type	Description
`segments`	string[]	Segment names or ids to include. Omit when disabling the sync, or when re-enabling one that already has a scope
`enable_sync`	boolean	Enable canonical data-platform sync after saving the scope. Sent on its own, it restores a retired sync and leaves the saved scope untouched
`disable_sync`	boolean	Retire a superseded or stale synced dataset — tears down the synced copy and stops the dataset being read or monitored. Reversible with `enable_sync`, which builds a new copy, so the first sync after a restore is a full load
`replaced_by`	string	With `disable_sync`: slug of the dataset that takes over, in the same organization. Automations that read the retired dataset are moved onto it

curl -X POST "https://api.erdo.ai/v1/integration-datasets/DATASET_ID/configure" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"segments": ["ACCOUNT_OR_SCHEMA_ID"], "enable_sync": true}'

Retire a dataset left syncing by a connection that was replaced, then restore it:

curl -X POST "https://api.erdo.ai/v1/integration-datasets/DATASET_ID/configure" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disable_sync": true}'

curl -X POST "https://api.erdo.ai/v1/integration-datasets/DATASET_ID/configure" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enable_sync": true}'

Create Dataset

POST /v1/datasets-create

Create a new empty dataset with its columns declared up front. Every write is checked against that declaration, which is set when the dataset is created rather than taken from its first rows. Uses your organization’s default storage backend. After creation, use Write Rows to add data.

Parameter	Type	Description
`name`	string	Name for the dataset
`description`	string	Optional description
`instructions`	string	Optional instructions for AI agents analyzing this dataset
`purpose`	string	The dataset’s role in your org’s vocabulary, e.g. `"leads"`. Check List Dataset Purposes first — if the purpose already exists, reuse its dataset instead of creating a sibling: one purpose maps to one dataset per org, and a create for a purpose the org already has is refused with the existing dataset’s slug (a second dataset for the same purpose splits its rows across tables).
`purpose_description`	string	Optional. What this purpose means in your org (what writes to it, what reads it). Establishes the vocabulary entry when the purpose is new.
`separate_dataset`	boolean	Optional. `true` only to deliberately run a parallel table for a purpose the org already has — a separate program you chose to run. The default refuses and names the dataset to reuse.
`access`	string	Who can use the dataset: `organization` (default) so agents and teammates can use it, or `private` to keep it to the creating user
`schema`	object	`{"columns": [{"name", "type", "required", "description", "semantic_role", "currency"}]}`. Required, except for a purpose whose columns Erdo defines (`page events`, `widget events`, `widget leads`); those take Erdo’s columns and any you pass are added. For `leads`, include `email` and/or `phone` and every form field; Erdo adds `submitted_at` and `canonical_lead_id`. A create without it is refused with `invalid_argument`.

The response may carry warnings — advisory findings such as plural/singular near-misses of an existing purpose. Creating a second dataset for an established purpose is refused (not warned): the error names the dataset to reuse.

curl -X POST "https://api.erdo.ai/v1/datasets-create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Daily Metrics", "description": "Automated metrics from our monitoring pipeline", "purpose": "daily metrics", "purpose_description": "Monitoring pipeline metrics, appended daily", "schema": {"columns": [{"name": "day", "type": "date", "required": true}, {"name": "requests", "type": "integer"}]}}'

List Dataset Purposes

GET /v1/datasets-purposes

The org’s dataset vocabulary: every purpose (dataset role) in use, its description, the dataset currently carrying it, that dataset’s declared schema, and how many datasets carry it. This is the deterministic answer to both “which dataset holds this data?” and “which fields does its producer write?” — no name-searching or separate schema lookup. Consult it before creating a dataset; when the purpose exists, reuse the dataset carrying it and validate your producer against declared_schema. Every org starts with the platform-provisioned entries (leads, page events, widget events, widget leads — present when the org uses each kind), and the vocabulary grows as you assign purposes to new datasets.

curl "https://api.erdo.ai/v1/datasets-purposes" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "purposes": [
    {
      "purpose": "leads",
      "description": "Lead/form submissions captured by this org's lead pipelines, upserted by email — one row per lead…",
      "established_by_dataset_id": "3425ac45-…",
      "established_by_dataset_slug": "my-org.leads",
      "dataset_id": "3425ac45-…",
      "dataset_slug": "my-org.leads",
      "declared_schema": {
        "columns": [
          {"name": "email", "type": "text", "required": true},
          {"name": "submitted_at", "type": "date", "required": true}
        ]
      },
      "dataset_count": 1,
      "datasets": [
        {"dataset_slug": "my-org.leads", "integration_config_key": ""}
      ]
    }
  ]
}

datasets lists every dataset currently carrying the purpose, ordered by slug, even when dataset_count is greater than one and no single dataset_slug is returned. For a dataset synced from a connected integration, integration_config_key names its provider; it is empty otherwise, and also when the integration belongs to a different organization than the dataset. dataset_slug is the current write target to reuse, and declared_schema is its producer contract. The established_by_* fields remain for audit and compatibility; they identify the dataset that first introduced the vocabulary entry and can differ after a purpose moves. Add ?scope=managed from a manager account to read the same vocabulary across every client organization it operates. Each entry then carries organization_slug and organization_name, and its established_by_dataset_slug is organization-qualified — so you can query a client’s dataset directly without switching organizations:

curl "https://api.erdo.ai/v1/datasets-purposes?scope=managed" \
  -H "Authorization: Bearer YOUR_API_KEY"

scope=managed is for the manager organization’s admins and owners — the same people who can switch into a client. Anybody else gets a permission error naming the requirement, rather than an empty list that reads like there is nothing there. An organization that manages no clients gets an empty purposes array and a message saying so, rather than an empty answer that reads like a failed query.

Ensure a Purpose Dataset

POST /v1/datasets-ensure

Use this for a durable producer. It creates the organization dataset when the purpose is new, reuses it when the stored schema matches, or adopts preferred_dataset when you already have an authoritative binding. The declared schema is stored before a newly created dataset receives its purpose, and concurrent calls for one purpose converge on one dataset.

curl -X POST "https://api.erdo.ai/v1/datasets-ensure" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead grades",
    "purpose": "lead grades",
    "purpose_description": "Grades written by the lead review workflow",
    "preferred_dataset": "my-org.lead-grades",
    "declared_schema": {"columns": [
      {"name": "lead_email", "type": "text", "required": true},
      {"name": "grade", "type": "text"}
    ]}
  }'

The response includes created, the resolved dataset identity, and its actual declared_schema. A purpose carried by multiple datasets, a populated legacy dataset with no declaration, or an incompatible contract returns a conflict naming the migration required; the endpoint never silently chooses one. When a producer has reviewed a contract change, reviewed_optional_additions may list optional column names from declared_schema. On the existing unique purpose-bound file dataset, Erdo validates the complete contract and adds only those missing, typed columns while holding the purpose, ownership, and dataset-write locks. Unknown, required, duplicate, undeclared, or invalidly typed names are refused before mutation. The default ensure request remains strict; this field does not authorize adoption of a split, repurposed, or unrelated dataset. For the leads purpose, a newly created dataset gets permanent lead identity at creation. Add email_column and phone_column (default email/phone) to name which declared columns hold the contact evidence the identity resolver reads — at least one must exist in your contract, or the request is refused rather than capturing nothing. The returned declared_schema also carries the platform-owned canonical_lead_id key column, which you never declare or write; ensuring the same purpose again with your original contract stays compatible.

Upload a File as a Dataset

POST /v1/datasets-upload

Upload a file and create a dataset from it in one call. The file’s schema is extracted before the response returns, so the dataset is immediately queryable. Prefer this over Create Dataset + Write Rows when your data already exists as a file.

Parameter	Type	Description
`filename`	string	Filename with extension — drives type detection (`.csv`, `.tsv`, `.xlsx`, `.json`, `.jsonl`, `.pdf`, `.docx`, `.txt`, `.md`, …)
`content_base64`	string	The raw file bytes, base64-encoded (max 20 MB decoded; use the web app’s resumable upload for larger files)
`name`	string	Optional display name; defaults to the filename
`description`	string	Optional description shown to AI agents analyzing the dataset
`access`	string	Who can use the dataset: `organization` (default) so agents and teammates can use it, or `private` to keep it to the uploading user

# base64 -w0 keeps the output on one line (GNU coreutils wraps at 76 cols by
# default, which would break the JSON string); on macOS `base64 -i leads.csv`.
curl -X POST "https://api.erdo.ai/v1/datasets-upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"leads.csv\", \"name\": \"Leads\", \"content_base64\": \"$(base64 -w0 leads.csv)\"}"

ready reports whether schema extraction succeeded; when false, the file stored but is not yet queryable (a warning explains why).

{
  "dataset_id": "uuid",
  "slug": "my-org.leads",
  "name": "Leads",
  "ready": true
}

Delete Dataset

DELETE /v1/datasets/:slug

Permanently delete a dataset and all its data. Requires admin permission on the dataset.

curl -X DELETE "https://api.erdo.ai/v1/datasets/my-org.daily-metrics" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Datasets

GET /v1/datasets-search

Search datasets by name.

Parameter	Type	Description
`query`	string	Search text

curl "https://api.erdo.ai/v1/datasets-search?query=revenue" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Dataset Schema

GET /v1/datasets/:id/schema

Get detailed schema for a dataset including column names, types, statistics, and sample data. Call this before writing data to understand the column structure.

curl "https://api.erdo.ai/v1/datasets/my-dataset-uuid/schema" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Dataset (SQL)

POST /v1/datasets/:slug/query

Run a SQL query against a dataset. The SQL dialect depends on the storage backend (PostgreSQL, ClickHouse, or DuckDB for file datasets). Queries are limited to 5,000 bytes and cannot embed rows using an inline VALUES clause. Store those rows in a dataset first. Column names, quoted text and comments containing VALUES remain ordinary SQL text; validation uses the storage provider’s comment and string rules.

Parameter	Type	Description
`query`	string	SQL query to execute
`resource_key`	string	Resource key from the dataset schema; selects a table in a multi-resource dataset
`limit`	number	Max rows (default 100)

curl -X POST "https://api.erdo.ai/v1/datasets/my-org.sales-data/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_key": "orders", "query": "SELECT * FROM orders WHERE revenue > 10000 ORDER BY date DESC", "limit": 50}'

{
  "columns": ["date", "revenue", "orders"],
  "rows": [["2025-03-15", "42300", "156"], ["2025-03-14", "38900", "142"]],
  "row_count": 2
}

For file datasets (CSV/Excel), the table is always named data regardless of the resource key. For database, warehouse, and synchronized API integration datasets, use the actual resource or table name from the schema — passing resource_key selects which resource to query, and that resource’s name is the SQL table name.

Query several datasets at once

POST /v1/queries

Run up to 20 SQL reads in one request, each against its own dataset. Use it when one screen needs rows from several datasets, such as a lead’s row in your leads dataset and its rows in your grades and enrichment datasets. Each read runs in parallel and exactly as POST /v1/datasets/:slug/query would run it: the same access check, default filters, filter_names, resource_key and limit. Results come back in the order you sent them. A read that fails carries its own error and the others still answer, so one missing dataset does not blank the whole screen. Scoped API keys can’t call this endpoint. They are confined to named datasets, so use POST /v1/datasets/:slug/query with them instead.

curl -X POST "https://api.erdo.ai/v1/queries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries": [
        {"dataset_slug": "my-org.leads", "query": "SELECT * FROM data WHERE canonical_lead_id = '\''…'\''", "limit": 1},
        {"dataset_slug": "my-org.lead-grades", "query": "SELECT * FROM data WHERE canonical_lead_id = '\''…'\''"}
      ]}'

{
  "results": [
    {"result": {"columns": ["canonical_lead_id", "email"], "rows": [["…", "…"]], "row_count": 1}},
    {"error": {"code": "not_found", "message": "dataset not found"}}
  ]
}

Query Dataset (Natural Language)

POST /v1/datasets/:slug/query-nl

Query a dataset using natural language. Erdo generates and executes the correct SQL for you.

Parameter	Type	Description
`question`	string	Natural language question

curl -X POST "https://api.erdo.ai/v1/datasets/my-org.sales-data/query-nl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What were the top 5 products by revenue last month?"}'

The response carries both the SQL Erdo wrote and what it returned:

{
  "sql": "SELECT product, SUM(amount) AS revenue FROM data GROUP BY 1 ORDER BY 2 DESC LIMIT 5",
  "columns": ["product", "revenue"],
  "rows": [["Widget", "48210"], ["Gizmo", "31775"]],
  "row_count": 2,
  "output": "Queried my-org.sales-data — 2 rows returned. ...",
  "success": true
}

rows holds the values in columns order — the same tabular shape /v1/datasets/:slug/fetch returns, so both dataset reads are consumed the same way — and output is that result rendered to read. row_count is how many rows the query matched and can exceed the number of rows returned, which is capped at 1000; compare the two to tell whether you have the whole result. When the dataset’s saved filters shaped the read, applied_filters names them, so a count is never reported as the whole truth when it excludes something. On failure, success is false and error says why.

Fetch Dataset Contents

POST /v1/datasets/:slug/fetch

Fetch raw contents of a dataset without writing SQL.

Parameter	Type	Description
`limit`	number	Max rows (default 1000)
`sql_query`	string	Optional SQL filter

Get Dataset Context

GET /v1/dataset-context

Get detailed context for multiple datasets at once — schemas, column types, statistics, and sample data.

Parameter	Type	Description
`dataset_slugs`	string[]	Specific dataset slugs (empty = all)
`limit`	number	Max datasets (default 10)

Writing Data

Write data into your datasets from any application. Rows are written to whatever storage backend the dataset uses (Postgres, ClickHouse, or CSV file storage).

Write Rows

POST /v1/datasets/:slug/rows

Write or upsert rows to a dataset.

Parameter	Type	Description
`rows`	object[]	Array of row objects with column names as keys
`key_column`	string	Optional. Column to upsert on (update existing, insert new)
`write_mode`	string	Optional. `replace` (default) rewrites the whole matching row; `merge` keeps the row’s existing values and fills its blanks
`overwrite_columns`	string[]	Optional, with `merge`. The columns an incoming non-blank value may overwrite

Append rows (no key column):

curl -X POST "https://api.erdo.ai/v1/datasets/my-org.metrics/rows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {"date": "2025-03-17", "revenue": 42300, "orders": 156},
      {"date": "2025-03-18", "revenue": 45100, "orders": 163}
    ]
  }'

Upsert rows (with key column):

curl -X POST "https://api.erdo.ai/v1/datasets/my-org.metrics/rows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {"date": "2025-03-17", "revenue": 43500, "orders": 160}
    ],
    "key_column": "date"
  }'

{
  "rows_affected": 2,
  "rows_inserted": 1,
  "rows_updated": 1
}

rows_inserted and rows_updated split rows_affected into the rows that created a row in the dataset and the rows that replaced one. A keyed write is an upsert, so this is the only way to tell a new record from a correction to one you already had — an arrival timestamp cannot say, because an upsert rewrites the row it matched and the timestamp moves with it. Rows also carry erdo_created_at, set when a write creates the row and left alone by every write after, for when you come back to the dataset later rather than reading the response. A keyed write in the default replace mode rewrites the whole row, so a column you leave out is blanked. To change some columns of a row and keep the rest, write in merge mode and name the columns you are changing:

curl -X POST "https://api.erdo.ai/v1/datasets/my-org.prospects/rows" \
  -H "Authorization: Bearer $ERDO_API_KEY" -H "Content-Type: application/json" \
  -d '{"key_column": "name", "write_mode": "merge", "overwrite_columns": ["outreach_status"],
       "rows": [{"name": "Alba Palm Beach", "outreach_status": "sent"}]}'

On a file dataset with a required column, a merge is checked against the row it leaves behind. An update that leaves the column out keeps its stored value and passes. A row for a new key is inserted as you sent it, so it needs every required column. A Postgres-backed dataset checks the rows you send, so there every row in a merge must carry every required column. ClickHouse-backed datasets do not support merge. Storage-specific behavior:

Storage	Append	Upsert (`key_column`)	Notes
Postgres	Insert rows	`ON CONFLICT DO UPDATE`	Key column must have a unique constraint
ClickHouse	Batch insert	Insert (use ReplacingMergeTree for dedup)
CSV/File	Append to CSV	Not supported (always appends)	New columns are added automatically

Delete Rows

DELETE /v1/datasets/:slug/rows

Delete rows from a dataset. Works for both file (CSV) and database-backed datasets.

Parameter	Type	Description
`key_column`	string	Column to match against
`keys`	string[]	Values to delete. Empty = delete all rows.

curl -X DELETE "https://api.erdo.ai/v1/datasets/my-org.metrics/rows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_column": "date", "keys": ["2025-03-17"]}'

{
  "rows_affected": 1
}

Update Schema

POST /v1/datasets/:slug/schema

Update a dataset’s schema: add, remove, rename columns, or change column types. Operations are applied atomically — if any fails, none are applied. Supported for CSV file datasets only. After changes, column analysis is automatically refreshed.

Parameter	Type	Description
`operations`	object[]	Array of schema operations

Each operation object:

Field	Type	Description
`type`	string	`add_column`, `remove_column`, `rename_column`, or `alter_column_type`
`column`	string	Target column name
`new_name`	string	New name (for `rename_column` only)
`column_type`	string	Type hint: `text`, `integer`, `float`, `date`, `boolean` (for `add_column` and `alter_column_type`)

curl -X POST "https://api.erdo.ai/v1/datasets/my-org.metrics/schema" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {"type": "add_column", "column": "region", "column_type": "text"},
      {"type": "rename_column", "column": "rev", "new_name": "revenue"},
      {"type": "alter_column_type", "column": "revenue", "column_type": "float"},
      {"type": "remove_column", "column": "temp_notes"}
    ]
  }'

{
  "columns_added": 1,
  "columns_removed": 1,
  "columns_renamed": 1,
  "columns_retyped": 1,
  "current_columns": ["date", "revenue", "region"]
}

Ask Questions

Ask a Data Question

POST /v1/ask

Ask a natural language question about your data. Invokes an AI agent that reads existing datasets and connected sources, runs analysis, and returns a text answer. A question is read-only unless allow_writes is true. The agent does not create datasets, write declarations, schedule syncs, or persist other changes. When an answer needs something that does not exist yet, it describes what it would create. A saved shortcut (saved_ask_id) runs its stored configuration, including any writes that configuration performs.

Can take 30 seconds to 2 minutes for complex questions.

Parameter	Type	Description
`question`	string	The data question
`dataset_slugs`	string[]	Optional. Scope to specific datasets.
`timezone`	string	Optional. e.g. `America/New_York`
`allow_writes`	boolean	Optional. Default false. Set true to let this question create datasets, write declarations, schedule syncs, and persist other changes.

curl -X POST "https://api.erdo.ai/v1/ask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What were total sales last quarter?", "dataset_slugs": ["my-org.sales-data"]}'

{
  "thread_id": "uuid",
  "status": "success",
  "answer": "Total sales last quarter were $1.2M, up 15% from the previous quarter..."
}

Integrations

Connect third-party apps and data sources so Erdo can use them — in agent runs, data questions, and datasets. What decides the flow is whether you already hold the credential: databases, API keys, and service accounts connect in a single call, and so do SaaS apps whose auth type is keys. OAuth apps are the exception, because the provider mints their credentials during the authorization itself — they return a connect_url for the user to authorize in a browser, and polling the status endpoint completes the connection. Connecting integrations covers both flows end to end.

List Integrations

GET /v1/integrations

Returns the integrations connected in your organization.

curl "https://api.erdo.ai/v1/integrations" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "integrations": [
    {
      "id": "uuid",
      "app": "postgres",
      "name": "Production DB",
      "status": "active",
      "auth_type": "database",
      "type": "database"
    }
  ]
}

Search Connectable Apps

GET /v1/integration-apps?query=slack

Search apps that can be connected: native integrations (databases, warehouses, APIs) and thousands of SaaS apps. The auth_types field tells you how connection works — database, api_key, service_account, basic, and aws_iam on a native integration, plus keys on a SaaS app, all connect directly with credentials, while oauth/oauth2/oauth1 apps go through a browser authorization step.

Parameter	Type	Description
`query`	string	Optional search term. Empty lists native integrations plus popular apps.

{
  "apps": [
    { "app": "slack", "name": "Slack", "auth_types": ["oauth"], "source": "pipedream" },
    { "app": "postgres", "name": "PostgreSQL", "auth_types": ["database"], "source": "native" }
  ]
}

Connect an Integration

POST /v1/integrations-connect

Parameter	Type	Description
`app`	string	App identifier from Search Connectable Apps
`name`	string	Optional display name for the connection
`credentials`	object	Credentials keyed by the field names the app declares. Works for native credential integrations and for SaaS apps whose auth type is `keys`. Passing them to an OAuth app is rejected with an error — connect without them and use the returned `connect_url`.
`scopes`	array	Optional scopes to grant; defaults to all the app supports
`return_url`	string	Optional absolute `http(s)` URL to send the user’s browser to after they authorize an OAuth app at `connect_url`. Defaults to Erdo’s data page; pass your own page when you embed the connect flow in your product so the user lands back on it. Ignored for credential-based apps that connect in one call.

Connecting a database — created, verified, and activated in one call:

curl -X POST "https://api.erdo.ai/v1/integrations-connect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "postgres",
    "credentials": {
      "host": "db.example.com", "port": "5432",
      "database": "analytics", "username": "readonly", "password": "..."
    }
  }'

{ "app": "postgres", "integration_id": "uuid", "status": "active" }

Connecting an OAuth app — the response carries a connect_url to open in a browser. Pass return_url when you embed the flow in your own product so the user’s browser lands back on your page (not Erdo’s) after authorizing:

curl -X POST "https://api.erdo.ai/v1/integrations-connect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app": "slack", "return_url": "https://portal.example.com/integrations/done"}'

{
  "app": "slack",
  "status": "pending",
  "connect_url": "https://...",
  "next_step": "Have the user open connect_url in a browser and authorize slack, then check the connection status for app=\"slack\" to confirm."
}

If verification fails for a native credential integration (wrong password, unreachable host), the call returns an error and nothing is left behind — fix the credentials and retry. A SaaS keys app connects the same way but is not verified: its credentials go to the connector platform, which stores what it is given without calling the vendor. The response says so in next_step, and the first action run is what confirms the key.

Check Connection Status

GET /v1/integrations-connect/:app

Reports whether an app is connected. For browser-authorized apps this also completes any connection the user finished since the connect call — poll it after the user opens the connect_url. An app you have never connected answers {"app": "...", "connected": false, "integrations": []}. That is an ordinary answer about your account, not an error, so a caller starting from zero can poll it safely; a genuine provider failure still comes back as an error.

curl "https://api.erdo.ai/v1/integrations-connect/slack" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "app": "slack",
  "connected": true,
  "integrations": [
    { "id": "uuid", "app": "slack", "name": "Slack (team@acme.com)", "status": "connected" }
  ],
  "note": "1 new connection(s) confirmed."
}

Delete an Integration

DELETE /v1/integrations/:id

Removes a connected integration by its id (from List Integrations). The credential is deleted and any datasets built on the integration are cleaned up — the same behaviour as removing the connection in the Erdo web app. This is how you correct a connection made in the wrong organization without a trip to the UI. An id that does not exist in your organization — including one already deleted — answers 404 Not Found.

curl -X DELETE "https://api.erdo.ai/v1/integrations/INTEGRATION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "id": "uuid", "app": "reddit_ads", "name": "Reddit Ads Integration", "deleted": true }

Discover Tables

GET /v1/integrations/:integration/tables

Discover what a connected database integration exposes. :integration is the app key (e.g. postgres) or, when several instances of the same app are connected, the integration id. Without schema_name it lists the selectable schemas (all SQL databases and warehouses). With schema_name it lists that schema’s tables with columns, types, and row estimates — supported for SQL databases (Postgres, MySQL, and compatible); warehouses (BigQuery, Snowflake, ClickHouse) list schemas but not per-table columns here.

Parameter	Type	Description
`schema_name`	string	Optional. Schema to list tables for.

curl "https://api.erdo.ai/v1/integrations/postgres/tables?schema_name=public" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "integration_id": "uuid",
  "app": "postgres",
  "schemas": [{ "id": "public", "name": "public", "type": "schema" }],
  "tables": [
    {
      "schema_name": "public",
      "table_name": "orders",
      "columns": [{ "name": "id", "data_type": "uuid", "is_nullable": false, "is_primary_key": true }],
      "estimated_row_count": 12840
    }
  ]
}

Create a Dataset from an Integration

POST /v1/integration-datasets

Create a dataset backed by any connected integration that exposes queryable data. Database and warehouse integrations can query live against the source; sync-capable API integrations automatically materialize their provider resources through Erdo’s data platform. Pick selectable scopes with Discover Tables first when the integration exposes them (some allow only one). Integrations with neither a direct query path nor dataset sync are rejected. Resource and column discovery runs in the background and the dataset schema appears after the first discovery/sync, after which Query Dataset works against the returned slug.

Parameter	Type	Description
`integration`	string	App key (e.g. `postgres`) or integration id
`name`	string	Display name for the dataset
`description`	string	Optional description shown to AI agents
`schemas`	string[]	Selectable schema names (or ids) to include, from Discover Tables

curl -X POST "https://api.erdo.ai/v1/integration-datasets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integration": "postgres", "name": "Production DB", "schemas": ["public"]}'

{
  "dataset_id": "uuid",
  "slug": "my-org.production-db",
  "name": "Production DB",
  "status": "active"
}

Threads & Conversations

List Threads

GET /v1/threads

Parameter	Type	Description
`limit`	number	Max results (default 20)
`offset`	number	Pagination offset

Get Thread Messages

GET /v1/threads/:id/messages

Get all messages from a conversation thread. User-authored messages include the author’s canonical ID, name, and email when that user is still in the organization. Each content item includes its persisted content_type and, when present, ui_content_type. Use ui_content_type to select the presentation component for structured content such as tool results and generated UI. UI-generation items also include created_by_invocation_id when the renderer needs the originating invocation to load referenced data.

Create Thread

POST /v1/threads-create

Parameter	Type	Description
`name`	string	Optional thread name
`dataset_ids`	string[]	Optional dataset UUIDs to attach
`visibility`	string	Optional. `visible` (default) lists the thread for everyone in the organization. `hidden` keeps it out of the organization’s thread list.

Delete Thread

DELETE /v1/threads/:id

Permanently delete a thread and its messages. This cannot be undone. The caller needs admin on the thread: its creator or an organization admin. A scoped key needs the agents:run capability.

Send Message

POST /v1/threads/:id/send

Send a message to a thread and get an AI-generated response. The optional context is available to the agent for this turn without becoming part of the visible user message in the thread. This lets an application supply the current page, selection, or other structured state while preserving an honest transcript. The persisted message is attributed to the authenticated user, including when the request comes through an application using the REST or MCP surface.

Can take 30 seconds to 2 minutes.

Parameter	Type	Description
`message`	string	The message
`context`	string	Optional application context for this turn. It is not stored as the visible user message.
`agent_key`	string	Optional. Default: `erdo.data-question-answerer`
`timezone`	string	Optional timezone
`async`	boolean	Optional. Start the run and return immediately.

Memories & Skills

Memories store reusable knowledge and instructions that Erdo’s AI uses in future conversations.

Create Memory

POST /v1/memories

Parameter	Type	Description
`title`	string	Short title
`content`	string	The content or instructions
`description`	string	Brief description
`type`	string	`snippet` (knowledge) or `skill` (instructions)
`category`	string	Optional category
`tags`	string[]	Optional tags
`dataset_ids`	string[]	Optional associated dataset UUIDs

Search Memories

GET /v1/memories-search

Parameter	Type	Description
`query`	string	Search text
`limit`	number	Max results (default 10)

List Memories

GET /v1/memories

Parameter	Type	Description
`type`	string	Optional filter: `snippet` or `skill`
`category`	string	Optional category filter
`limit`	number	Max results (default 20)
`offset`	number	Pagination offset

Delete Memory

DELETE /v1/memories/:id

Soft delete — can be recovered.

Artifacts

Artifacts are AI-generated outputs from agent runs — insights, metrics, alerts, and tables.

List Artifacts

GET /v1/artifacts

Parameter	Type	Description
`type`	string	Optional: `insight`, `chart`, `metric`, `alert`, `table`, `suggestion`
`limit`	number	Max results (default 20)
`offset`	number	Pagination offset

Get Artifact

GET /v1/artifacts/:id

Screenshots

Capture a public web page to a PNG and get a signed, time-limited download URL. Only works on URLs reachable without login (a marketing site, a published Erdo page at https://pages.erdo.ai/p/{id}, etc.).

POST /v1/screenshot

curl -X POST "https://api.erdo.ai/v1/screenshot" \
  -H "Authorization: Bearer $ERDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://pages.erdo.ai/p/abc123", "full_page": true}'

Response: signed_url, bucket_key, media_type, width, height, expires_at.

Pages

Deploy authenticated, data-wired HTML apps to Erdo over HTTP — the same surface as the erdo_deploy_page MCP tools, for CI and scripts. See the Build Apps on Erdo guide for the page runtime, the window.erdo client, and the read/write model.

Deploy Page

POST /v1/pages

Parameter	Type	Description
`title`	string	Page title shown in Erdo
`html`	string	Full document or fragment. With the `react-tailwind` runtime, include a root element and put React code in `js`
`css`	string	Optional. Stylesheet
`js`	string	Optional. JavaScript/JSX; `window.erdo` is available
`runtime`	string	Optional. `react-tailwind` (default) or `none`
`dataset_slugs`	string[]	Optional. Datasets the page reads — granted read access (you must be able to view them); unknown slugs are a hard error
`public`	boolean	Optional. `true` makes the page publicly viewable (view-only). Default `false`

Returns the page id, editor url, optional public_url, and structured validation results. A deploy with validation errors still saves — fix them and iterate.

curl -X POST "https://api.erdo.ai/v1/pages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales Dashboard",
    "html": "<div id=\"root\"></div>",
    "js": "const {rows} = await erdo.queryDataset(\"acme.sales\", {limit: 1000}); /* render */",
    "dataset_slugs": ["acme.sales"],
    "public": false
  }'

Update Page

PUT /v1/pages/:pageID

Provided fields are merged — send only js to fix a script without resending html/css. Omit any field to keep its current value. build_brief updates only the page judges’ stored brief; an empty string clears it without changing the page content or other judge metadata. artifact_kind (landing_page, lead_followup_page, dashboard or app) re-declares what the page is for, in the same write as the content; omit it to keep the current purpose. Meta and LinkedIn tags load only on lead-generation landing pages, so set it whenever a rewrite changes the page’s job. dataset_slugs replaces the current grants; public toggles visibility. Returns fresh validation results.

Validate Page

POST /v1/pages/validate

Dry-run validation without deploying: HTML structure, JS/JSX syntax and runtime smoke checks, window.erdo usage, and dataset-slug references. Accepts html (required), css, js, runtime, and dataset_slugs.

Clone Page

POST /v1/pages

Copying a page is the deploy endpoint’s clone mode: pass clone_from_page_id instead of content. The content is copied byte for byte, and the lead-form event pipelines the source page owns are duplicated onto the copy with the pipeline ids in its content rewritten to match — so the copy captures its own leads instead of filing them against the page it was copied from. The copy is private unless the request sets public: true; the source’s publish state is never inherited. Leave html/css/js/runtime and the grant lists empty — the copy carries the source’s.

Parameter	Type	Description
`clone_from_page_id`	string	Page to copy.
`title`	string	Optional. Title for the copy. Default: `Copy of <source title>`
`public`	boolean	Optional. Publish the copy immediately (default false).

Returns the usual deploy response plus source_page_id, cloned_pipelines (one entry per duplicated pipeline: source_id, id, purpose, slug), rewrites (every id substitution applied to the copied content), and notes.

curl -X POST "https://api.erdo.ai/v1/pages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clone_from_page_id": "PAGE_ID", "title": "Sales Dashboard — EMEA"}'

Automations (Heartbeats)

Heartbeats are recurring agents that analyze your data on a schedule.

List Heartbeats

GET /v1/heartbeats

Parameter	Type	Description
`limit`	number	Max results (default 20)
`offset`	number	Pagination offset

Create Heartbeat

POST /v1/heartbeats

Parameter	Type	Description
`name`	string	Name
`instructions`	string	What to do on each run
`interval_minutes`	number	Run frequency (min 5)
`description`	string	Optional description
`timezone`	string	Optional (default UTC)
`active_window_start`	string	Optional. e.g. `09:00`
`active_window_end`	string	Optional. e.g. `18:00`
`active_days`	number[]	Optional. 0=Sun..6=Sat
`run_at`	string	Optional RFC3339 instant: run once at or after it, then stop permanently
`ends_at`	string	Optional RFC3339 instant: never run after it
`dataset_ids`	string[]	Optional dataset UUIDs
`effort`	string	Optional: `low`, `medium`, `high`

curl -X POST "https://api.erdo.ai/v1/heartbeats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue monitor",
    "instructions": "Check daily revenue for anomalies and alert if down >10% vs last week",
    "interval_minutes": 60,
    "dataset_ids": ["dataset-uuid"],
    "active_window_start": "09:00",
    "active_window_end": "18:00",
    "timezone": "America/New_York"
  }'

Run Heartbeat

POST /v1/heartbeats/:id/run

Trigger a heartbeat immediately, outside its schedule.

Enable or Disable Heartbeat

POST /v1/heartbeats/:id/state

Pause a misbehaving automation so it stops running, or resume a paused one.

Parameter	Type	Description
`state`	string	`active` or `disabled`

curl -X POST "https://api.erdo.ai/v1/heartbeats/HEARTBEAT_ID/state" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "disabled"}'

List Heartbeat Executions

GET /v1/heartbeats/:id/executions

Parameter	Type	Description
`limit`	number	Max results (default 10)

Rendering

Render Chart

POST /v1/render/chart

Render a data visualization. Supports bar, line, pie, histogram, and scatter charts. See MCP docs for full schema.

Render Table

POST /v1/render/table

Render a data table. See MCP docs for full schema.

​REST API

​Getting an API Key

​Project context

​Scoped API Keys

​Scoped Tokens

​API Surface

​Errors

​Datasets

​List Datasets

​Configure an Integration Dataset

​Create Dataset

​List Dataset Purposes

​Ensure a Purpose Dataset

​Upload a File as a Dataset

​Delete Dataset

​Search Datasets

​Get Dataset Schema

​Query Dataset (SQL)

​Query several datasets at once

​Query Dataset (Natural Language)

​Fetch Dataset Contents

​Get Dataset Context

​Writing Data

​Write Rows

​Delete Rows

​Update Schema

​Ask Questions

​Ask a Data Question

​Integrations

​List Integrations

​Search Connectable Apps

​Connect an Integration

​Check Connection Status

​Delete an Integration

​Discover Tables

​Create a Dataset from an Integration

​Threads & Conversations

​List Threads

​Get Thread Messages

​Create Thread

​Delete Thread

​Send Message

​Memories & Skills

​Create Memory

​Search Memories

​List Memories

​Delete Memory

​Artifacts

​List Artifacts

​Get Artifact

​Screenshots

​Pages

​Deploy Page

​Update Page

​Validate Page

​Clone Page

​Automations (Heartbeats)

​List Heartbeats

​Create Heartbeat

​Run Heartbeat

​Enable or Disable Heartbeat

​List Heartbeat Executions

​Rendering

​Render Chart

​Render Table

REST API

Getting an API Key

Project context

Scoped API Keys

Scoped Tokens

API Surface

Errors

Datasets

List Datasets

Configure an Integration Dataset

Create Dataset

List Dataset Purposes

Ensure a Purpose Dataset

Upload a File as a Dataset

Delete Dataset

Search Datasets

Get Dataset Schema

Query Dataset (SQL)

Query several datasets at once

Query Dataset (Natural Language)

Fetch Dataset Contents

Get Dataset Context

Writing Data

Write Rows

Delete Rows

Update Schema

Ask Questions

Ask a Data Question

Integrations

List Integrations

Search Connectable Apps

Connect an Integration

Check Connection Status

Delete an Integration

Discover Tables

Create a Dataset from an Integration

Threads & Conversations

List Threads

Get Thread Messages

Create Thread

Delete Thread

Send Message

Memories & Skills

Create Memory

Search Memories

List Memories

Delete Memory

Artifacts

List Artifacts

Get Artifact

Screenshots

Pages

Deploy Page

Update Page

Validate Page

Clone Page

Automations (Heartbeats)

List Heartbeats

Create Heartbeat

Run Heartbeat

Enable or Disable Heartbeat

List Heartbeat Executions

Rendering

Render Chart

Render Table