1. Create a key
Sign in, open Developers, and create a key. You choose:
| Choice | Options | Notes |
|---|---|---|
| Mode | sandbox · live | Sandbox keys (cdk_test_…) simulate every call for free and only ever see simulated matters. Live keys (cdk_live_…) open real matters. |
| Kind | personal · office | A personal key acts as you. An office key acts as the office's designated user and is created by that person; it is the key for the firm's systems. |
| Scopes | matters:read matters:write search inquire documents usage:read | Tick what the integration needs. A key can also be limited to chosen matters; such a key cannot open new ones. |
| Expiry | 90 days (personal live) · none (office, sandbox) | Or set your own, up to ten years. A revoked key stops at once. |
The secret is shown one time, on creation. Store it in your secret manager; the page keeps only the key's id and last four characters.
2. Authenticate
Send the key as a bearer token, or as HTTP Basic with the key's id (cdk_<id>) as the username and the secret as the password. Both work on every door.
curl https://api.codossier.com/v1/matters \
-H "Authorization: Bearer cdk_test_<id>_<secret>"curl https://api.codossier.com/v1/matters -u "cdk_<id>:<secret>"3. Make the first call
With a sandbox key, open a simulated matter. The call answers at once with a request; the matter builds in the background (a real one takes 20–30 minutes; a simulated one, seconds).
curl -X POST https://api.codossier.com/v1/requests \
-H "Authorization: Bearer cdk_test_<id>_<secret>" \
-H "Content-Type: application/json" \
-H "Prefer: wait=30" \
-d '{
"intent": "open_matter",
"text": "Our client was dismissed three weeks after reporting billing irregularities...",
"options": { "simulate": "ready" }
}'{
"id": "01a1…",
"schema": "codossier.request/1.1",
"understood_as": { "intent": "open_matter", "how": "explicit" },
"status": "working",
"stage": { "code": "building", "label": "building the dossier" },
"eta": "2026-10-08T19:02:11Z",
"next": { "poll_after_seconds": 60 },
"links": { "self": "https://api.codossier.com/v1/requests/01a1…", "events": "https://api.codossier.com/v1/events?after=786873" }
}Follow it with GET /v1/requests/{id}, adding Prefer: wait=60 to hold the call until something changes. When status is completed, links.dossier points at the finished dossier. The same three calls, with a live key and no simulate, open a real matter.
How every call behaves
- Snake_case JSON in and out. Dates are ISO-8601 UTC. Ids are UUIDs.
- One envelope in, one envelope out. Every piece of work is
POST /v1/requestswith anintent; every answer is a request with astatus(queued,working,needs_input,completed,failed). - Quick or long. Quick intents (search, apply, add_node, deliver, reply) answer inside the wait window. Long ones (open_matter, inquire, supplement, import) answer 202 at once and finish in the background.
- Questions come back as data. A request that needs something from you is
needs_inputwithquestions[]; you answer with thereplyintent. - Refusals are problem documents (
codossier.problem/1.0) with acodeyou can branch on, a humandetail, and acorrelation_idto quote to us. - Idempotency. Send
Idempotency-Keyon any POST and a retry returns the same request instead of a second one. - Sandbox and live never mix. A sandbox key sees only simulated matters; a live key never sees them.
Paying for matters
Opening a real matter costs one dossier credit, the same as on the site. A personal key spends one of your own credits automatically; an office set up for invoice billing has its matters counted onto the monthly invoice instead. With no credit and no invoice the request answers billing_not_enabled and says where to buy. Search, the Lode CLI and the other work on a matter you own are included within a daily allowance per dossier. Send "estimate": true with any request to see its price and plan without running it.