Knowledge Connectors

Endpoints under /api/v1/knowledge-connectors. Every response uses the api-contracts.v1 envelope: success is { ok: true, data, meta: { contractVersion: "api-contracts.v1" } }; failure is { ok: false, error: { code, message } }.

There is no durable Knowledge Sync dispatcher. POST .../runs queues the run and executes it in the same request. A defer body field is rejected. See Knowledge Connectors for credentials, filters, leases, and degradation.

Endpoints

POST, PATCH, and DELETE require header Idempotency-Key. Missing or invalid key: 400 idempotency_key_invalid.

List connectors

GET /api/v1/knowledge-connectors

data:

The process default registry certifies drive, confluence, slack, and github. Those four advertise capabilities: ["knowledge.sync"] and certified: true. An uncertified provider can still appear on a stored connector, but capabilities is empty and a run cannot be queued.

Allowlisted providerId values only: drive, confluence, slack, github.

Create a connector

POST /api/v1/knowledge-connectors — 201 { connector }.

Provider-specific filters (fileIds, spaceIds, channelIds, repositories) are validated at fetch time, not at create. Duplicate name: 409 conflict. Missing knowledge base: 404.

Get, update, delete

GET /api/v1/knowledge-connectors/{id} — { connector }.

PATCH /api/v1/knowledge-connectors/{id} — { connector }.

DELETE /api/v1/knowledge-connectors/{id} — { deleted: true, connectorId }. Removes the connector. Sync runs cascade-delete. On the Prisma store, documents keep their rows and connectorId is set to null (onDelete: SetNull). The in-memory store also deletes those documents.

Connector object

Lease fields (syncLeaseRunId, syncLeaseToken, syncLeaseExpiresAt) are not serialized.

List and get runs

GET /api/v1/knowledge-connectors/{id}/runs — { runs, nextCursor }. Same cursor / limit rules as connector list. Unknown connector: 404.

GET /api/v1/knowledge-connectors/{id}/runs/{runId} — { run }.

Queue and execute a run

POST /api/v1/knowledge-connectors/{id}/runs — 201 { run } when execute completes.

Body must be an object whose only allowed key is options. records, cursor, defer, or any other key: 400 validation_failed (Only bounded sync options are accepted.).

{ "options": { "maxPages": 4, "maxItems": 200 } }

Unsupported option keys, non-numbers, or out-of-range values: 400.

The same request calls queueRun then executeRun. A successful HTTP response means the batch was applied. If execute fails, the handler returns an error envelope (not 201 with a failed run). The persisted run is still failed (or remains queued if start never claimed the lease). Inspect it with GET .../runs/{runId}.

Uncertified provider: 409 conflict (Provider {id} has not passed certification.). Missing or incompatible credential: 409 setup_required (retryable: false, details.availability from the capability error). Concurrent execute on the same connector: 409 conflict (Knowledge sync run is not queued.). The second run stays queued for a later retry.

Replay the same Idempotency-Key with the same options to retry a failed or cancelled run (retryTerminal) or to return a succeeded run without a second apply. Same key, different options: 409. Stable run id: ksr_ plus the first 40 hex characters of sha256(workspaceId + NUL + connectorId + NUL + key).

Agents use the preview capability knowledge.sync with the same queue-then-execute path. Required input: connectorId. Optional: maxPages, maxItems, maxBytes, timeoutMs. Confirmation and idempotency are required.

Cancel a run

POST /api/v1/knowledge-connectors/{id}/runs/{runId}/cancel — { run } with status: "cancelled".

Cancels queued or running. A second cancel, or cancel of succeeded / failed / cancelled: 409 (Cannot cancel a {status} knowledge sync run.). A cancelled run cannot be started (409 Knowledge sync run is not queued.).

Run object

requestFingerprint, leaseToken, and leaseExpiresAt are not serialized.

Error map

Next steps