API

A JSON API under /api/v1/console/. Everything the console's screens do goes through these doors; the ones below are the ones a program most often wants.

Authentication

Mint a personal access token in the console (Settings › Tokens) or with the API, then send it on every call:

curl -s https://console.dev.ductileai.com/api/v1/console/tokens \
  -H "Content-Type: application/json" --cookie "$SESSION" \
  -d '{"name":"ci deploy","ttlDays":90}'
# => { "token": "dpt_…", "expiresAt": "…" }   shown once

curl -s https://console.dev.ductileai.com/api/v1/console/businessProcesses \
  -H "Authorization: Bearer dpt_…"

A token carries its owner's permissions, intersected with an optional scope at minting (one environment, one folder, one process). It cannot mint tokens, step up, or change sign-in settings. GET /api/v1/console/tokens lists yours; DELETE /api/v1/console/tokens/:id revokes one.

Conventions

Requests and answers are JSON; a body needs Content-Type: application/json.
Errors answer { "error": "snake_case_code", "detail": … } with the matching status: 400 invalid body, 401 not signed in, 403 not allowed, 404 not found, 409 a state that refuses the act, 429 rate-limited (with retry-after).
Lists page with ?limit= and a cursor returned as nextCursor.
Every write is audited to your tenant's ledger with the token's owner as the actor.

Business processes

Door	Purpose
`GET /businessProcesses`	List, paged, with summaries.
`POST /businessProcesses`	Create from a definition (the JSON the canvas and the MCP compiler produce).
`GET /businessProcesses/:id`	One process with its definition.
`PUT /businessProcesses/:id`	Replace the definition; validated on the way in.
`DELETE /businessProcesses/:id`	Delete.
`POST /businessProcesses/:id/versions`	Cut a version (what deploys).
`GET /businessProcesses/:id/versions`	The version ledger.
`POST /businessProcesses/:id/preflight`	Validate and check readiness before a deploy: credentials bound, wires typed, gates in place.
`GET /businessProcesses/:id/cell-check`	Which runtime cell (runtime × process type) the process needs and whether the tenant has one.

Drafting

Door	Purpose
`POST /assist/generate`	One-shot: `{ "brief": "…", "model": "default" }` → a validated draft, its plan summary and what is still to fill. `model` is an id from `GET /assist/models`.
`GET /assist/models`	The planner and speech models a person may pick: "Default" plus what your operator offers.
`POST /api/authoring/conversations`	Start a conversation: `{ "goal": "…", "model"?: id }`. Answers the conversation with its checkpoint (approve, revise, answer a question) and, when it has one, the draft.
`POST /api/authoring/conversations/:id/reply`	Answer the checkpoint: `{ "kind": "CONTINUE" \| "REVISE" \| "APPROVE" \| "DENY" \| "ANSWER" \| "CANCEL", "text"?: "…" }`.
`GET /api/authoring/conversations?scope=recent&source=own\|others\|all`	Recent conversations, finished ones too.
`DELETE /api/authoring/conversations/:id`	Stop it; add `?purge=1` to delete your own for good.
`POST /api/authoring/transcribe?model=`	Speech to text: post the audio bytes with their content type.

Runs and deployments

Door	Purpose
`GET /runs`, `GET /runs/:runId`	Runs and one run's record.
`GET /runs/:runId/output`	What a run produced.
`GET /runs/:runId/compute`	What it cost: events by class, duration, the credit line.
`GET /pods`, `POST /pods`	The runtime pods of the tenant, and enrolling one (on-premises installs).
`GET /deployments`, `POST /deployments`	Where a version runs, and placing one.

Connectors, credentials, people

Door	Purpose
`GET /connectors`	The catalogue as your plan entitles it.
`POST /connectors/publish`, `/takedown`, `/fork`	A tenant's own connectors: publish one, withdraw it, fork a platform one.
`GET /connector-credentials`, `POST /connector-credentials`	Connections by name and vendor; the secret is written once and never read back.
`GET /tenant/members`, `POST /tenant/members/invites`	Who is in the tenant and inviting someone; grants per member.
`GET /settings/dapps`	Which vendor groups this tenant may use, and why not when not.

Webhooks and triggers

A deployed process can start from a schedule, an inbound webhook or a vendor event; the console issues the webhook URL and its secret when the trigger is created (GET /triggers, POST /triggers). Inbound requests are verified against that secret and rate-limited per trigger.

The operator's doors (/api/v1/operator/…) are a separate plane with its own sign-in and are not part of the tenant API.