API Reference

The Confluye REST API is served under /api/v1. Use it to manage workflows, trigger runs, work with data, and administer the platform programmatically. Every request is scoped to a single workspace — the one that owns the API key you authenticate with.

Create keys in the app (API Keys); Admin or Owner session required.

Base URL

All endpoints are relative to your Confluye deployment origin, under the /api/v1 prefix:

https://confluye.run/api/v1

Absolute URLs returned in responses (for example a webhook invoke URL) are built from the request origin, so they match the host you called.

Authentication

Send a workspace API token in the Authorization header. Only Bearer is accepted. Tokens must start with hise_.

curl https://confluye.run/api/v1/workflows \
  -H "Authorization: Bearer hise_xxxxxxxxxxxxxxxxxxxxxxxx"

Missing, non-bearer, non-hise_, unknown, or revoked tokens return 401:

{ "error": "Valid bearer API key is required" }

The same 401 is returned if the key's user is banned or no longer has workspace and organization membership. A verified call updates lastUsedAt.

Key scopes

Keys carry workspace, personal, or copilot (normalizeApiKeyScope; anything else becomes workspace).

These routes require scope === "workspace" and otherwise return 403 { "error": "A workspace API key is required." }:

• POST /workflows/{id}/execute
• Credential list/create/update/delete (credential test accepts any valid key)
• GET/POST /workspace-members
• Mailer, RSS triggers, Google domain-wide delegation
• Files, research, presentations, knowledge connectors
• Usage and Confluye Command jobs
• POST /skills/load and POST /chat (other Skills CRUD and Chat read/update/delete operations accept any valid key for the key's workspace)
• Platform MCP (workspace key)

Preferences (GET/PATCH /settings/preferences) and many workflow/document/database reads accept any valid key for that workspace.

GET /workspaces returns { workspace } for the key's workspace (404 if missing).

Workspace boundary

Requests never switch workspace. Accessing a resource whose workspaceId is not the key's workspace returns 403 ("API key cannot access this workflow|schedule|webhook") or 404, depending on the route.

Conventions

Format. Requests and responses are JSON, except POST /documents and POST /databases/import, which accept multipart/form-data, plus PUT /files/{id}/content and GET /files/{id}/content, which write and return raw bytes.

Errors. Most endpoints return { "error": "<message>" } with an appropriate HTTP status.

Some routes add a machine-readable code and contextual fields (for example /databases/query returns code and availableTables; /workflows/{id}/deploy returns code and review).

Pagination. Pagination is endpoint-specific. Files, research runs, knowledge connectors, and knowledge-connector runs use cursor / limit and return nextCursor. The /runs list takes a limit query param (default 100, clamped 1–200). /databases/{tableId}/rows takes limit and offset and returns pagination: { limit, offset, returned, total }. Endpoint pages document their exact defaults and maximums; lists without pagination return the full array.

Idempotency. Endpoints that create runs accept an optional Idempotency-Key header (POST /workflows/{id}/execute, /runs/{id}/cancel, /runs/{id}/rerun, /schedules/{id}/run). Replaying the same key with the same body returns the stored response with Idempotency-Replayed: true; the same key with a different body returns 409. Keys are valid for 24 hours.

Rate limits. /api/v1 has no global API-key rate limiter. Auth sign-in and MCP OAuth do.

Members (v1)

POST /api/v1/workspace-members body: { email, role }. role must be admin, member, or viewer — not owner. Requires a workspace key and Admin/Owner. See Organizations and workspaces.

Endpoint domains