Quickstart

Decosa is applied AI on open models: tools that each do one real job (check a brief, run the visit, fill a form), and the open models under them, by API in the OpenAI format. Every hosted model call comes back with a signed receipt you can check. From a key to a verified first call takes five steps.

1. Get a key

Create one at API keys. It is shown once: store it as DECOSA_API_KEY. A new key has a free budget of $0.02 of hosted usage a day at list price; a key with Decosa credits has no daily cap.

export DECOSA_API_KEY=dk_...

2. Make a call

curl -s -i https://api.decosa.ai/v1/chat/completions \
  -H "Authorization: Bearer $DECOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.8-27b", "messages": [{"role": "user", "content": "Hello"}]}'

It is the OpenAI chat format, so any OpenAI SDK works with base_url set to https://api.decosa.ai/v1 and your key as the API key. Over the budget or at zero credits the API answers HTTP 402 with a link to buy more; over a rate limit, 429 with Retry-After.

3. Read the receipt id

The response headers carry the receipt id: x-decosa-receipt: <id>. The receipt holds the model and hashes of what went in and came out, signed with Decosa's Ed25519 key. It holds hashes, never your text.

4. Verify the receipt

curl -s https://api.decosa.ai/receipts/<id>

returns the signed record and the checks it passed. Or open /receipts/<id> on this site, which re-checks the signature in your browser. How receipts work, and what they don't prove.

5. Next

• Run a whole tool: every tool page has Use it from your code, with its API calls and a prompt for a coding agent.
• Building blocks: the capabilities the tools are made from, each with its route, on Developers.
• The Decosa agent and the machine-readable index for coding agents: For AI agents.
• Run it on your own hardware instead: Self-hosting.

Check the service

curl -s https://api.decosa.ai/healthz

"llm": true means the hosted language model is answering. While it says false, chat calls may fail with 502 or 503 and tool pages show recorded runs; the status line at the top of this page reads the same check live.

Demo sessions (no key)

The tool pages' samples use short demo sessions instead of a key. They are small, keep no account, and must never get patient or client data; for real data, self-host.

A demo session

curl -s -X POST https://api.decosa.ai/demo/session \
  -H 'Content-Type: application/json' -d '{"vertical":"clinical"}'
# {"token": "...", "expires_at": 1790000000, "budget": {"seconds_audio": 300, "llm_tokens": 20000}}

Vertical ids: clinical, sales, code, studio, field, translate. Sessions are limited to 20 per network an hour and 60 an hour across the whole hosted demo, and live audio sessions are capped globally (GET /healthz shows the current limits under demo_sessions). Over a limit the API returns HTTP 429 with Retry-After.

Run a sample without a microphone

POST /demo/replay runs a canned audio script through the real pipeline and streams the same events as a live session, over server-sent events:

curl -N -X POST https://api.decosa.ai/demo/replay \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"vertical":"clinical","script_id":"clinical-back-pain"}'

GET /demo/scripts lists the script ids. No token is needed for it.

Stream live audio

Open WS /ws/live?vertical=<id>&token=<token>, send 16 kHz mono PCM16 little-endian frames of about 100 ms, and send {"type":"stop"} when you are done. The server answers with ready, transcript, lane, receipt, budget, error and done events. See the API reference for the shapes.

Let a coding agent do it

Every tool page has a Use it from your code section with two copy-paste prompts for Claude Code, Codex or similar: one wires your project to the hosted API, the other sets the tool up on your own GPU.