REST API reference¶

This reference is for client developers and integrators. After reading it, you can find the local API base URL, response format, auth headers, resource endpoints, session endpoints, and artifact endpoints.

Default service address:

http://127.0.0.1:8787

General conventions¶

Most JSON endpoints return an envelope:

{
  "success": true,
  "data": {}
}

Error responses:

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "resource not found"
  }
}

File downloads and artifact downloads return binary responses; upload endpoints use multipart/form-data.

Identity and auth¶

Local development supports these headers:

Authorization: Bearer <dev_token>
X-Dev-Token: <dev_token>
X-Workspace-Id: default

When headers are omitted, the backend uses the development default identity and default workspace. Web v1 does not expose workspace switching; use default unless you are building an integration that owns workspace routing.

For local user isolation, send the same identity headers to both /api/v1/* REST calls and POST /api/copilotkit. If the two channels use different headers, sessions, resources, files, artifacts, and run events can appear under different users.

Password mode uses session cookies and CSRF:

DATAFOUNDRY_AUTH_MODE=password
X-CSRF-Token: <token_from_df_csrf_cookie>

Use DATAFOUNDRY_AUTH_MODE=dev for local dev-token auth. In production, password mode is the default unless overridden.

Identity endpoints¶

Method	Path	Purpose
GET	`/api/v1/me`	Read the current user and workspace.
GET	`/api/v1/dev/identities`	List local development users. Disabled in production by default.
POST	`/api/v1/dev/users`	Create or update a local development user. Disabled in production by default.

Password auth endpoints¶

These endpoints are enabled when password auth mode is active:

Method	Path	Purpose
POST	`/api/v1/auth/register`	Create a user account and verification token.
POST	`/api/v1/auth/login`	Sign in and set `df_session` and `df_csrf` cookies.
POST	`/api/v1/auth/verify-email`	Verify an email token.
POST	`/api/v1/auth/password/forgot`	Request a password reset.
POST	`/api/v1/auth/password/reset`	Reset a password with a token.
GET	`/api/v1/auth/csrf`	Read the current CSRF token.
POST	`/api/v1/auth/logout`	Sign out the current session.
POST	`/api/v1/auth/logout-all`	Revoke all sessions for the current user.
GET	`/api/v1/auth/sessions`	List active sessions for the current user.
DELETE	`/api/v1/auth/sessions/:id`	Revoke one session.
POST	`/api/v1/auth/password/change`	Change the current user's password.

Health and capabilities¶

Method	Path	Purpose
GET	`/healthz`	Check whether the backend is running.
GET	`/api/v1/capabilities`	Read backend capability switches.
GET	`/api/v1/me`	Read current identity.

curl http://127.0.0.1:8787/healthz
curl http://127.0.0.1:8787/api/v1/capabilities

Agent Runtime¶

Method	Path	Purpose
POST	`/api/copilotkit`	Start an agent run; returns AG-UI event stream.
POST	`/api/v1/runs/:id/cancel`	Cancel a running agent run.

POST /api/copilotkit uses CopilotKit / AG-UI RunAgentInput. See Agent Runtime and AG-UI reference.

Sessions¶

Method	Path	Purpose
GET	`/api/v1/sessions`	List server sessions. Supports `limit`, `cursor`.
PATCH	`/api/v1/sessions/:sessionId`	Update session title.
GET	`/api/v1/sessions/:sessionId/conversation`	Read authoritative server conversation history. Supports `limit`.
POST	`/api/v1/sessions/:sessionId/branches`	Create a persistent branch from an ended run. Body: `{ "runId": "..." }`.

Session APIs restore history for Web/TUI, display titles, read tool-call pairings, and support re-asking from checkpoints. The conversation response includes messages, runEventRefs, toolCalls, and may include checkpoints, branch, and branches. Each checkpoint is derived from existing run, message, and run-event records and includes runId, status, message position bounds, event seq bounds, start/finish times, and optional error text; it marks the recoverable history boundary for one run. Branch sessions reference parent history up to the fork checkpoint instead of copying messages, so reading a branch returns the visible parent prefix plus the branch's own messages.

Workspace configuration¶

Method	Path	Purpose
GET	`/api/v1/workspace-config`	Read workspace resource defaults.
PATCH	`/api/v1/workspace-config`	Update default enablement.
GET	`/api/v1/run-defaults`	Read run default configuration.

Data sources¶

Method	Path	Purpose
GET	`/api/v1/datasource-types`	Discover supported data source types and field schema.
GET	`/api/v1/datasources`	List data sources.
POST	`/api/v1/datasources`	Create a data source.
GET	`/api/v1/datasources/:id`	Read data source details.
PATCH	`/api/v1/datasources/:id`	Update a data source.
DELETE	`/api/v1/datasources/:id`	Delete a data source.
POST	`/api/v1/datasources/:id/test`	Test connection.
POST	`/api/v1/datasources/:id/introspect`	Fetch schema; returns a job.
GET	`/api/v1/datasources/:id/schema`	Read schema snapshot. Supports `q`, `includeStats`.
GET	`/api/v1/datasources/:id/tables/:table/preview`	Preview table data. Supports `schema`, `limit`, `offset`, `orderBy`.

The backend does not expose arbitrary SQL REST endpoints. SQL analysis runs through agent tools.

Models¶

Method	Path	Purpose
GET	`/api/v1/model-profiles`	List model profiles.
POST	`/api/v1/model-profiles`	Create a model profile.
GET	`/api/v1/model-profiles/:id`	Read a model profile.
PATCH	`/api/v1/model-profiles/:id`	Update a model profile.
DELETE	`/api/v1/model-profiles/:id`	Delete a model profile.
POST	`/api/v1/model-profiles/:id/test`	Test provider.

Knowledge bases¶

Method	Path	Purpose
GET	`/api/v1/knowledge-bases`	List knowledge bases.
POST	`/api/v1/knowledge-bases`	Create a knowledge base.
GET	`/api/v1/knowledge-bases/:id`	Read a knowledge base.
PATCH	`/api/v1/knowledge-bases/:id`	Update a knowledge base.
DELETE	`/api/v1/knowledge-bases/:id`	Delete a knowledge base.
POST	`/api/v1/knowledge-bases/:id/test`	Validate configuration.
POST	`/api/v1/knowledge-bases/:id/files`	Upload documents.
POST	`/api/v1/knowledge-bases/:id/files/import`	Import from FileAssetRef.
POST	`/api/v1/knowledge-bases/:id/search`	Retrieval debug.
POST	`/api/v1/knowledge-bases/:id/reindex`	Rebuild index; returns a job.

MCP and Skills¶

Method	Path	Purpose
GET / POST	`/api/v1/mcp-servers`	List or create MCP servers.
GET / PATCH / DELETE	`/api/v1/mcp-servers/:id`	Read, update, or delete MCP servers.
POST	`/api/v1/mcp-servers/:id/test`	Test MCP server.
GET	`/api/v1/mcp-servers/:id/tools`	Fetch tools manifest.
GET / POST	`/api/v1/skills`	List or upload Skills.
POST	`/api/v1/skills/select`	Preview Skill filtering for a run.
GET / PATCH / DELETE	`/api/v1/skills/:id`	Read, update, or delete Skills.
POST	`/api/v1/skills/:id/test`	Test Skill.
POST	`/api/v1/skills/:id/validate`	Validate Skill.
POST	`/api/v1/skills/:id/replace`	Replace Skill package.

Files¶

Method	Path	Purpose
GET	`/api/v1/files`	List file assets. Supports `scope`, `origin`, `source`, `sessionId`.
POST	`/api/v1/files`	Batch upload files. Session id required in multipart field or header.
GET	`/api/v1/files/:id`	Read file reference.
POST	`/api/v1/files/:id/promote`	Promote session-scoped file to cross-session workspace file.
DELETE	`/api/v1/files/:id`	Delete file reference.
GET	`/api/v1/files/:id/download`	Download file content.
POST	`/api/v1/chat/uploads`	Upload chat attachments for the current conversation.

Artifacts¶

Method	Path	Purpose
GET	`/api/v1/artifacts?sessionId=:sessionId`	List outputs for a session.
GET	`/api/v1/artifacts/:id`	Read artifact details.
GET	`/api/v1/artifacts/:id/preview`	Read preview JSON.
GET	`/api/v1/artifacts/:id/content`	Read inline content.
GET	`/api/v1/artifacts/:id/download`	Download artifact. Optional `format`.
POST	`/api/v1/artifacts/:id/promote`	Add file artifact to workspace files.
POST	`/api/v1/artifacts/:id/export`	Export specified format; returns a job.

Query history¶

Method	Path	Purpose
GET	`/api/v1/query-history`	List SQL query history. Supports `sessionId`, `datasourceId`, `favorite`, `limit`.
POST	`/api/v1/query-history/:id/favorite`	Favorite a query.
POST	`/api/v1/query-history/:id/unfavorite`	Remove favorite.
PATCH	`/api/v1/query-history/:id`	Update favorite with `{ "favorite": true \\| false }`.

Jobs¶

Method	Path	Purpose
GET	`/api/v1/jobs/:id`	Query async job status.
POST	`/api/v1/jobs/:id/cancel`	Cancel async job.

Write conventions¶

Default JSON body limit is 1 MiB.
PATCH supports optimistic concurrency with revision or If-Match.
Schema fetch, index rebuild, and artifact export may use Idempotency-Key.
Credentials are submitted only when creating or updating resources.
Read APIs do not return plaintext passwords, tokens, or full connection strings.