Developers
LiveQuickstart: your first proposal.
Five minutes from a new key to a commitment a person has approved. Every write from a key becomes a proposal first. Nothing is confirmed until someone in your workspace says so.
1. Create a key
In the Ordo app, open Settings → Developers and create an API key. Give it a name and, optionally, an agent name; the agent name appears in the audit log next to everything the key does. The key acts as you.
| Scope | What it allows |
|---|---|
read | Read commitments, their history and the audit log. |
propose | Capture text and propose commitments or changes for a person to approve. |
confirm | Confirm and change commitments directly, but only once a workspace admin allows that key in Settings → Developers. |
New keys get read and propose. The secret starts with ordo_sk_ and is shown once, so copy it into your environment:
export ORDO_API_KEY="ordo_sk_…"2. Check the key
curl https://api.ordo.app/v1 \
-H "Authorization: Bearer $ORDO_API_KEY"{
"version": "2026-11-17",
"actor": { "type": "api_key", "keyId": "…", "agent": "my-script", "scopes": ["read", "propose"] }
}3. Read what you owe
GET /v1/commitments returns commitments newest first. Filter with state, owner, requester, source, from and to; page with limit (up to 100) and the nextCursor you get back.
curl "https://api.ordo.app/v1/commitments?owner=me&state=confirmed,in_progress" \
-H "Authorization: Bearer $ORDO_API_KEY"{
"object": "list",
"data": [
{
"id": "…",
"object": "commitment",
"state": "confirmed",
"title": "Send Acme the revised SOW",
"ownerId": "…",
"requester": { "name": "Dana Lee", "email": "dana@acme.example", "userId": null },
"dueAt": "2026-11-21T17:00:00.000Z",
"evidence": "I'll get you the revised SOW by Friday.",
"version": "…"
}
],
"nextCursor": null
}4. Send a conversation
Post conversation text (an email thread, chat or meeting notes, up to 32 KB) to /v1/captures. Ordo extracts the commitments in it and returns them as proposals. Send an Idempotency-Key so a retry never creates duplicates; externalId does the same per conversation.
curl https://api.ordo.app/v1/captures \
-H "Authorization: Bearer $ORDO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: call-notes-2026-11-18-acme" \
-H "Ordo-Agent: my-script" \
-d '{
"text": "Dana: can you send the revised SOW?\nSam: Yes, I will send it by Friday.",
"sourceLabel": "Acme call notes",
"externalId": "acme-call-2026-11-18"
}'{
"captureId": "…",
"commitments": [
{ "id": "…", "object": "commitment", "state": "proposed", "title": "Send the revised SOW", "dueAt": "2026-11-21T…", "confidence": 0.9, "proposalId": "…" }
]
}5. Approve it in Ordo
The proposals are now in the review queue in the Ordo app, with the source text attached. A person confirms, edits or dismisses each one. Once confirmed, the commitment reads back with state: "confirmed" and Ordo follows it through.
A workspace admin can let a specific key with the confirm scope approve on its own. That key can then confirm through the API:
curl https://api.ordo.app/v1/commitments/$ID/transitions \
-H "Authorization: Bearer $ORDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": "confirmed" }'Without that permission the request is refused with 403 approval_required, so an agent can tell its user to approve in Ordo instead.
Next
- API reference: every endpoint, the lifecycle, errors, If-Match and limits.
- Webhooks: get signed events when commitments are proposed, confirmed, due or kept.
- MCP server: let Claude and other agents read and propose commitments.
API version 2026-11-17. Breaking changes are versioned; we email key holders before they ship. Request access.
