REST API Reference

POST/api/answer

Provide a response based on the question and retriever.

Token scope: chat:run

JSON body (AnswerModel):

POST/api/search

Search for relevant documents based on query.

Token scope: chat:run

JSON body (SearchModel):

POST/stream

Stream a response based on the question and retriever.

Token scope: chat:run

JSON body (StreamModel):

GET/api/activity/history

Return one page of the caller's finished runs.

The caller's finished runs of every kind, newest first: scheduled, webhook and workflow runs, background jobs, and monitor wakes, with one status vocabulary. Returns: A Flask response with ``runs`` and ``has_more``, or 400 for an unknown ``kind`` or ``status``.

Not available to personal access tokens

GET/api/activity/now

Return the caller's Now snapshot.

What runs for the caller now (chat answers, background jobs, scheduled, webhook and workflow runs, ingests), what waits for them (tool approvals, schedules paused after failures), what runs in the next 24 hours, and the 24-hour counts. Returns: A Flask response with ``running``, ``needs_you``, ``up_next``, ``approval_conversations``, ``failed_conversations`` and ``stats``.

Not available to personal access tokens

GET/api/activity/planned

Return the caller's calendar window.

The caller's calendar for a window: planned schedule runs (from cron or run_at), past and in-flight runs with their status, coming knowledge syncs (one event per frequency each time it fires, kind sync), and monitors as date ranges. The window may span at most 62 days. A frequent schedule with more events than one schedule may list is summed up per day in tz: one event per day and routine state, with count and until. Returns: A Flask response with ``from``, ``to``, ``events`` (schedule and sync events, by ``kind``), ``monitors`` and ``truncated``, or 400 for a bad window or time zone.

Not available to personal access tokens

POST/api/messages/{message_id}/cancel

Ask a running answer to stop.

Stop the caller's chat answer that is still being written. The stream ends as if its client had disconnected and keeps what it wrote. Answers 202 once the request is stored; the stream sees it within a few seconds, or when a long tool call returns. Args: message_id: The answer's message id. Returns: 202 when the stop was requested, 404 when the caller has no such message, 409 when it is not running (finished, or paused for a tool approval), 503 without Redis.

Not available to personal access tokens

POST/api/get_feedback_analytics

Get feedback analytics data.

Token scope: analytics:read

JSON body (GetFeedbackAnalyticsModel):

POST/api/get_message_analytics

Get message analytics based on filter option.

Token scope: analytics:read

JSON body (GetMessageAnalyticsModel):

POST/api/get_schedule_analytics

Get scheduled agent run outcomes over time.

Token scope: analytics:read

JSON body (GetScheduleAnalyticsModel):

POST/api/get_token_analytics

Get token analytics data.

Token scope: analytics:read

JSON body (GetTokenAnalyticsModel):

POST/api/get_tool_analytics

Get tool call analytics from the tool execution journal.

Token scope: analytics:read

JSON body (GetToolAnalyticsModel):

POST/api/get_user_logs

Get user activity logs with pagination. Merges chat answers (user_logs), request errors (stack_logs) and scheduled agent runs (schedule_runs) into one timeline. Runs are ordered by their start time; ones still going (answers, scheduled, workflow and webhook runs) carry running: true until their finished row replaces them.

Token scope: analytics:read

JSON body (GetUserLogsModel):

GET/api/traces

Stored execution traces (span timelines) for one Logs row. Pass exactly one of message_id, request_id, activity_id, workflow_run_id or id; api_key_id scopes to an agent you own.

Token scope: analytics:read

GET/api/artifacts

List artifacts for a conversation, workflow run, or the caller.

Not available to personal access tokens

GET/api/artifacts/{artifact_id}

Get an artifact's metadata, version list, and current spec.

Not available to personal access tokens

DELETE/api/artifacts/{artifact_id}

Delete an artifact and all its versions (owner only)

Not available to personal access tokens

POST/api/artifacts/{artifact_id}/restore

Restore a prior version by appending it as the new current version.

Not available to personal access tokens

GET/api/artifacts/{artifact_id}/versions/{version}

Get a single artifact version's metadata and spec.

Not available to personal access tokens

GET/api/images/{agent_id}/{capability}

Serve an agent image using an opaque capability URL.

Not available to personal access tokens

POST/api/store_attachment

Stores one or multiple attachments without vectorization or training. Supports user or API key authentication.

Token scope: chat:run

JSON body (AttachmentModel):

POST/api/stt

Transcribe an uploaded audio file.

Not available to personal access tokens

JSON body (SpeechToTextModel):

POST/api/stt/live/chunk

Transcribe a chunk for a live speech-to-text session.

Not available to personal access tokens

JSON body (LiveSpeechToTextChunkModel):

POST/api/stt/live/finish

Finish a live speech-to-text session.

Not available to personal access tokens

POST/api/stt/live/start

Start a live speech-to-text session.

Not available to personal access tokens

POST/api/tts

Synthesize audio speech from text.

Not available to personal access tokens

JSON body (TextToSpeechModel):

GET/api/background_jobs

List the caller's background jobs of one conversation, newest first (no result bodies).

Token scope: conversations:read

GET/api/background_jobs/{job_id}

One background job: its state, progress and, once finished, a result preview.

Token scope: conversations:read

POST/api/background_jobs/{job_id}/cancel

Ask a running background job to stop. It ends as cancelled once its work really stops; a step already under way may still complete.

Token scope: conversations:write

GET/api/delete_all_conversations

Deletes all conversations for a specific user.

Token scope: conversations:write

POST/api/delete_conversation

Deletes a conversation by ID.

Token scope: conversations:write

POST/api/feedback

Submit feedback for a conversation.

Token scope: conversations:write

JSON body (FeedbackModel):

GET/api/get_conversations

Retrieve the user's sidebar conversations (visibility = listed), newest first, ordered by ``date`` DESC then ``id`` DESC. Each item carries ``date`` (ISO-8601). To page older conversations, pass the last item's ``date`` and ``id`` as ``before`` and ``before_id``. Invalid params are ignored.

Token scope: conversations:read

GET/api/get_single_conversation

Retrieve a single conversation by ID.

Token scope: conversations:read

GET/api/messages/{message_id}/tail

Current state of one conversation_messages row, scoped to the authenticated user. Used to reconnect to an in-flight stream after a refresh.

Token scope: chat:run or conversations:read

GET/api/search_conversations

Search the authenticated user's conversations by name or message content (case-insensitive substring match). Mirrors the visibility filter and response shape of /get_conversations, and additionally returns ``match_field`` (``name``, ``prompt`` or ``response``) and ``match_snippet`` (a short excerpt of the matched text centered on the query) for each result.

Token scope: conversations:read

POST/api/update_conversation_name

Updates the name of a conversation.

Token scope: conversations:write

JSON body (UpdateConversationModel):

GET/api/user/me

Return ``{user_id, roles, email?, name?, picture?}`` for the caller.

Any valid personal access token

GET/api/user/quota

Return the caller's limited buckets: ``{bucket, tokens, cost, resets_at}`` each.

Any valid personal access token

GET/api/models

Get list of available models with their capabilities.

When the request is authenticated, the response includes the user's own BYOM registrations alongside the built-in catalog.

Token scope: chat:run or models:read

GET/api/user/models

List the current user's BYOM custom models.

Token scope: models:read

POST/api/user/models

Register a new BYOM custom model.

Token scope: models:write

POST/api/user/models/test

Test an arbitrary BYOM payload (display_name / model id / base_url / api_key) without saving. Used by the UI's 'Test connection' button so the user can validate before they Save. Uses the selected API protocol with the same SSRF guard and 5s timeout as the by-id variant.

Token scope: models:write

GET/api/user/models/{model_id}

Get one BYOM custom model.

Token scope: models:read

PATCH/api/user/models/{model_id}

Update a BYOM custom model (partial)

Token scope: models:write

DELETE/api/user/models/{model_id}

Delete a BYOM custom model.

Token scope: models:write

POST/api/user/models/{model_id}/test

Test a saved BYOM record. Defaults to the stored base_url / upstream_model_id / encrypted api_key, but any of those can be overridden via the request body so the UI can test in-flight edits before saving. Used by the 'Test connection' button in edit mode.

Token scope: models:write

POST/api/conversations/{conversation_id}/read

Clear the conversation's unread mark (the user opened it). Idempotent.

Not available to personal access tokens

POST/api/presence

Report what one tab shows: sent when its visibility or route changes and every ~20 s while visible. A report counts for 45 s; `closing: true` forgets the tab at once. A user is not notified about a conversation a visible tab of theirs shows.

Not available to personal access tokens

JSON body (PresenceReport):

GET/api/push/public_key

Whether Web Push is configured, and the VAPID public key browsers subscribe with (`applicationServerKey`, raw base64url).

Not available to personal access tokens

POST/api/push/subscriptions

Save this browser's Web Push subscription (the browser's `PushSubscription` JSON) for the caller. The endpoint must be https on a known push service. Saving a known endpoint moves it to the caller. 503 when Web Push is not configured.

Not available to personal access tokens

JSON body (PushSubscription):

DELETE/api/push/subscriptions

Forget this browser's Web Push subscription: `{endpoint}` in the body, or `?endpoint=`.

Not available to personal access tokens

JSON body (PushUnsubscribe):

POST/api/adopt_agent

Adopt an agent by ID.

Token scope: agents:write

GET/api/agent_webhook

Generate webhook URL for the agent.

Token scope: agents:keys

POST/api/create_agent

Create a new agent.

Token scope: agents:write

JSON body (CreateAgentModel):

DELETE/api/delete_agent

Delete an agent by ID.

Token scope: agents:write

GET/api/export_agent

Export an agent as YAML.

Token scope: agents:read

GET/api/get_agent

Get agent by ID.

Token scope: agents:read

GET/api/get_agents

Retrieve agents for the user.

Token scope: agents:read

POST/api/import_agent

Import an agent from YAML: create a draft, or update the agent matched by id or slug.

Token scope: agents:write

POST/api/import_agent/plan

Dry-run an agent YAML import and return the resolution plan.

Token scope: agents:write

POST/api/pin_agent

Pin or unpin an agent.

Token scope: agents:write

GET/api/pinned_agents

Get pinned agents for the user.

Token scope: agents:read

POST/api/regenerate_agent_key/{agent_id}

Rotate an agent's API key. The previous key is invalidated immediately and a fresh key is returned once. Historical logging and usage records are re-pointed to the new key so analytics stay intact. Owner only.

Token scope: agents:keys

DELETE/api/remove_shared_agent

Remove a shared agent from the current user's shared list.

Token scope: agents:write

PUT/api/share_agent

Share or unshare an agent.

Token scope: agents:write

JSON body (ShareAgentModel):

GET/api/shared_agent

Get a shared agent by token or ID.

Not available to personal access tokens

GET/api/shared_agents

Get shared agents explicitly shared with the user.

Token scope: agents:read

GET/api/template_agents

Get template/premade agents.

Token scope: agents:read

PUT/api/update_agent/{agent_id}

Update an existing agent.

Token scope: agents:write

JSON body (UpdateAgentModel):

GET/api/webhooks/agents/{webhook_token}

Webhook listener for agent events (GET). Uses URL query parameters as payload to trigger processing. Honors an optional ``Idempotency-Key`` header: a repeat request with the same key within 24h returns the original cached response and does not re-enqueue the task.

Not available to personal access tokens

POST/api/webhooks/agents/{webhook_token}

Webhook listener for agent events (POST). Expects JSON payload, which is used to trigger processing. Honors an optional ``Idempotency-Key`` header: a repeat request with the same key within 24h returns the original cached response and does not re-enqueue the task.

Not available to personal access tokens

GET/api/agents/folders/

Get all folders for the user.

Token scope: agents:read

POST/api/agents/folders/

Create a new folder.

Token scope: agents:write

JSON body (CreateFolder):

POST/api/agents/folders/bulk_move

Move multiple agents to a folder.

Token scope: agents:write

JSON body (BulkMoveAgents):

POST/api/agents/folders/move_agent

Move an agent to a folder or remove from folder.

Token scope: agents:write

JSON body (MoveAgent):

GET/api/agents/folders/{folder_id}

Get a specific folder with its agents.

Token scope: agents:read

PUT/api/agents/folders/{folder_id}

Update a folder.

Token scope: agents:write

DELETE/api/agents/folders/{folder_id}

Delete a folder.

Token scope: agents:write

GET/api/agents/defaults

The guardrails a new agent starts with (set by an admin under Admin > Defaults), for prefilling the new-agent form: `{guardrails: {...}}`, the built-in defaults when none are set.

Token scope: agents:read

GET/api/guardrails/catalog

List available guardrail checks and their capabilities.

Token scope: agents:read

GET/api/guardrails/events

List guardrail decisions recorded for an agent.

Token scope: agents:read

GET/api/guardrails/summary

Aggregate guardrail activity for the caller.

Token scope: agents:read

GET/api/triggers/{token}

A GET call, taken only by a link created with methods ["POST", "GET"]: the query parameters are the delivery (a dotted key nests). A HEAD, a prefetch (Purpose / Sec-Purpose: prefetch) or a known link-preview or crawler User-Agent gets 200 {ignored} and changes nothing. 202 when accepted, 405 for a POST-only link, 404 for an unknown, expired, revoked or used-up one, 429 when rate limited.

Not available to personal access tokens

POST/api/triggers/{token}

Deliver an event to a monitor's webhook trigger link. Public: the token is the credential. Accepts JSON, form or text up to TRIGGER_MAX_PAYLOAD_BYTES. Signed links verify Standard Webhooks (webhook-id/webhook-timestamp/webhook-signature, 5 minute tolerance), GitHub X-Hub-Signature-256, X-Signature: sha256=<hex>, Stripe-Signature (t=..,v1=.., 5 minute tolerance), Slack X-Slack-Signature with X-Slack-Request-Timestamp (5 minute tolerance; a url_verification challenge is answered with 200 {challenge}), a static token header (X-Webhook-Token unless the link names another) or Authorization: Bearer. Deduplicated on Idempotency-Key, webhook-id, X-GitHub-Delivery or the Stripe/Slack event id, else the body hash. 202 when accepted; 404 for an unknown, expired, revoked or used-up link; 401 for a bad signature; 413 for a large body; 429 past TRIGGER_RATE_PER_MINUTE.

Not available to personal access tokens

GET/api/approvals/{token}

What an approval link asks: its title, question, details, options and whether it was decided. Public (the token is the credential); reading it changes nothing.

Not available to personal access tokens

POST/api/approvals/{token}

Decide an approval link: {decision, comment?}, where decision is one of its options. The first decision wins and resumes the conversation that asked; later ones get 409. 404 for an unknown, expired or revoked link, 400 for an option it doesn't offer, 429 when rate limited.

Not available to personal access tokens

GET/api/monitors

The caller's monitors, newest first: what each watches, its interval, last check, wakes left, expiry and links (never tokens or secrets).

Token scope: conversations:read

GET/api/monitors/{monitor_id}

One of the caller's monitors.

Token scope: conversations:read

GET/api/monitors/{monitor_id}/secret

The signing secret of one of the caller's webhook monitors, so the owner can configure the sender. Only the owner's session may read it (never an access token); the model only ever sees its reference. Rate limited, audited, never cached or logged. 404 when the monitor has no live signed link, or its secret was never set.

Not available to personal access tokens

PUT/api/monitors/{monitor_id}/secret

Set the signing secret of one of the caller's webhook monitors: {secret}. For Stripe and Slack, which create their own signing secret, this is how the link gets it; for any other signed scheme it replaces the generated one. Only the owner's session may set it (never an access token). Rate limited, audited without the value, never logged. 400 for a value that can't be this scheme's secret, 404 when the monitor has no live signed link.

Not available to personal access tokens

PUT/api/monitors/{monitor_id}/secret/exposure

Show (or stop showing) one of the caller's webhook monitors' raw signing secret to the assistant: {exposed: true|false}. Shown, monitor_list gives the assistant the value, which then goes to the model provider. Only the owner's session may change it (never an access token, never the assistant). Rate limited and audited. 404 when the monitor has no live signed link with a secret.

Not available to personal access tokens

POST/api/monitors/{monitor_id}/{action}

Pause, resume or cancel one of the caller's monitors. Cancelling revokes its links and any approval its source was given; resuming a polled monitor checks it again right away. 409 when the monitor is not in a state the action applies to.

Token scope: conversations:write

POST/api/create_prompt

Create a new prompt.

Token scope: prompts:write

JSON body (CreatePromptModel):

POST/api/delete_prompt

Delete a prompt by ID.

Token scope: prompts:write

JSON body (DeletePromptModel):

GET/api/get_prompts

Get all prompts for the user.

Token scope: prompts:read

GET/api/get_single_prompt

Get a single prompt by ID.

Token scope: prompts:read

POST/api/update_prompt

Update an existing prompt.

Token scope: prompts:write

JSON body (UpdatePromptModel):

GET/api/agents/{agent_id}/schedules

List schedules for an agent (recurring + one-time).

Token scope: schedules:read

POST/api/agents/{agent_id}/schedules

Create a schedule (recurring or one-time) for an agent.

Token scope: schedules:write

JSON body (ScheduleCreate):

GET/api/agents/{agent_id}/schedules/stats

Return run count, failures, tokens and latest failure for an agent.

Run stats for an agent's schedules over a recent window. Args: agent_id: Agent id from the URL. Returns: A Flask response with ``days``, ``runs``, ``failed``, ``tokens`` and ``latest_failure`` (or an error envelope).

Token scope: schedules:read

GET/api/schedules

Return the caller's schedules with agent and origin-chat names.

List the caller's schedules across every agent: their own, agentless ones created in chat, and those of teammates' agents they manage through a team (team: true). Monitors are not included. Returns: A Flask response with ``schedules``: schedule rows plus ``agent_name``, ``agent_image`` (a signed URL, never a storage path), ``origin_conversation_name`` and ``team`` (a schedule of a teammate's agent the caller manages through a team).

Token scope: schedules:read

GET/api/schedules/{schedule_id}

Get schedule by id.

Token scope: schedules:read

PUT/api/schedules/{schedule_id}

Edit a schedule's editable fields.

Token scope: schedules:write

PATCH/api/schedules/{schedule_id}

Pause / resume a schedule.

Token scope: schedules:write

DELETE/api/schedules/{schedule_id}

Cancel / delete a schedule.

Token scope: schedules:write

POST/api/schedules/{schedule_id}/run

Run a schedule immediately (trigger_source='manual').

Token scope: schedules:write

GET/api/schedules/{schedule_id}/runs

Paginated run log for a schedule.

Token scope: schedules:read

GET/api/schedules/{schedule_id}/runs/{run_id}

Full output / error for a single run.

Token scope: schedules:read

POST/api/share

Share a conversation.

Not available to personal access tokens

JSON body (ShareConversationModel):

GET/api/shared_conversation/{identifier}

Get publicly shared conversations by identifier.

Not available to personal access tokens

POST/api/add_chunk

Adds a new chunk to the document.

Token scope: sources:write

JSON body (AddChunkModel):

GET/api/combine

Redirects /api/combine to /api/sources for backward compatibility.

Not available to personal access tokens

DELETE/api/delete_chunk

Deletes a specific chunk from the document.

Token scope: sources:write

GET/api/delete_old

Deletes old indexes and associated files.

Token scope: sources:write

GET/api/directory_structure

Get the directory structure for a document.

Token scope: sources:read

GET/api/get_chunks

Retrieves chunks from a document, optionally filtered by file path and search term.

Token scope: sources:read

POST/api/manage_source_files

Add files, remove files, or remove directories from an existing source.

Token scope: sources:write

JSON body (ManageSourceFilesModel):

POST/api/manage_sync

Manage sync frequency for sources.

Token scope: sources:write

JSON body (ManageSyncModel):

POST/api/remote

Uploads remote source for vectorization. Honors an optional ``Idempotency-Key`` header: a repeat request with the same key within 24h returns the original cached response without re-enqueuing.

Token scope: sources:write

JSON body (RemoteUploadModel):

GET/api/sources

Provide JSON file with combined available indexes.

Token scope: sources:read

GET/api/sources/defaults

The retrieval settings a new source starts with (set by an admin under Admin > Defaults), for prefilling create forms: `{retrieval: {...}}`, the built-in defaults when none are set.

Token scope: sources:read

POST/api/sources/from_attachments

Creates a Knowledge source from chat attachments the caller already uploaded. The stored originals are copied into a new source and ingested like an upload (a zip contributes its files); the files together may not exceed the upload request limit (413). Returns the source id and the ingest task id; progress arrives as ``source.ingest.*`` events for that source id. Honors an optional ``Idempotency-Key`` header: a repeat request with the same key within 24h returns the first request's source and task ids without copying the files or queueing a second ingest.

Token scope: sources:write

JSON body (SourceFromAttachmentsModel):

GET/api/sources/paginated

Get document with pagination, sorting and filtering.

Token scope: sources:read

POST/api/sources/reingest

Re-run ingestion for a source — e.g. to recover a stalled embed flagged by the reconciler.

Token scope: sources:write

JSON body (ReingestSourceModel):

POST/api/sources/wiki

Create an LLM-editable wiki source. No ingestion task is enqueued; pages are authored via the WikiTool. An optional initial_content seeds /index.md and triggers its per-page re-embed.

Token scope: sources:write

JSON body (CreateWikiModel):

GET/api/sources/{source_id}/chunk

Return the cited chunk and its source.

The chunk behind a citation, found by its content key, else by its excerpt, with what the reader needs about its source. 404 when the caller cannot see the source, or with reason chunk_missing when neither finds the chunk (the source was edited); 501 with reason unsupported when the vector store cannot look chunks up. Args: source_id: The source the citation names. Returns: Response: ``{"success", "chunk", "source", "page_path"}``, or an error with ``reason`` ``chunk_missing`` (404) or ``unsupported`` (501) the reader tells apart from a source out of reach.

Token scope: sources:read

PATCH/api/sources/{source_id}/config

Edit a source's behavior config. Retrieval-time fields take effect live; chunking changes require an explicit re-ingest (surfaced as requires_reingest). A section the body leaves out (chunking, retrieval, graph) keeps its saved value, so a body with only `retrieval` saves just that.

Token scope: sources:write

JSON body (SourceConfigModel):

GET/api/sources/{source_id}/graph

Bounded knowledge-graph overview for a graphrag source: top nodes by degree and the edges among them (read access: owner or shared). Returns empty lists when no graph has been built yet.

Token scope: sources:read

GET/api/sources/{source_id}/graph/node/{node_id}

A graph node's description and its linked chunks (read access: owner or shared).

Token scope: sources:read

GET/api/sources/{source_id}/graph/nodes

List one page of a source's graph nodes with type facets.

Paged, searchable list of a graphrag source's nodes, highest degree first, plus type facets over all its nodes (read access: owner or shared). Query params: q (name substring), type (type key), page (1-based), per_page (1-100, default 25). Args: source_id: The source id from the URL. Returns: Response: ``{success, nodes, total, page, per_page, types}``, or 401/404/400 on missing auth, no read access or a failure. ``page`` is clamped to ``1..GRAPH_NODE_LIST_MAX_PAGE`` and ``per_page`` to ``1..GRAPH_NODE_LIST_MAX_LIMIT``. A graph store that is not configured or has no tables yet reads as an empty page, like the overview; any other store query failure is a 400, never an empty 200.

Token scope: sources:read

POST/api/sources/{source_id}/graphrag/enable

Enable GraphRAG on a source: flips its config to graphrag mode and enqueues graph extraction over its embedded chunks. Requires VECTOR_STORE=pgvector and GRAPHRAG_ENABLED. Write access required (owner/editor). The config kind cannot be set to graphrag via the config PATCH endpoint.

Token scope: sources:write

POST/api/sources/{source_id}/injection_review

Add a chunk text's hash to the source's owner allowlist, or remove it.

Mark a flagged chunk safe from prompt-injection screening for agents using this source, or undo that. Needs chunk-edit access. Keyed by the chunk text, so editing the chunk drops the mark. At most 1000 chunks per source. Returns `{success, content_hash, allowed, count}`. Args: source_id: The source. Returns: Response: ``{"success", "content_hash", "allowed", "count"}``, a 400 for a bad body or a full allowlist, or the access error.

Token scope: sources:write

JSON body (InjectionReviewModel):

POST/api/sources/{source_id}/search

Run the real retrieval pipeline against one source and return the ranked chunks it produces, optionally under an ad-hoc retrieval config. Read-only: nothing is saved.

Token scope: chat:run

JSON body (SourceSearchModel):

POST/api/sources/{source_id}/wiki/convert

Convert an ingested source into a wiki. A blank source is enabled inline; a source with files runs a conversion task (poll its status for the per-file summary). Write access required (owner/editor).

Token scope: sources:write

GET/api/sources/{source_id}/wiki/page

Fetch a single wiki page's content fresh from storage.

Token scope: sources:read

PUT/api/sources/{source_id}/wiki/page

Create or overwrite a wiki page (human edit). Write access required; a stale expected_version returns 409.

Token scope: sources:write

JSON body (WikiPageEditModel):

GET/api/sources/{source_id}/wiki/pages

List a wiki source's pages (read access: owner or shared).

Token scope: sources:read

GET/api/sources/{source_id}/wiki/settings

A wiki's settings. Anyone who can see the wiki may read them; returns allow_outside_edits plus the caller's access.

Token scope: sources:read

PUT/api/sources/{source_id}/wiki/settings

Change a wiki's settings (owner only, manage_settings). Body: {"allow_outside_edits": bool}: whether runs from an agent's API key or widget may edit the wiki.

Not available to personal access tokens

POST/api/sync_source

Trigger an immediate sync for a source.

Token scope: sources:write

JSON body (SyncSourceModel):

GET/api/task_status

Get celery job status.

Token scope: chat:run or sources:read or sources:write

JSON body (TaskStatusModel):

PUT/api/update_chunk

Updates an existing chunk in the document.

Token scope: sources:write

JSON body (UpdateChunkModel):

POST/api/upload

Uploads a file to be vectorized and indexed. Honors an optional ``Idempotency-Key`` header: a repeat request with the same key within 24h returns the original cached response without re-enqueuing.

Token scope: sources:write

JSON body (UploadModel):

GET/api/admin/teams

Global-admin oversight: every team with member counts, or a picker search.

With no query args every team is returned. Any of these switches to a bounded search (same row shape): q: Case-insensitive substring of the team name or slug. without_quota: ``1`` keeps only teams with no team ``all``-bucket quota policy. limit: The most rows to return, clamped to 1-100 (default 20).

Not available to personal access tokens

GET/api/resource_settings

A resource's sharing switches.

Anyone with access may read them. Query: ``resource_type``, ``resource_id``. Returns ``settings`` as ``[{key, value, default}]`` in display order, plus the caller's ``access`` and ``allowed_actions``.

Token scope: teams:read

PUT/api/resource_settings

Change a resource's sharing switches.

Needs ``manage_settings`` (owner). Body: ``{"resource_type", "resource_id", "settings": {key: bool}}``. An unknown key or a non-boolean value is a 400. Returns the GET shape.

Not available to personal access tokens

GET/api/resource_shares

List the teams a resource is shared with.

Needs ``share`` on it. Powers the share dialog (current shares + unshare), so only someone who may change the sharing can enumerate it: 404 when the resource isn't visible, 403 when the caller's role can't share.

Token scope: teams:read

GET/api/teams

List the teams the caller belongs to, each annotated with their role.

Token scope: teams:read

POST/api/teams

Create a team (self-serve)

The creator becomes its first team_admin.

Not available to personal access tokens

GET/api/teams/{team_id}

Team detail with members and the caller's role.

Requires membership.

Token scope: teams:read

PUT/api/teams/{team_id}

Update team name/description.

Requires team_admin.

Not available to personal access tokens

DELETE/api/teams/{team_id}

Delete the team.

Owner-only (a global admin overrides).

Not available to personal access tokens

GET/api/teams/{team_id}/grants

List resources shared with this team.

Requires membership. Each row carries the resource's name, owner and people labels (email when on file, else null) and ``caller`` — the caller's own live ``{access, allowed_actions}`` on that resource (null if none). A plain member sees whole-team grants and grants aimed at them; a team_admin, or someone with ``share`` on the resource, sees every grant.

Token scope: teams:read

POST/api/teams/{team_id}/grants

Share a resource with this team, or change an existing grant's level.

Needs ``share`` on the resource (the owner, or an editor when the owner turned on ``editors_can_share``) and membership of the team. The grant records the real owner as ``owner_id`` and the caller as ``granted_by``.

Not available to personal access tokens

DELETE/api/teams/{team_id}/grants

Unshare a resource from this team.

Allowed with ``share`` on the resource — no membership needed, so an owner who left the team can still pull their resource back — or for a team_admin of this team. ``target_user_id`` picks one member's grant (absent → the whole-team grant). Identifiers come from query params (some proxies strip DELETE bodies), with a JSON-body fallback.

Not available to personal access tokens

GET/api/teams/{team_id}/members

List members.

Requires membership. Optional query args: ``q`` (case-insensitive substring over email and user id), ``page`` (1-based) and ``page_size`` (1..100; paginates only when given). ``total`` is the row count after the ``q`` filter.

Token scope: teams:read

POST/api/teams/{team_id}/members

Add a member by email (preferred) or raw user_id.

Requires team_admin.

Not available to personal access tokens

PUT/api/teams/{team_id}/members/{member_id}

Change a member's role.

Requires team_admin. Guards the last admin.

Not available to personal access tokens

DELETE/api/teams/{team_id}/members/{member_id}

Remove a member.

team_admin removes anyone; a member may remove self (leave). Guards the last admin.

Not available to personal access tokens

POST/api/teams/{team_id}/transfer_owner

Transfer team ownership.

Owner-only (global admin overrides). The new owner must already be a member; they are promoted to team_admin.

Not available to personal access tokens

GET/api/artifact/{artifact_id}

Get artifact data by artifact ID. Returns all todos for the tool when fetching a todo artifact.

Not available to personal access tokens

GET/api/available_tools

Get available tools for a user.

Token scope: tools:read

POST/api/create_tool

Create a new tool.

Token scope: tools:write

JSON body (CreateToolModel):

POST/api/delete_tool

Delete a tool by ID.

Token scope: tools:write

JSON body (DeleteToolModel):

GET/api/get_tools

Get tools created by a user.

Token scope: tools:read

GET/api/mcp_server/auth_status

Batch check auth status for all MCP tools. Lightweight DB-only check — no network calls to MCP servers.

Not available to personal access tokens

GET/api/mcp_server/callback

Handle OAuth callback by providing the authorization code and state.

Not available to personal access tokens

JSON body (MCPServerCallbackModel):

POST/api/mcp_server/oauth_cancel

Cancel an MCP OAuth sign-in the caller started, so the worker stops waiting for its callback.

Token scope: tools:write

JSON body (MCPOAuthCancelModel):

POST/api/mcp_server/save

Create or update MCP server with automatic tool discovery. While Admin > Guardrails warns on tool descriptions, each discovered action is scored for prompt injection and stored with `injection: {p, scorer}`; the response's `injection` is `{flagged: [names], unscored: [names]}` (null while the warnings are off). Nothing is deactivated.

Token scope: tools:write

JSON body (MCPServerSaveModel):

POST/api/mcp_server/test

Test MCP server connection with provided configuration.

Token scope: tools:write

JSON body (MCPServerTestModel):

POST/api/parse_spec

Parse an API specification (OpenAPI 3.x or Swagger 2.0) and return actions.

Token scope: tools:write

POST/api/update_tool

Update a tool's names, actions, config or chat switch.

Update a tool by ID The tool type (``name``) never changes. ``actions`` are checked against the stored ones like ``/api/update_tool_actions``: nothing is added and fixed values are the owner's. A connection-backed MCP server is moved only through ``/api/mcp_server/save``. Returns: ``{"success": true}``, or 400 / 403 / 404 with a message.

Token scope: tools:write

JSON body (UpdateToolModel):

POST/api/update_tool_actions

Update the actions of a tool.

Token scope: tools:write

JSON body (UpdateToolActionsModel):

POST/api/update_tool_config

Replace a tool's config, keeping stored secrets the client left out.

Update the configuration of a tool A connection-backed tool's new key goes to its connection (the owner's to change) and its server cannot be moved here; an api_tool's fixed values are the owner's. Returns: ``{"success": true}``, or 400 / 403 / 404 with a message.

Token scope: tools:write

JSON body (UpdateToolConfigModel):

POST/api/update_tool_status

Update the status of a tool.

Token scope: tools:write

JSON body (UpdateToolStatusModel):

POST/api/workflows

Create a new workflow with nodes and edges.

Token scope: workflows:write

GET/api/workflows/{workflow_id}

Get workflow details with nodes and edges.

Token scope: workflows:read

PUT/api/workflows/{workflow_id}

Update workflow and replace nodes/edges.

Token scope: workflows:write

DELETE/api/workflows/{workflow_id}

Delete workflow and its graph.

Token scope: workflows:write

GET/api/connectors/auth

Get connector OAuth authorization URL.

Not available to personal access tokens

POST/api/connectors/auth/complete

Finish a connector sign-in: the app's callback page posts the provider's code and state.

Not available to personal access tokens

JSON body (ConnectorAuthCompleteModel):

GET/api/connectors/callback

Forward the provider's answer to the app page that finishes the sign-in.

OAuth redirect URI for external connectors; forwards to the app's callback page.

Not available to personal access tokens

GET/api/connectors/callback-status

Return HTML page with connector authentication status.

Return HTML page with connector authentication status.

Not available to personal access tokens

POST/api/connectors/disconnect

Disconnect a connector session.

Not available to personal access tokens

JSON body (ConnectorDisconnectModel):

POST/api/connectors/files

List files from a connector provider (supports pagination and search)

Not available to personal access tokens

JSON body (ConnectorFilesModel):

POST/api/connectors/sync

Sync connector source to check for modifications.

Not available to personal access tokens

JSON body (ConnectorSyncModel):

POST/api/connectors/validate-session

Validate a connection and return the account and a short-lived access token.

Not available to personal access tokens

JSON body (ConnectorValidateSessionModel):

GET/api/connections

The caller's connections with status and linked resource counts.

Not available to personal access tokens

POST/api/connections

Create a connection from pasted credentials: {connector_key, credentials, label?}. Same credentials reuse the same connection.

Not available to personal access tokens

POST/api/connections/claim

One-time link of a legacy browser session token ({provider, session_token}) to the caller's connection. Removed next release.

Not available to personal access tokens

PUT/api/connections/tools/{tool_id}/credential-mode

Whose account a shared connection-backed tool uses: {mode: owner | member}. Owner only; refused when an admin forces a mode for the connector.

Not available to personal access tokens

GET/api/connections/{connection_id}

One connection with the sources it syncs and the tools it provides.

Not available to personal access tokens

PATCH/api/connections/{connection_id}

Name an account: {name}. An empty name clears it. Owner only.

Not available to personal access tokens

DELETE/api/connections/{connection_id}

Remove a connection: {sources: keep | delete, tools: delete | keep}. Kept sources keep their content and stop syncing.

Not available to personal access tokens

POST/api/connections/{connection_id}/disconnect

Delete a connection's stored credentials; its sources and tools stay.

Not available to personal access tokens

GET/api/connections/{connection_id}/linear

Linear: the teams and projects the connection can see, for the sync picker. Read through Linear's MCP server with the connection's sign-in.

Not available to personal access tokens

POST/api/connections/{connection_id}/picker-token

A short-lived access token for a browser-side file picker. Owner only; never a refresh token.

Not available to personal access tokens

POST/api/connections/{connection_id}/reconnect

OAuth: returns an authorization URL for the same account. API key: accepts {credentials} and replaces the stored ones.

Not available to personal access tokens

POST/api/connections/{connection_id}/refresh-tools

MCP: re-scan the server's actions and return what was added and removed.

Not available to personal access tokens

GET/api/connections/{connection_id}/repositories

GitHub: the repositories the connection can read, for the sync picker. install_url is where a GitHub App sign-in chooses more repositories.

Not available to personal access tokens

POST/api/connections/{connection_id}/setup

Apply the connect wizard's choices: {create_tools, allow_writes?, tool_permissions?, sync?: {items, frequency, name?, config?}}. allow_writes points GitHub's tool at its write endpoint. config is the synced source's retrieval settings, validated like an upload's. Honours an Idempotency-Key header for the sync.

Not available to personal access tokens

PUT/api/connections/{connection_id}/tools/{tool_id}/parameters

Fix or release an action's parameters: {action, parameters: {name: value | null}}. A value is sent on every call and hidden from the model; null lets the model decide. Owner only.

Not available to personal access tokens

PUT/api/connections/{connection_id}/tools/{tool_id}/permissions

Set per-action permissions: {permissions: {action: always | ask | off}}.

Not available to personal access tokens

PUT/api/connections/{connection_id}/writes

GitHub: let agents make changes through this connection, or only read: {allow}. Re-reads the tool's actions from the matching endpoint. Owner only.

Not available to personal access tokens

GET/api/connectors/catalog

Every connector with its availability and the caller's connection summary.

Not available to personal access tokens

GET/api/admin/activity

Merged audit feed, newest first, with filters and a total.

Not available to personal access tokens

GET/api/admin/activity/events

Distinct ``(event, category)`` pairs this instance has recorded.

The filter UI offers these instead of a free-text box, so an operator never has to guess that denied logins are ``oidc_login_denied``.

Not available to personal access tokens

GET/api/admin/activity/export

Stream the filtered feed as CSV or NDJSON.

Streamed, not buffered: a compliance export of a busy instance should not be built in memory first. Capped at ``_EXPORT_MAX_ROWS``, and the ``X-Export-Max-Rows`` header reports the cap that was in effect so a truncated export is not mistaken for a complete one.

Not available to personal access tokens

GET/api/admin/admins

List all admins with earliest grant time + grant sources.

Not available to personal access tokens

GET/api/admin/audit

Global auth-events feed, newest first.

Filter by event/user/since.

Not available to personal access tokens

GET/api/admin/connectors

Every connector with its policy, setup state and connection count.

Not available to personal access tokens

PUT/api/admin/connectors

Update policies: {policies: {key: {enabled?, credential_mode?, allow_writes?}}, allow_custom_mcp?}.

Not available to personal access tokens

GET/api/admin/decisions

The decision model as this API process sees it.

Not available to personal access tokens

GET/api/admin/defaults/agents

The guardrails new agents start with, and what the injection model costs on this server.

Not available to personal access tokens

PUT/api/admin/defaults/agents

Store the body's `guardrails` object as the default for new agents; existing agents keep their own.

Not available to personal access tokens

GET/api/admin/defaults/sources

The default retrieval settings for new sources, and what relevance costs on this server.

Not available to personal access tokens

PUT/api/admin/defaults/sources

Store the body's `retrieval` object as the default for new sources; existing sources keep their own.

Not available to personal access tokens

GET/api/admin/devices/audit

Global remote-device command audit feed.

Filter by decision/user/since.

Not available to personal access tokens

GET/api/admin/guardrails

The floor every agent follows, whether MCP tool descriptions are scored, and the injection model's cost.

Not available to personal access tokens

PUT/api/admin/guardrails

Store the body's `floor` (an agent guardrails object, or null for none) and/or `mcp_description_warnings`.

Not available to personal access tokens

GET/api/admin/overview

Top-line KPIs for the dashboard home.

Not available to personal access tokens

GET/api/admin/quotas

Every stored policy, grouped by layer, plus the models cost limits cannot see.

Query args (all optional; without them every row is returned): teams_q: Case-insensitive substring of the team name or slug. users_q: Case-insensitive substring of the user's subject id or email. teams_page / users_page: 1-based page of that list; only a list whose page arg is given is paginated. page_size: Teams or users per page, clamped to 1-100 (default 20); a page carries every bucket row of each of them. ``teams_total`` and ``users_total`` count the teams and users after filtering and before paging. Rows keep the repository order (subject, then bucket).

Not available to personal access tokens

PUT/api/admin/quotas/instance

Set the instance default for one bucket.

Not available to personal access tokens

DELETE/api/admin/quotas/instance

Remove the instance default for ``?bucket=``, or for every bucket.

Not available to personal access tokens

GET/api/admin/quotas/teams/{team_id}

The per-member allowance of one team.

Not available to personal access tokens

PUT/api/admin/quotas/teams/{team_id}

Set the allowance each member of the team gets.

Not available to personal access tokens

DELETE/api/admin/quotas/teams/{team_id}

Remove the team's allowance for ``?bucket=``, or for every bucket.

Not available to personal access tokens

GET/api/admin/quotas/users/{user_id}

A user's overrides and the limits and usage they resolve to.

Not available to personal access tokens

PUT/api/admin/quotas/users/{user_id}

Set one user's override, which beats team allowances and the default.

Not available to personal access tokens

DELETE/api/admin/quotas/users/{user_id}

Remove the user's override for ``?bucket=``, or for every bucket.

Not available to personal access tokens

GET/api/admin/usage

Global usage: time-bucketed series, totals, spend, latency, top users.

Every bucket carries both tokens and USD cost. Quota policies have always been settable in dollars; until now nothing showed the spend they were capping.

Not available to personal access tokens

GET/api/admin/users

List users, paginated, most-recently-seen first.

Each row carries ``last_seen`` (max auth-event time) and the stored ``email`` (null when none is on file); ``?user_id=`` matches either. Admin status is intentionally not joined here; the dashboard cross-references GET /api/admin/admins for badges.

Not available to personal access tokens

GET/api/admin/users/{user_id}

Per-user drill-down: profile, roles, recent auth events, counts.

Not available to personal access tokens

PATCH/api/admin/users/{user_id}

Activate/deactivate a user.

Deactivation also revokes live sessions.

Not available to personal access tokens

POST/api/admin/users/{user_id}/revoke-sessions

Force-logout: revoke the user's live OIDC sessions (best-effort)

Not available to personal access tokens

POST/api/admin/users/{user_id}/role

Grant the admin role to ``user_id`` (manual source)

Idempotent.

Not available to personal access tokens

DELETE/api/admin/users/{user_id}/role

Revoke the manual admin grant.

Refuses to remove the last admin.

Not available to personal access tokens

GET/api/admin/users/{user_id}/usage

One user's spend: daily series plus a split by model and by flow.

Not available to personal access tokens

DELETE/api/admin/tokens/{token_id}

Revoke any user's token.

Not available to personal access tokens

GET/api/admin/users/{user_id}/tokens

List a user's tokens, revoked ones included.

Not available to personal access tokens

GET/api/user/tokens

List the caller's tokens with the scope catalog and the server's token policy.

Not available to personal access tokens

POST/api/user/tokens

Create a token.

The plaintext ``token`` is returned here and never again.

Not available to personal access tokens

DELETE/api/user/tokens/{token_id}

Revoke one of the caller's tokens.

Takes effect on the next request.

Not available to personal access tokens

POST/api/user/tokens/{token_id}/regenerate

Issue a new secret for a token and reset its expiry.

Name, scopes and restrictions stay; the old secret stops working at once. ``expires_in_days`` is optional and defaults to the lifetime the token was last issued with. An expired token can be renewed this way; a revoked one cannot. The plaintext ``token`` is returned here and never again.

Not available to personal access tokens

POST/api/user/tokens/{token_id}/tool

Create an API tool that lets agents read this account with the token.

The body carries the token's plaintext ``token``, which only the caller holds (it was just shown to them), and ``base_url``, where the API is reached. The tool gets the read endpoints the token may call, with the token sealed as their ``Authorization`` header.

Not available to personal access tokens