18 · The HTTP reference¶
Every operation the API serves is in this chapter's table, grouped by product as the API reference groups them. Each row opens that operation in the reference, where you can read its request and response in full and try it with your own key. The table reads without JavaScript, prints, and travels in the offline copies of this guide, which the interactive page cannot; the page is the interactive half. Both are generated from one document.
The document¶
The contract is openapi.yaml, OpenAPI 3.1, served byte for byte at
api.stalwart.it/openapi.yaml, with a Portuguese twin at
/openapi.pt.yaml whose prose is translated and whose contract is the same. This guide was built against
the document with this SHA-256:
9ec469bdccaf965e1d7d21182ab1495f890322124c0943fb4b5202ff4ed2916b
It is stamped at the foot of every page too. To confirm that the guide and the reference describe the same contract, compare it with the SHA-256 of the file the API serves.
The URL carries /v1. Adding a field, a mode, a refusal slug or an event type is a compatible change;
removing or retyping anything is /v2.
Every operation¶
Bot builder¶
Plans¶
Read a user's turn into a plan of tool calls. A turn is your user's words, so the plan is made on your own host: by the licensed runtime, or by the router you run in your environment, which serves this route. api.stalwart.it does not.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/plans |
Plan the tool calls for a turn | route |
200, 400, 401, 403, 413, 429, 503 |
Catalogues¶
Register your tools from LangChain tool definitions, an MCP server's tool list or an OpenAPI document. Each registration is a version, linted before it routes, and the one before it can be restored.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/catalogues |
Register a tool catalogue | catalogue |
201, 400, 401, 403, 409, 413, 429, 503 |
GET /v1/catalogues |
List the catalogue's versions | catalogue |
200, 401, 403 |
GET /v1/catalogues/{version} |
Read the catalogue | catalogue |
200, 401, 403, 404 |
POST /v1/catalogues/{version}/restore |
Restore the previous catalogue | catalogue |
201, 401, 403, 404, 429, 503 |
Tool checks¶
Check one tool call against your catalogue, your rulebook and the session's history, and get one answer: allow, confirm or refuse. The check runs on your own host: in the licensed runtime, or through these routes on the router you run in your environment, for a host that cannot load the runtime. api.stalwart.it does not serve them.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/tool-checks |
Check a tool call | tool_check |
200, 400, 401, 403, 413, 429, 503 |
POST /v1/tool-receipts |
Check a call's receipt | tool_check |
200, 400, 401, 403, 413, 429, 503 |
Vocabulary¶
The words the selector reads, per tenant: publish a version, learn new words from feedback, and roll back.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
GET /v1/vocabulary |
Read the vocabulary | mine or packages |
200, 401, 403 |
PUT /v1/vocabulary |
Publish a vocabulary version | mine |
200, 400, 401, 403 |
POST /v1/vocabulary/mine |
Learn new words from feedback | mine |
202, 400, 401, 403, 429 |
GET /v1/vocabulary/mine |
List the miner's runs | mine |
200, 401, 403 |
GET /v1/vocabulary/mine/{run_id} |
Read a learning run | mine |
200, 401, 403, 404 |
DELETE /v1/vocabulary/mine/{run_id} |
Withdraw a learning run | mine |
200, 401, 403, 404 |
POST /v1/vocabulary/revert |
Roll the vocabulary back | mine |
200, 400, 401, 403 |
GET /v1/vocabulary/history |
List the vocabulary's versions | mine or packages |
200, 401, 403 |
Feedback and grammar reports¶
What your users said when the selector got it wrong, and the sentence shapes it could not read.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/feedback |
Send your users' feedback | feedback |
201, 400, 401, 403, 409, 429 |
GET /v1/feedback/export |
Export feedback | feedback or packages |
200, 401, 403 |
GET /v1/grammar-reports/shipped |
List the shapes now read | grammar_report or mine |
200, 401, 403 |
POST /v1/grammar-reports |
Report an unread sentence shape | grammar_report |
201, 400, 401, 403, 409 |
GET /v1/feedback/summary |
Summarise feedback | feedback |
200, 401, 403 |
Rule sheets¶
Your business rules as YAML a person can read aloud, compiled to the rulebook the tool check enforces, linted against your catalogue and registered on it.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/rule-sheets/compile |
Compile a rule sheet | catalogue |
200, 400, 401, 403, 409, 413, 429, 503 |
POST /v1/rule-sheets |
Save a rule sheet | catalogue |
201, 400, 401, 403, 409, 413, 429, 503 |
GET /v1/rule-sheets |
Read the rule sheet | catalogue |
200, 401, 403 |
Replies¶
What a reply may say: the outcome phrasings that replace a sentence misstating what was done, and the reply rules for personal data, wording and offers.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
GET /v1/reply-rules |
Read the reply rules | catalogue |
200, 401, 403 |
PUT /v1/reply-rules |
Save the reply rules | catalogue |
200, 400, 401, 403, 413 |
GET /v1/outcome-phrasings |
Read the outcome phrasings | catalogue |
200, 401, 403 |
PUT /v1/outcome-phrasings |
Save the outcome phrasings | catalogue |
200, 400, 401, 403, 413 |
Accuracy¶
How well your agents read what people ask, from the first day: an evaluation set written from your catalogue, beside your users' thumbs.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
GET /v1/accuracy |
Read the accuracy | catalogue |
200, 401, 403 |
Guardrail bug hunter¶
Hunt a policy¶
Submit a job with mode: hunt and the policy -- Colang 1 or Colang 2 -- or an agent graph and its catalogue, and read the findings from the finished job. The examples Guardrail bug hunter: hunt a Colang 1 policy for bugs, Guardrail bug hunter: hunt a Colang 2 policy for bugs and Guardrail bug hunter: hunt an agent graph are complete requests, each policy inline.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/solves |
Submit a job | the mode's own grant | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Projects and scans¶
A project keeps a policy's scans together, so each scan is compared with the last and a quality profile can gate it.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/projects |
Create a project | hunt |
201, 400, 401, 403, 409 |
GET /v1/projects |
List projects | hunt |
200, 401, 403 |
GET /v1/projects/{id} |
Read a project | hunt |
200, 401, 403, 404 |
PUT /v1/projects/{id}/profile |
Set a project's quality gate | hunt_details |
200, 400, 401, 403, 404, 409 |
POST /v1/projects/{id}/scans |
Scan a project | hunt |
200, 202, 400, 401, 403, 404, 409, 413, 429 |
GET /v1/projects/{id}/scans |
List a project's scans | hunt |
200, 401, 403, 404 |
GET /v1/projects/{id}/scans/{scan_id} |
Read a scan | hunt |
200, 401, 403, 404 |
Findings¶
Every finding a project's scans have reported, with its history, your decision about it, and what was tried against it in your environment.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/hunt-attempts |
Record an attempt on a finding | hunt |
201, 400, 401, 403, 409 |
GET /v1/hunt-attempts |
List the attempts on findings | hunt |
200, 401, 403 |
GET /v1/projects/{id}/findings |
List findings | hunt |
200, 400, 401, 403, 404 |
GET /v1/projects/{id}/findings/{fingerprint} |
Read a finding | hunt_details |
200, 401, 403, 404 |
PATCH /v1/projects/{id}/findings/{fingerprint} |
Triage a finding | hunt_details |
200, 400, 401, 403, 404, 409 |
Guardrail verification¶
Verify a guardrail¶
Submit a job with mode: guardrail for one action and its context, or batch for a table of them, over a Colang 1 or Colang 2 policy. The two Guardrail verification: can this action fire without this context? examples are complete requests, one in each dialect; the request body's selector lists every verification mode.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/solves |
Submit a job | the mode's own grant | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Verify an agent graph¶
Submit a job with mode: graph, an exported agent graph and the catalogue its tools are classified by: every tool reached without its check, every write without its confirmation, every order rule, every privileged tool under taint and every saga rule is decided, and each one broken comes back with a path through the graph. The example Guardrail verification: verify an agent graph before it is deployed is a complete request.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/solves |
Submit a job | the mode's own grant | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Guardrail writing¶
Write a guardrail¶
Submit a guardrail job with a generation object in place of a policy: a rule in prose, your provider, model and key. The draft is written in Colang 2 unless you ask for Colang 1, verified like any other policy and repaired where it is wrong. Your key and prompt are never stored. The two Guardrail writing examples are complete requests: one drafts in Colang 2, the other asks for Colang 1 with generation.dialect.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/solves |
Submit a job | the mode's own grant | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Random forest verification¶
Verify a forest¶
Upload the model and a property table, then submit a job with mode: forest, or forest_enumeration to search around real records. The example Random forest verification is a complete request.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/solves |
Submit a job | the mode's own grant | 200, 202, 400, 401, 403, 409, 413, 429, 503 |
Jobs and files¶
Jobs¶
Every product above that runs as a job is read, streamed and cancelled here.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
GET /v1/solves |
List jobs | any valid key | 200, 401 |
GET /v1/solves/{id} |
Read a job | any valid key | 200, 400, 401, 404, 413 |
DELETE /v1/solves/{id} |
Cancel a job | any valid key | 200, 401, 404 |
GET /v1/solves/{id}/events |
Stream a job's progress | any valid key | 200, 401, 404, 429 |
GET /v1/solves/{job_id}/artifacts |
List a job's artefacts | any valid key | 200, 401, 404 |
Uploads and artefacts¶
Stage a file too large to send inline, and download what a job produced.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/uploads |
Open an upload | any valid key | 201, 400, 401, 413 |
PUT /v1/uploads/{upload_id}/content |
Send an upload's bytes | any valid key | 200, 400, 401, 413 |
GET /v1/artifacts/{id} |
Download an artefact | any valid key | 200, 206, 401, 403, 404, 410 |
GET /v1/artifacts/{id}/access |
Who has read an artefact | any valid key | 200, 401, 404 |
Account¶
Capabilities and access¶
What this key can do: the modes, profiles and limits, and access to the package feed.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
GET /v1/packages/entitlement |
Check package feed access | any valid key | 200, 401, 403 |
GET /v1/profiles |
List profiles | any valid key | 200 |
GET /v1/capabilities |
What this key can do | any valid key | 200 |
GET /v1/account |
What this key is held to | any valid key | 200, 401 |
GET /v1/version |
What is running here | any valid key | 200, 401 |
Local runtime¶
The licensed runtime on your machine calls these: it activates with your key, renews its lease in the background, downloads its bundles and reports its counts. A turn never waits on them.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
GET /v1/licences |
Read the licence | runtime |
200, 401, 403 |
GET /v1/licences/keys |
Read the licence keys | none, public | 200, 503 |
POST /v1/licences/activate |
Activate a licence | runtime |
201, 400, 401, 403, 409, 503 |
POST /v1/licences/refresh |
Renew a lease | runtime |
200, 400, 401, 403, 404, 409, 503 |
POST /v1/licences/release |
Release an installation | runtime |
200, 400, 401, 403, 404 |
POST /v1/licences/offline |
Activate an offline installation | runtime |
201, 400, 401, 403, 409, 503 |
GET /v1/bundles/{kind} |
Download a bundle | runtime |
200, 400, 401, 403, 409, 503 |
POST /v1/usage-reports |
Report usage | runtime |
201, 400, 401, 403, 404, 503 |
Sign-up and sessions¶
Open an account with an emailed link or with Google, show a request is a person's, and check or end the session the console signs in with.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
POST /v1/signup |
Sign up by email | none, public | 202, 400, 409, 429, 503 |
GET /v1/signup/challenge |
Get a sign-up challenge | none, public | 200 |
GET /v1/signup/google |
Sign up with Google | none, public | 303, 503 |
GET /v1/signup/google/callback |
Return from Google | none, public | 303, 403, 503 |
GET /v1/session |
Read the session | none, public | 200, 401 |
POST /v1/session/end |
Sign out everywhere | none, public | 204, 400, 401 |
Billing¶
The plans' prices as the website shows them, and the webhooks Stripe and the mail provider post to. A webhook is signed, recorded once, and never called by a client.
| Operation | What it does | Grant it needs | Statuses |
|---|---|---|---|
GET /v1/mail/events |
Check the mail provider webhook | none, public | 200 |
HEAD /v1/mail/events |
Check the mail webhook, headers only | none, public | 200 |
POST /v1/mail/events |
Mail provider webhook | none, public | 200, 400, 401 |
GET /v1/pricing |
Read the prices | none, public | 200 |
POST /v1/billing/webhooks/stripe |
Stripe webhook | none, public | 200, 400, 401, 503 |
POST /v1/solves is under every product that runs as a job, and appears once under each of them. Its grant
is the grant of the mode the request names (chapter 40).
The reference page, and your key¶
The reference at api.stalwart.it is public, and reading it needs no key. Its Test Request panel sends real requests, with a key you paste. Here is what it does with that key, stated as the page's own policy and configuration decide it:
- A request from the panel is a real call: authenticated, rate-limited and metered against your key's quota like any other. It is never a sandbox, never a test mode, and not free.
- The key is sent to the host that served the page, and to nothing else. The panel's one server is the
page's own origin, and the page's Content-Security-Policy admits requests to that origin only: scripts
from it only, with no inline script; styles from it, plus the inline styles the renderer sets; fonts and
images from it, plus
data:addresses. - The page keeps no key in your browser's storage, loads nothing from a third party, and sends no telemetry. It has no AI assistant, and no link to a hosted client.
A reader who would rather not paste a production key mints one for the purpose on the console's Keys page, and revokes it afterwards (chapter 5). A server edited in the panel to point at another host is refused by the page's policy, and the panel says nothing about why (chapter 15).
This table is the accessible route to the same contract. The interactive page is the renderer's, not ours to make accessible; this chapter is held to the same accessibility checks as every other page of the guide.
The limits¶
- The links open the live reference, and need the network. In an offline copy of this guide the table and the digest are complete; the links are not.
- A request sent from the reference page is a real, metered call.