API reference

Generated from the API's OpenAPI document — every endpoint, grouped by resource.

Agents

GET/v1/agents

List agent profiles

Responses

Status	Description
`200`	Agent profiles
`401`	Error

POST/v1/agents

Create an agent profile (profile + version 1)

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`401`	Error

GET/v1/agents/{id}

Get an agent profile, including its current version config

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Agent profile
`404`	Error

GET/v1/agents/{id}/evals

List this agent's eval run batches, newest first

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Eval runs
`404`	Error

POST/v1/agents/{id}/evals

Run every eval case for this agent through the kernel (as an evals.run job)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Queued
`404`	Error
`409`	Error

GET/v1/agents/{id}/evals/{runId}

Get one eval run batch's per-case detail

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`runId`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Eval run
`404`	Error

GET/v1/agents/{id}/proposals

List this agent's improvement proposals, newest first

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Proposals
`404`	Error

POST/v1/agents/{id}/proposals

Manually create an improvement proposal (proposedConfig + rationale)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`404`	Error
`409`	Error

POST/v1/agents/{id}/proposals/{pid}/accept

Accept a proposal — creates a new immutable version (base ⊕ diff) and makes it current

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`pid`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Accepted
`404`	Error
`409`	Error

POST/v1/agents/{id}/proposals/{pid}/reject

Reject a proposal

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`pid`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Rejected
`404`	Error
`409`	Error

POST/v1/agents/{id}/proposals/suggest

Enqueue improvements.suggest on demand, from the agent's most recent failing eval cases

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`202`	Queued
`404`	Error
`409`	Error

GET/v1/agents/{id}/versions

List an agent profile's versions, newest first

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Versions
`404`	Error

POST/v1/agents/{id}/versions

Create a new immutable profile version (becomes current)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`404`	Error

GET/v1/agents/{id}/versions/{a}/diff/{b}

JSON diff between two profile versions' configs, per docs/specs/phase-3.md §3.5

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`a`	path	integer	Yes
`b`	path	integer	Yes

Responses

Status	Description
`200`	Diff
`404`	Error

GET/v1/agents/{id}/versions/{version}

Get one specific agent profile version

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`version`	path	integer	Yes

Responses

Status	Description
`200`	Agent profile version
`404`	Error

POST/v1/agents/{id}/versions/{version}/activate

Make an already-existing version current again (rollback/forward), per docs/specs/phase-3.md §3.5

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`version`	path	integer	Yes

Responses

Status	Description
`200`	Activated
`404`	Error

Api Keys

GET/v1/api-keys

List API keys

Responses

Status	Description
`200`	API keys

POST/v1/api-keys

Create an API key (plaintext key returned once)

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created

PATCH/v1/api-keys/{id}

Set or clear an API key's monthly spend cap

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Updated
`400`	Error
`404`	Error

DELETE/v1/api-keys/{id}

Revoke an API key

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Revoked
`404`	Error

App Templates

GET/v1/app-templates

List the static published-app template gallery (drop_and_extract, quote_request), per docs/plan/phase-6-ux-checklist.md §6.6

Responses

Status	Description
`200`	App templates
`401`	Error

Apps

GET/v1/apps

List published apps

Responses

Status	Description
`200`	Published apps
`401`	Error

POST/v1/apps

Create a published app from an agent profile

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`404`	Error
`409`	Error

GET/v1/apps/{id}

Get a published app

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Published app
`404`	Error

PATCH/v1/apps/{id}

Update a published app's template/slug/theme/access/caps

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Updated
`400`	Error
`404`	Error
`409`	Error

DELETE/v1/apps/{id}

Delete a published app

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error

POST/v1/apps/{id}/domain

Set a custom domain, returning the TXT record to publish for verification

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Domain set
`400`	Error
`404`	Error
`409`	Error

POST/v1/apps/{id}/domain/verify

Verify the custom domain's TXT record

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Verified
`404`	Error
`409`	Error
`422`	Error

POST/v1/apps/{id}/pause

Pause a live app (status -> paused)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Paused
`404`	Error

POST/v1/apps/{id}/publish

Publish a draft/paused app (status -> live)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Published
`404`	Error

GET/v1/apps/{id}/usage

Today's and recent daily usage against this app's caps

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Usage
`404`	Error

GET/v1/apps/slug-availability

Check whether a slug is free to use for a new/renamed published app (global, not workspace-scoped)

Parameters

Name	In	Type	Required
`slug`	query	string	Yes

Responses

Status	Description
`200`	Availability
`401`	Error

Builder

POST/v1/builder/sessions

Start a conversational agent-builder session, per docs/plan/phase-6-ux-checklist.md §6.5

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`401`	Error

GET/v1/builder/sessions/{id}

Get a builder session, including its transcript and current draft config

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Builder session
`404`	Error

POST/v1/builder/sessions/{id}/cancel

Abandon a builder session without creating an agent (idempotent; 409 if already completed)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Builder session
`404`	Error
`409`	Error

POST/v1/builder/sessions/{id}/create

Validate the session's draft config and create the agent profile + version 1 from it

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`201`	Created
`400`	Error
`404`	Error
`409`	Error

POST/v1/builder/sessions/{id}/messages

Send a message in a builder session; the control model replies and may update the draft config

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Builder session
`400`	Error
`404`	Error
`409`	Error

Calendar

GET/v1/calendar

The built-in booking calendar's settings, plus appointments within an optional [from, to) range

Parameters

Name	In	Type	Required
`from`	query	string (date)	No
`to`	query	string (date)	No

Responses

Status	Description
`200`	Calendar
`401`	Error

PATCH/v1/calendar

Update the built-in booking calendar's timezone and/or opening hours

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Updated
`400`	Error
`401`	Error
`403`	Error

Connections

GET/v1/connections

List save-output delivery connections (email/webhook/s3/gdrive/sharepoint)

Responses

Status	Description
`200`	Connections

POST/v1/connections

Create a connection — secret config fields are sealed at rest, never returned

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`501`	Error

DELETE/v1/connections/{id}

Delete a connection

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error

POST/v1/connections/{id}/test

Non-destructive connectivity/credential check for one connection

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Test result
`404`	Error

Console

GET/v1/console/auth/me

Current session user + workspaces

Responses

Status	Description
`200`	Current user
`401`	Error

POST/v1/console/auth/password/forgot

Email a password-reset token, if the address has an account (enumeration-safe)

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`204`	Sent (or a no-op)
`400`	Error
`429`	Error

POST/v1/console/auth/password/reset

Redeem a password-reset token, set a new password, and revoke every session

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`204`	Reset
`400`	Error
`429`	Error

POST/v1/console/auth/sign-out

End the current session

Responses

Status	Description
`204`	Signed out

POST/v1/console/auth/sign-up

Create an account (user + organization + workspace) and start a session

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`409`	Error

POST/v1/console/auth/verify

Redeem an email-verification token

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`204`	Verified
`400`	Error
`429`	Error

POST/v1/console/auth/verify/request

Email the signed-in user a verification token

Responses

Status	Description
`204`	Sent
`401`	Error
`429`	Error

GET/v1/console/billing

Balance, plan, entitlements, credit packs, and recent ledger rows

Responses

Status	Description
`200`	Billing
`401`	Error

POST/v1/console/billing/checkout

Create a Stripe Checkout session for a credit pack (owner only)

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Checkout session
`400`	Error
`403`	Error
`503`	Error

POST/v1/console/invitations/accept

Redeem a workspace invitation token for the signed-in user, granting membership

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Membership granted
`400`	Error
`401`	Error
`403`	Error
`409`	Error
`429`	Error

GET/v1/console/members

List the workspace's organisation's members and roles

Responses

Status	Description
`200`	Members
`401`	Error

DELETE/v1/console/members/{userId}

Remove a member from this workspace's organisation (owner/admin only)

Parameters

Name	In	Type	Required
`userId`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Removed
`403`	Error
`404`	Error
`409`	Error

POST/v1/console/members/invite

Create a pending invitation (by email) into this workspace's organisation and email the invitee a token (owner/admin only) — see POST /v1/console/invitations/accept

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Invitation created
`400`	Error
`403`	Error
`404`	Error
`409`	Error

GET/v1/console/outbox

Dev-only: lists this workspace's outbound_messages (what DevEmailSender "sent") — 404s outside development

Responses

Status	Description
`200`	Outbox
`401`	Error
`404`	Error

GET/v1/console/request-logs

Paginated, filterable request log for this workspace

Parameters

Name	In	Type	Required
`from`	query	string (date-time)	No
`to`	query	string (date-time)	No
`path`	query	string	No
`status`	query	integer	No
`cursor`	query	string	No
`limit`	query	integer	No

Responses

Status	Description
`200`	Request logs
`401`	Error

GET/v1/console/workspace

Get the current workspace's name and settings (allowed data regions, retention days, brand colour)

Responses

Status	Description
`200`	Workspace
`401`	Error
`404`	Error

PATCH/v1/console/workspace

Update workspace name / allowed data regions / retention days / brand colour

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Updated
`400`	Error
`401`	Error
`403`	Error
`404`	Error

Files

POST/v1/files

Upload a file (multipart or raw body + X-Filename)

Request body

Content type	Schema
`multipart/form-data`	object
`application/octet-stream`	string (binary)

Responses

Status	Description
`201`	Stored
`413`	Error
`415`	Error

Finance

GET/v1/finance/categories

This workspace's effective finance category taxonomy (platform defaults, workspace overrides win by key)

Responses

Status	Description
`200`	Categories
`401`	Error

GET/v1/finance/export

Streams bank transactions as CSV over an optional [from, to] range (400 on a malformed from/to) and the same category/anomaly/uncategorised/q filters GET /v1/finance/transactions supports — ?format=journal (default) or ?format=datev (behind AFB_FEATURE_DATEV, 404 otherwise)

Parameters

Name	In	Type	Required
`from`	query	string (date)	No
`to`	query	string (date)	No
`category`	query	string	No
`anomaly`	query	enum(true \| false)	No
`uncategorised`	query	enum(true \| false)	No
`q`	query	string	No
`format`	query	enum(journal \| datev)	No

Responses

Status	Description
`200`	CSV
`400`	Error
`404`	Error

GET/v1/finance/imports

List this workspace's bank CSV imports, newest first

Responses

Status	Description
`200`	Bank imports
`401`	Error

POST/v1/finance/imports

Upload a bank CSV export and create a finance/categorisation run (202, Idempotency-Key supported)

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	string	No
`accountLabel`	query	string	No

Request body

Content type	Schema
`multipart/form-data`	object
`text/csv`	string
`application/octet-stream`	string (binary)

Responses

Status	Description
`202`	Queued
`400`	Error
`402`	Error
`413`	Error

POST/v1/finance/reconciliation

Create a finance/reconciliation run matching open invoices against transactions over {from, to}

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Queued
`400`	Error
`402`	Error
`403`	Error

POST/v1/finance/reports

Create a finance/cashflow-report run over {from, to} (optional template)

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Queued
`400`	Error
`402`	Error
`403`	Error

GET/v1/finance/rules

List this workspace's transaction_rules (created via PATCH /v1/finance/transactions/:id's own makeRule)

Responses

Status	Description
`200`	Rules
`401`	Error

DELETE/v1/finance/rules/{id}

Delete one of this workspace's transaction_rules

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`401`	Error
`403`	Error
`404`	Error

GET/v1/finance/summary

By-month and by-category totals, plus anomaly/uncategorised counts, over an optional [from, to] range

Parameters

Name	In	Type	Required
`from`	query	string (date)	No
`to`	query	string (date)	No

Responses

Status	Description
`200`	Summary
`401`	Error

GET/v1/finance/transactions

List/filter this workspace's imported bank transactions (cursor-paginated)

Parameters

Name	In	Type	Required
`from`	query	string (date)	No
`to`	query	string (date)	No
`category`	query	string	No
`anomaly`	query	enum(true \| false)	No
`uncategorised`	query	enum(true \| false)	No
`q`	query	string	No
`cursor`	query	string	No
`limit`	query	integer	No

Responses

Status	Description
`200`	Transactions
`401`	Error

PATCH/v1/finance/transactions/{id}

Correct one transaction's category (source becomes human), optionally creating a categorisation rule

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Updated
`400`	Error
`403`	Error
`404`	Error

Health

GET/v1/health

Health check

Responses

Status	Description
`200`	OK

Knowledge

GET/v1/knowledge

List this workspace's knowledge documents

Responses

Status	Description
`200`	Knowledge documents

POST/v1/knowledge

Upload a knowledge document (txt/csv/md/pdf); indexed asynchronously via a knowledge.index job

Request body

Content type	Schema
`multipart/form-data`	object
`application/octet-stream`	string (binary)

Responses

Status	Description
`201`	Stored
`413`	Error
`415`	Error

DELETE/v1/knowledge/{id}

Delete a knowledge document (and its indexed chunks)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error

POST/v1/knowledge/search

Search this workspace's indexed knowledge chunks

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Search results
`400`	Error

Misc

GET/docs

HTML API reference viewer

Responses

Status	Description
`200`	HTML

Models

GET/v1/models

List the model catalogue, filtered by the workspace's allowed data regions

Responses

Status	Description
`200`	Models
`401`	Error

Openapi.json

GET/v1/openapi.json

This OpenAPI document

Responses

Status	Description
`200`	OpenAPI document

Phone

GET/v1/phone/agents

List phone agents

Responses

Status	Description
`200`	Phone agents
`401`	Error

POST/v1/phone/agents

Create a phone agent from a phone preset — compiles and pushes it to the configured VoiceProvider

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`401`	Error
`403`	Error

GET/v1/phone/agents/{id}

Get a phone agent, including its current version config

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Phone agent
`404`	Error

PATCH/v1/phone/agents/{id}

Create a new profile version and recompile + push the update to the VoiceProvider

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Updated
`400`	Error
`404`	Error

DELETE/v1/phone/agents/{id}

Delete a phone agent from the VoiceProvider and this workspace

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error

POST/v1/phone/agents/{id}/rotate-secrets

Rotates this phone agent's tool + webhook secrets, recompiles, and pushes the update to the VoiceProvider (the response never echoes the new secret values)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Rotated
`401`	Error
`403`	Error
`404`	Error

GET/v1/phone/calls

List calls (paginated), filterable by agentId/direction/status

Parameters

Name	In	Type	Required
`agentId`	query	string	No
`direction`	query	enum(inbound \| outbound)	No
`status`	query	enum(live \| completed \| failed)	No
`cursor`	query	string	No
`limit`	query	integer	No

Responses

Status	Description
`200`	Calls
`401`	Error

GET/v1/phone/calls/{id}

Get a call: transcript, summary, collected data, actions, audio link, run id

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Call
`404`	Error

POST/v1/phone/calls/outbound

Start an outbound call, or (for a requiresApproval preset) create a needs_approval run — approve via the existing POST /v1/runs/{id}/approve

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Call started
`202`	Needs approval
`400`	Error
`404`	Error

GET/v1/phone/numbers

List imported Twilio phone numbers

Responses

Status	Description
`200`	Phone numbers
`401`	Error

POST/v1/phone/numbers

Import a Twilio phone number (from a sealed "twilio" connection) and optionally assign it to an agent

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`404`	Error

DELETE/v1/phone/numbers/{id}

Delete an imported phone number

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error

POST/v1/phone/simulate

Dev-only: simulates an inbound call end-to-end via FakeVoiceProvider (404 outside development)

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Simulated
`400`	Error
`404`	Error
`409`	Error

POST/v1/phone/tools/{tool}

Live, mid-call server-tool endpoint called by the voice provider (bearer tool secret)

Parameters

Name	In	Type	Required
`tool`	path	string	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Tool result
`401`	Error
`404`	Error

POST/v1/phone/webhooks/elevenlabs

Post-call webhook (HMAC-signed) — completes the call and enqueues phone.postcall

Parameters

Name	In	Type	Required
`ElevenLabs-Signature`	header	string	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Received
`401`	Error
`404`	Error

Presets

GET/v1/presets

List presets available from the registry

Responses

Status	Description
`200`	Presets

Price Lists

GET/v1/price-lists

List this workspace's price lists

Responses

Status	Description
`200`	Price lists

POST/v1/price-lists

Import a price list from CSV (columns sku,description,unit,unit_price,category,labor_minutes); all-or-nothing with a row-level validation report

Parameters

Name	In	Type	Required
`name`	query	string	No
`currency`	query	string	No

Request body

Content type	Schema
`multipart/form-data`	object
`text/csv`	string
`application/octet-stream`	string (binary)

Responses

Status	Description
`201`	Imported
`400`	Error
`413`	Error

DELETE/v1/price-lists/{id}

Delete a price list (cascades its items)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error

GET/v1/price-lists/{id}/items

Search a price list's items by a simple token index

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`q`	query	string	No
`limit`	query	integer	No

Responses

Status	Description
`200`	Price list items
`404`	Error

Pricing Rules

GET/v1/pricing-rules

Get the effective pricing rules (a profile's own override, else the workspace default)

Parameters

Name	In	Type	Required
`profileId`	query	string (uuid)	No

Responses

Status	Description
`200`	Pricing rules
`404`	Error

PUT/v1/pricing-rules

Replace the workspace default pricing rules, or a per-profile override when ?profileId= is given

Parameters

Name	In	Type	Required
`profileId`	query	string (uuid)	No

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Pricing rules
`400`	Error

Projects

GET/v1/projects

List projects in the workspace, each with its member count

Responses

Status	Description
`200`	Projects
`401`	Error

POST/v1/projects

Create a project (name + optional monthly spend cap)

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error
`401`	Error

GET/v1/projects/{id}

Get one project

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Project
`404`	Error

PATCH/v1/projects/{id}

Update a project's name and/or spend cap

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Updated
`400`	Error
`404`	Error

DELETE/v1/projects/{id}

Delete a project (refuses the default project or one that still owns rows)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error
`409`	Error

GET/v1/projects/{id}/members

List a project's members

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Members
`404`	Error

POST/v1/projects/{id}/members

Add a member to a project (or update their role)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Added
`400`	Error
`404`	Error

DELETE/v1/projects/{id}/members/{userId}

Remove a member from a project

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`userId`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Removed
`404`	Error

Public

GET/v1/public/apps/{slug}

Public app metadata: name, theme, template, access mode, locale, inputSpec, owner, caps, settings (e.g. quote_request's showPricesToEndUser), dataInfo

Parameters

Name	In	Type	Required
`slug`	path	string	Yes

Responses

Status	Description
`200`	Public app
`404`	Error
`429`	Error

POST/v1/public/apps/{slug}/files

Upload a file for a public-app run (requires an app session)

Parameters

Name	In	Type	Required
`slug`	path	string	Yes

Request body

Content type	Schema
`multipart/form-data`	object
`application/octet-stream`	string (binary)

Responses

Status	Description
`201`	Stored
`401`	Error
`404`	Error
`413`	Error
`415`	Error
`422`	Error
`429`	Error

GET/v1/public/apps/{slug}/logo

Stream the app's branding logo, if one was uploaded

Parameters

Name	In	Type	Required
`slug`	path	string	Yes

Responses

Status	Description
`200`	Logo image
`404`	Error
`429`	Error

POST/v1/public/apps/{slug}/runs

Create a run in the app owner's workspace (requires an app session). For quote_request apps, input.fields.customer.{name,email} are required and validated, and at least one file (the drawing).

Parameters

Name	In	Type	Required
`slug`	path	string	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Queued
`400`	Error
`401`	Error
`404`	Error
`429`	Error
`503`	Error

GET/v1/public/apps/{slug}/runs/{id}

Get a public-app run (only visible to the app session that created it). For quote_request apps, returns a reduced shape: status, stage (preparing|awaiting_approval|sent|failed), sentTo (masked email), and quote only when the app's settings.showPricesToEndUser is on.

Parameters

Name	In	Type	Required
`slug`	path	string	Yes
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Run
`401`	Error
`404`	Error
`429`	Error

GET/v1/public/apps/{slug}/runs/{id}/events

Live public-app run events (SSE) — same semantics as the workspace-scoped run events endpoint

Parameters

Name	In	Type	Required
`slug`	path	string	Yes
`id`	path	string (uuid)	Yes
`Last-Event-ID`	header	string	No

Responses

Status	Description
`200`	text/event-stream
`401`	Error
`404`	Error
`429`	Error

GET/v1/public/apps/{slug}/runs/{id}/output

Get a public-app run's output (JSON, or CSV via ?format=csv)

Parameters

Name	In	Type	Required
`slug`	path	string	Yes
`id`	path	string (uuid)	Yes
`format`	query	enum(csv)	No

Responses

Status	Description
`200`	Output
`401`	Error
`404`	Error
`409`	Error
`429`	Error

POST/v1/public/apps/{slug}/session

Start a public-app session (public/link/password immediately; magic_link emails a token)

Parameters

Name	In	Type	Required
`slug`	path	string	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Session
`202`	Magic link sent
`400`	Error
`401`	Error
`404`	Error
`429`	Error

POST/v1/public/apps/{slug}/session/verify

Redeem a magic-link token, starting a session

Parameters

Name	In	Type	Required
`slug`	path	string	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Session
`400`	Error
`401`	Error
`404`	Error
`429`	Error

GET/v1/public/apps/by-host

Resolve a verified custom domain's Host header to its app's slug

Parameters

Name	In	Type	Required
`host`	query	string	Yes

Responses

Status	Description
`200`	Slug
`404`	Error
`429`	Error

Runs

GET/v1/runs

List runs (paginated)

Parameters

Name	In	Type	Required
`cursor`	query	string	No
`limit`	query	integer	No
`status`	query	string	No
`agentId`	query	string	No

Responses

Status	Description
`200`	Runs

POST/v1/runs

Create (queue) a run

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	string	No

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Queued
`400`	Error
`402`	Error

GET/v1/runs/{id}

Get a run

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Run
`404`	Error

POST/v1/runs/{id}/approve

Approve or reject a needs_approval run and resume it

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Resuming
`404`	Error
`409`	Error

GET/v1/runs/{id}/artifacts/{artifactId}

Download a run artifact

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`artifactId`	path	string (uuid)	Yes

Responses

Status	Description
`200`	File bytes
`404`	Error

POST/v1/runs/{id}/cancel

Cancel a queued/paused run

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`200`	Cancelled
`404`	Error
`409`	Error

GET/v1/runs/{id}/events

Live run events (SSE): replays stored events (from Last-Event-ID), then streams live; heartbeats; ends on terminal status

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`Last-Event-ID`	header	string	No

Responses

Status	Description
`200`	text/event-stream
`404`	Error

POST/v1/runs/{id}/feedback

Submit feedback on a run

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`404`	Error

POST/v1/runs/{id}/input

Answer a needs_input run and resume it

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Resuming
`404`	Error
`409`	Error

GET/v1/runs/{id}/output

Get a run's final output (JSON, or CSV via ?format=csv)

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`format`	query	enum(csv)	No

Responses

Status	Description
`200`	Output
`404`	Error
`409`	Error

POST/v1/runs/{id}/review

Accept or reject a needs_review run and resume it

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`202`	Resuming
`404`	Error
`409`	Error

GET/v1/runs/{id}/steps

Get a run's ordered steps

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes
`include`	query	enum(io)	No

Responses

Status	Description
`200`	Steps
`404`	Error

Search

GET/v1/search

Global search across agents, runs, phone calls, finance transactions, and static console pages, per docs/plan/phase-6-ux-checklist.md §6.7

Parameters

Name	In	Type	Required
`q`	query	string	No

Responses

Status	Description
`200`	Search results
`401`	Error
`429`	Error

Stripe

POST/v1/stripe/webhook

Stripe webhook receiver (signature-verified)

Parameters

Name	In	Type	Required
`Stripe-Signature`	header	string	Yes

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`200`	Handled
`400`	Error
`503`	Error

Tools

GET/v1/tools

List the tool catalogue (name, description, safety) an agent's config may enable, per docs/plan/16 §1

Responses

Status	Description
`200`	Tools
`401`	Error

Usage

GET/v1/usage

Usage totals and current balance

Parameters

Name	In	Type	Required
`from`	query	string (date-time)	No
`to`	query	string (date-time)	No

Responses

Status	Description
`200`	Usage

Webhooks

GET/v1/webhooks

List webhook subscriptions

Responses

Status	Description
`200`	Webhooks

POST/v1/webhooks

Create a webhook subscription

Request body

Content type	Schema
`application/json`	object

Responses

Status	Description
`201`	Created
`400`	Error

DELETE/v1/webhooks/{id}

Delete a webhook subscription

Parameters

Name	In	Type	Required
`id`	path	string (uuid)	Yes

Responses

Status	Description
`204`	Deleted
`404`	Error