Endpoints reference

The complete top-level /api/v1 REST surface. This article is generated from the same source the live GET /api/v1 discovery document serves, which is drift-tested against the running route table — so it cannot list an endpoint that does not exist.

Endpoint	Method	Scope	Key type	Summary
`/api/v1/search`	POST	`retrieve`	personal or organization	Semantic search over the knowledge base; returns ranked passages ({id, title, url, text}).
`/api/v1/retrieve`	POST	`retrieve`	personal or organization	Run the full knowledge retrieval pipeline and return ranked candidates without synthesis.
`/api/v1/documents/{document_id}`	GET	`retrieve`	personal or organization	Fetch the stored content + metadata behind one /v1/search result.
`/api/v1/answer`	POST	`answer`	personal or organization	Generate a synthesized answer with citations for organization-grounded claims (full QueryResponse).
`/api/v1/ingest`	POST	`ingest`	personal	Save a note/document as a review-queue draft.
`/api/v1/ingest/{article_id}`	GET	`ingest`	personal	Check the editorial status of a note saved via /v1/ingest.
`/api/v1/agents/{agent_id}/answer`	POST	`answer`	personal	Answer from one specific API-enabled agent (explicit-agent variant of /v1/answer).
`/api/v1/creations`	GET	`retrieve`	personal or organization	List the organization's API-enabled Creations (cursor-paginated).
`/api/v1/creations/{creation_id}`	GET	`retrieve`	personal or organization	Fetch a published Creation by id.
`/api/v1/conversations`	POST	`helpdesk`	organization	Open a new help-desk conversation from an external system.
`/api/v1/conversations`	GET	`helpdesk`	organization	List help-desk conversations (cursor-paginated) with status/channel filters.
`/api/v1/conversations/{conversation_id}`	GET	`helpdesk`	organization	Fetch one help-desk conversation's transcript + metadata.
`/api/v1/conversations/{conversation_id}/reply`	POST	`helpdesk`	organization	Post an operator reply into a help-desk conversation.
`/api/v1/conversations/{conversation_id}/resolve`	POST	`helpdesk`	organization	Set a help-desk conversation's status to resolved.
`/api/v1/conversations/{conversation_id}/note`	POST	`helpdesk`	organization	Add an internal operator note to a help-desk conversation (never shown to the customer).
`/api/v1/capture`	POST	`ingest`	personal	Capture a web page (rendered text + same-site media URLs) into the ingestion review queue.
`/api/v1/capture-defaults`	GET	`ingest`	personal	Read your capture-governance defaults + the organization's policy ceiling.
`/api/v1/capture/discovery-config`	GET	`ingest`	personal	Read the site-capture discovery tuning (regex sources, scroll/pager bounds, per-site overrides).
`/api/v1/capture-defaults`	PUT	`ingest`	personal	Save your capture-governance defaults (validated against the org ceiling).
`/api/v1/skills`	GET	`retrieve`	personal or organization	List the organization's runnable tool-kind skills (platform + custom).
`/api/v1/skills/{skill_id}/run`	POST	`answer`	personal or organization	Run one read/compose-tier skill with the supplied parameters.
`/api/v1/drive/step`	POST	`answer`	personal or organization	Decide the single next browser action for an agentic browser-control (Act) loop.
`/api/v1/agents`	GET	`answer or retrieve`	personal or organization	List the organization's API-enabled agents (slug, name, description, default flag).
`/api/v1/me`	GET	`any`	personal or organization	Identity for the presented key: organization (name + slug), key tier, granted scopes.

A scope of any means any valid key works, no specific scope required.

Endpoint details

`POST /api/v1/search`

Semantic search over the knowledge base; returns ranked passages ({id, title, url, text}).

Scope: retrieve
Key type: personal or organization

Body

Name	Description
`query`	string (required) — the search query.
`agent`	string (optional) — restrict to one agent's knowledge by slug.
`effort`	string (optional) — auto \| fast \| balanced \| thorough \| research (retrieval depth).
`limit`	integer (optional, 1-80) — max passages.

Same operation as the MCP search tool; defaults to the union of API-enabled agents.

`POST /api/v1/retrieve`

Run the full knowledge retrieval pipeline and return ranked candidates without synthesis.

Scope: retrieve
Key type: personal or organization

Body

Name	Description
`query`	string (required) — the retrieval query.
`agent`	string (optional) — restrict to one agent's knowledge by slug.
`effort`	string (optional) — auto \| fast \| balanced \| thorough \| research (retrieval depth).
`limit`	integer (optional, 1-120) — max candidates.
`collapse`	boolean (optional) — one candidate per source when true.
`max_per_source`	integer (optional, 1-20) — max chunks per source when not collapsed.

Paraphrase-aware retrieval using the same candidate pipeline that answer synthesis sees.

`GET /api/v1/documents/{document_id}`

Fetch the stored content + metadata behind one /v1/search result.

Scope: retrieve
Key type: personal or organization

Path parameters

Name	Description
`document_id`	An article: or chunk: handle returned by /v1/search.

Same operation as the MCP fetch tool.

`POST /api/v1/answer`

Generate a synthesized answer with citations for organization-grounded claims (full QueryResponse).

Scope: answer
Key type: personal or organization

Body

Name	Description
`query`	string (required) — the question to answer.
`agent`	string (optional) — answer using a specific agent by slug; defaults to the org's default or first API-enabled agent.
`effort`	string (optional) — auto \| off \| fast \| balanced \| thorough \| research; bounded by the agent's max_answer_effort policy. 'off' answers without knowledge-base retrieval.
`mode`	string (optional) — knowledge_only \| hybrid \| open; defaults to the agent's configured mode. Use knowledge_only to prevent general-knowledge fallback.
`council`	string (optional) — run a saved Council by slug.

Same operation as the MCP answer tool. Citations can be empty when hybrid/open mode answers from general knowledge, or when effort=off skips retrieval.

`POST /api/v1/ingest`

Save a note/document as a review-queue draft.

Scope: ingest
Key type: personal

Body

Name	Description
`title`	string (required) — a short title.
`content`	string (required) — the full text to save.
`category`	string (optional) — a category or topic.

Same operation as the MCP ingest tool; saved as a DRAFT pending editor review.

`GET /api/v1/ingest/{article_id}`

Check the editorial status of a note saved via /v1/ingest.

Scope: ingest
Key type: personal

Path parameters

Name	Description
`article_id`	The id returned by POST /v1/ingest.

Returns status (draft | approved | verified) and whether it has landed live or is in review.

`POST /api/v1/agents/{agent_id}/answer`

Answer from one specific API-enabled agent (explicit-agent variant of /v1/answer).

Scope: answer
Key type: personal

Path parameters

Name	Description
`agent_id`	The agent's slug (the agent must have API access enabled).

Body

Name	Description
`query`	string (required) — the question to answer.
`answer_effort`	string (optional) — auto \| off \| fast \| balanced \| thorough \| research (bounded by the agent's max_answer_effort policy; 'off' answers without knowledge-base retrieval).
`answer_mode`	string (optional) — knowledge_only \| hybrid \| open (shown in the app as Strict \| Balanced \| Flexible).
`reasoning`	string (optional) — auto \| off \| light \| standard \| deep (model thinking depth, independent of answer_effort).

`GET /api/v1/creations`

List the organization's API-enabled Creations (cursor-paginated).

Scope: retrieve
Key type: personal or organization

Query parameters

Name	Description
`cursor`	string (optional) — opaque next_cursor from a prior page.
`limit`	integer (optional, 1-100) — page size (default 25).

Only Creations whose owner enabled the API channel appear; fetch a body with /v1/creations/{id}.

`GET /api/v1/creations/{creation_id}`

Fetch a published Creation by id.

Scope: retrieve
Key type: personal or organization

Path parameters

Name	Description
`creation_id`	The Creation id.

`POST /api/v1/conversations`

Open a new help-desk conversation from an external system.

Scope: helpdesk
Key type: organization

Body

Name	Description
`body`	string (required) — the inbound customer message (1-4000 chars).
`customer_email`	string (optional) — resolved-or-created in the identity layer.
`subject`	string (optional) — the conversation title.
`channel`	string (optional) — website_widget \| public_widget \| email \| sms \| voice (default email).

Organization key only. Returns the conversation summary; a follow-up GET /v1/conversations lists it.

`GET /api/v1/conversations`

List help-desk conversations (cursor-paginated) with status/channel filters.

Scope: helpdesk
Key type: organization

Query parameters

Name	Description
`cursor`	string (optional) — opaque next_cursor from a prior page.
`status`	string (optional) — active \| needs_follow_up \| resolved \| archived.
`channel`	string (optional) — website_widget \| public_widget \| email.
`limit`	integer (optional, 1-100) — page size (default 25).

Organization key only; personal keys 403. Newest-first.

`GET /api/v1/conversations/{conversation_id}`

Fetch one help-desk conversation's transcript + metadata.

Scope: helpdesk
Key type: organization

Path parameters

Name	Description
`conversation_id`	A conversation id from /v1/conversations.

`POST /api/v1/conversations/{conversation_id}/reply`

Post an operator reply into a help-desk conversation.

Scope: helpdesk
Key type: organization

Path parameters

Name	Description
`conversation_id`	A conversation id from /v1/conversations.

Body

Name	Description
`body`	string (required) — the reply text (1-4000 chars).
`mark_resolved`	boolean (optional) — resolve the conversation in the same write.

Reuses the inbox operator-reply mechanism; mirrored into the transcript and delivered to the visitor.

`POST /api/v1/conversations/{conversation_id}/resolve`

Set a help-desk conversation's status to resolved.

Scope: helpdesk
Key type: organization

Path parameters

Name	Description
`conversation_id`	A conversation id from /v1/conversations.

`POST /api/v1/conversations/{conversation_id}/note`

Add an internal operator note to a help-desk conversation (never shown to the customer).

Scope: helpdesk
Key type: organization

Path parameters

Name	Description
`conversation_id`	A conversation id from /v1/conversations.

Body

Name	Description
`body`	string (required) — the note text (1-4000 chars).

`POST /api/v1/capture`

Capture a web page (rendered text + same-site media URLs) into the ingestion review queue.

Scope: ingest
Key type: personal

Body

Name	Description
`hostname`	string (required) — host the capture came from.
`items`	array (required) — captured pages/lessons ({url, title?, page_text?, image_urls?, pdf_urls?, media_urls?, transcript_text?, ...}).
`force`	boolean (optional) — re-capture even if already ingested.
`run_id`	string (optional) — from a prior response; appends a follow-up chunk to the same run.

Returns 202 with {run_id, status, accepted_items}. Every URL is SSRF-validated against the media/CDN host allowlist; the key's owner must hold a contributor+ role.

`GET /api/v1/capture-defaults`

Read your capture-governance defaults + the organization's policy ceiling.

Scope: ingest
Key type: personal

The extension uses this to render only permitted capture choices.

`GET /api/v1/capture/discovery-config`

Read the site-capture discovery tuning (regex sources, scroll/pager bounds, per-site overrides).

Scope: ingest
Key type: personal

Data only: the extension compiles and clamps client-side, with bundled defaults as the offline fallback.

`PUT /api/v1/capture-defaults`

Save your capture-governance defaults (validated against the org ceiling).

Scope: ingest
Key type: personal

Body

Name	Description
`source_access`	object (optional) — default visibility/audience for captures.
`publish_mode`	string (optional) — draft \| live ('live' only stored when the org + your role permit it).

`GET /api/v1/skills`

List the organization's runnable tool-kind skills (platform + custom).

Scope: retrieve
Key type: personal or organization

Returns {skills: [{id, slug, label, description, primitive_kind, risk_tier, parameters_schema}]}.

`POST /api/v1/skills/{skill_id}/run`

Run one read/compose-tier skill with the supplied parameters.

Scope: answer
Key type: personal or organization

Path parameters

Name	Description
`skill_id`	A skill id from GET /v1/skills.

Body

Name	Description
`parameters`	object — shape per the skill's parameters_schema.

write_external/admin skills never execute here — they return {ok: false, status: 'pending_approval'} so the user approves in the app.

`POST /api/v1/drive/step`

Decide the single next browser action for an agentic browser-control (Act) loop.

Scope: answer
Key type: personal or organization

Body

Name	Description
`goal`	string (required) — what the user asked for (1-4000 chars).
`history`	array (optional) — prior steps ({action, result?}).
`observation`	object (required) — current page ({url, title, dom_summary, screenshot?, ...}).
`must_finish`	boolean (optional) — force a final `finish` report from what's gathered.

Stateless: execute the returned action, append it to history, call again.

`GET /api/v1/agents`

List the organization's API-enabled agents (slug, name, description, default flag).

Scope: answer or retrieve
Key type: personal or organization

Feeds a name-based agent picker; agent slugs address /v1/answer and /v1/agents/{agent_id}/answer.

`GET /api/v1/me`

Identity for the presented key: organization (name + slug), key tier, granted scopes.

Scope: any
Key type: personal or organization

Any valid key, no specific scope. Lets a client show 'Connected to ' before writing.

Automation subtree

Event subtree for automation platforms (Zapier/n8n/Make): subscribe to and poll the organization's event stream, stream live events over SSE (/automation/events), query entities, and upsert customers (idempotent — replays are marked with X-Idempotent-Replay: true). Requires an organization key with the 'automation' scope. GET /api/v1/automation/registry is its self-describing catalog.

Start at GET /api/v1/automation/registry.