datamcp Integration API v1

The Integration API lets automation tools read and change rows in a datamcp database source. It supports direct PostgreSQL and MySQL sources, and PostgreSQL sources connected through Local Agent Tunnel. It does not expose database passwords to the automation tool. Queries and results still pass through datamcp and the automation provider.

Base URL: https://api.datamcp.app/api

Authentication and scope

Create an Integration credential in datamcp → API Keys. Select the database source and only the operations the automation needs. For writes, select allowed tables. The secret begins with dm_int_ and is shown only when created; send it in the Authorization: Bearer <integration-key> header. Do not use a workspace API key or a database password.

The key's issuer must remain an organization owner or admin. A key is also limited by source membership, operation scope, table scope for writes, the active datamcp subscription or trial, source availability, and database grants. Revocation takes effect on the next request. A read-query grant permits reading the selected source, not just the table chosen for writes. Issue separate read and write keys when that distinction matters.

All responses use JSON. Successful responses have success: true and data; failures have success: false and an error object. Set Content-Type: application/json on requests with a body. Avoid logging credentials or full database results.

List accessible sources

GET /integrations/v1/sources

Returns the active sources selected for the key. Each source includes its id, name, source type, database type, routing type, and operations allowed by the key. It does not include the database connection string.

{
  "success": true,
  "data": [
    {
      "id": "conn_example",
      "name": "Orders",
      "type": "database",
      "databaseType": "postgresql",
      "routingType": "tunnel",
      "operations": ["read_query"]
    }
  ]
}

Use the returned id as sourceId below. The source selector in the Zapier app filters this list by the operation being configured.

Read rows

POST /integrations/v1/sources/{sourceId}/query

Requires read_query. Supply a read-only SQL statement, optionally with bound parameters. Use $1, $2, etc. for PostgreSQL and ? placeholders for MySQL rather than inserting workflow values into SQL text. maxRows defaults to 100 and must be between 1 and 100. Up to 50 scalar parameters are accepted; each may be a string of at most 4096 characters, a finite number, a boolean, or null. Query text is limited to 20,000 characters. Execution times out after 30 seconds; a 512 KiB result cap also applies.

{
  "query": "SELECT id, status FROM public.orders WHERE id = $1",
  "parameters": [123],
  "maxRows": 10
}

{
  "success": true,
  "data": {
    "columns": ["id", "status"],
    "rows": [[123, "new"]],
    "rowCount": 1,
    "truncated": false
  }
}

The query is checked by datamcp's SQL policy and database permissions and runs in a read-only transaction. The Zapier app converts each row array to an object using columns; give duplicate SQL columns distinct aliases. A returned page is bounded, not an implicit request for every row in a large table. Use an explicit stable ordering and keyset predicate when paginating a large table.

Change one row

All row operations use /integrations/v1/sources/{sourceId}/rows, a schema-qualified table such as public.orders, and a key that grants the matching operation and allows that table. The source schema must have been synced. The underlying database role must also have the necessary grants. For update and delete, provide the complete primary key in key. Values are bound as parameters, not interpolated into SQL.

HTTP method	Required operation	Body
`POST`	`create_row`	`{"table":"public.orders","values":{"label":"demo"}}`
`PATCH`	`update_row`	`{"table":"public.orders","key":{"id":123},"values":{"status":"done"}}`
`DELETE`	`delete_row`	`{"table":"public.orders","key":{"id":123}}`

A successful response is {"success":true,"data":{"affectedRows":1}}; affectedRows: 0 means no row matched. Updates and deletes are limited to one row. The production backend must have integration writes enabled. A Local Agent source must additionally run in read-write mode; a read-only agent cannot be overridden by the key.

Do not blindly retry a write after a timeout or uncertain response. The database might have committed it even though the response was lost. Check the row first. There is no public idempotency-key contract for these operations.

Common errors

HTTP status	Meaning
`400`	Invalid SQL, parameters, table name, row values, or primary key.
`401`	Missing, malformed, revoked, or expired Integration credential.
`402`	No active subscription or trial for the organization.
`403`	Source, operation, or table outside the key's scope; insufficient database permissions; or writes disabled.
`409`	Write outcome is unknown. Inspect the row before retrying.
`412`	Source schema needs to be synced before a write.
`429`	Query rate limit exceeded.
`503`	Database or Local Agent unavailable. A write may need verification before retrying.

The error envelope may include a request ID for support. Do not include a key, password, full connection URL, or sensitive query result in a support message.

Credential management

The following endpoints are for an authenticated datamcp dashboard owner or admin, not for an Integration key:

POST /integration-credentials creates a key from name, organizationId, sourceIds (1–10), operations (1–4), and optional tableScopes mapping source IDs to allowed schema-qualified tables. The one-time secret appears only in this response.
GET /integration-credentials?organizationId={uuid} lists key metadata, including scopes, creation and last-use times, expiry, and revocation state, but never the secret or hash.
DELETE /integration-credentials/{credentialId}?organizationId={uuid} revokes an active key.

The available database operations are read_query, create_row, update_row, and delete_row. Agent Memory and OpenAPI operations are not exposed through Integration API v1.