Developers
LiveAPI reference.
A REST API over the commitment ledger. Base URL https://api.ordo.app, JSON in and out, version 2026-11-17. Every response carries an Ordo-Version header; breaking changes get a new date and the old one keeps working with a Deprecation header.
The machine-readable contract is public at /v1/openapi.json (OpenAPI 3.1). This page is the readable version.
Authentication
Send an API key as a Bearer token. Keys start with ordo_sk_ and are created in Settings → Developers (see the quickstart).
Authorization: Bearer ordo_sk_…
Ordo-Agent: my-agent # optional, shown in the audit logEndpoints
| Endpoint | Scope | What it does |
|---|---|---|
| GET /v1 | Any key | Check a key: the API version, the caller and its scopes. |
| GET /v1/openapi.json | No key | The OpenAPI 3.1 contract. No key needed. |
| GET /v1/commitments | read | List commitments, newest first. |
| POST /v1/commitments | propose | Propose a commitment directly. It starts as proposed. |
| GET /v1/commitments/{id} | read | Get one commitment, by its id or the id of the proposal it came from. |
| PATCH /v1/commitments/{id} | propose | Edit owner, due date, condition, open question or requester. |
| POST /v1/commitments/{id}/transitions | propose | Move a commitment through its lifecycle. |
| GET /v1/commitments/{id}/events | read | Where it came from and everything that happened since, oldest first. |
| POST /v1/captures | propose | Send conversation text and get back the commitments Ordo proposes from it. |
| GET /v1/audit/events | read | The workspace audit log, newest first. |
GET /v1/commitments accepts state (comma-separated; defaults to every state except captured), owner (a user id or me), requester (a user id, an email or me), source, from/to (ISO dates), limit (1–100, default 25) and cursor. Lists return { "object": "list", "data": [...], "nextCursor": … }; pass nextCursor back as cursor until it is null. The audit log pages with before and nextBefore instead.
POST /v1/captures takes text (required, 32 KB max), sourceLabel, sourceUrl and externalId. Sending the same externalId again returns the first capture. POST /v1/commitments takes title (required), summary, ownerId, dueAt or dueCondition, openDecision, requester and evidence (what was said, for the reviewer).
Commitment states
| State | Meaning |
|---|---|
captured | Text Ordo has received but not proposed from. Hidden from lists unless you ask for it. |
proposed | Waiting in the review queue for a person to confirm or dismiss. |
confirmed | A person approved it. Now a tracked commitment. |
in_progress | Someone is working on it. |
fulfilled | The promise was kept. |
renegotiated | The due date moved to a later one, on the record. |
broken | It will not happen. |
dismissed | A reviewer decided the proposal was not a commitment. |
Move a commitment with POST /v1/commitments/{id}/transitions and a body of { "to": … }:
- A
proposedcommitment moves toconfirmedordismissed. Both need confirm rights. Dismissing needs areasonCode:not_a_commitment,not_actionable,duplicate,wrong_owner,wrong_due_date,already_doneorother. - A
confirmedcommitment moves toin_progress,fulfilled,renegotiated(with adueAtlater than the current one) orbroken. Without confirm rights the change is proposed and the response is202. fulfilledandbrokenare final. An optionalnote(500 characters) is kept on the record.
{ "to": "renegotiated", "dueAt": "2026-12-05T17:00:00Z", "note": "Waiting on legal" }
{ "to": "dismissed", "reasonCode": "duplicate" }
{ "to": "fulfilled", "note": "SOW sent in the thread on Nov 20" }Applied or proposed
PATCH and transitions return a write result. 200 with applied: true means the change is made. 202 with applied: false means Ordo filed it as a proposal for a person to approve, with its proposalId.
{
"commitment": { "id": "…", "state": "confirmed", "version": "…" },
"applied": false,
"proposalId": "…",
"message": "Proposed for a person to approve."
}A key without confirm rights can propose owner and due-date changes to a confirmed commitment. Other edits to a confirmed commitment, and removing a due date, need a person.
If-Match
Every commitment has a version. Send it as If-Match on PATCH and on transitions. It is required to edit a confirmed commitment (428 precondition_required without it). If someone changed the commitment since you read it, you get 409 conflict: fetch it again and retry.
curl -X PATCH https://api.ordo.app/v1/commitments/$ID \
-H "Authorization: Bearer $ORDO_API_KEY" \
-H "Content-Type: application/json" \
-H "If-Match: $VERSION" \
-H "Idempotency-Key: move-due-$ID-1" \
-d '{ "dueAt": "2026-11-28T17:00:00Z", "note": "Customer asked for next week" }'Idempotency-Key
Every POST and PATCH accepts an Idempotency-Key header of 8–128 letters, digits, dots, colons, dashes or underscores. Keys are scoped to your API key.
- A retry with the same key and body returns the first response for 24 hours, with
Idempotent-Replayed: true. - The same key with a different body is refused with
422 idempotency_mismatch. - A retry while the first request is still running gets
409 conflict. Wait a moment and retry. - Refusals are kept like successes; only a server error frees the key for another try.
Errors
Errors share one shape. Match on error.code; the message is written for people and can change.
{
"error": {
"code": "approval_required",
"message": "This key can only propose owner and date changes to a confirmed commitment.",
"details": {},
"requestId": "…"
}
}| Status | Code | When |
|---|---|---|
| 400 | validation_error | A field is missing or invalid. `details` names the field. |
| 401 | unauthorized | No key, or the key is wrong or revoked. |
| 402 | quota_exceeded | The workspace used its API calls for this calendar month. |
| 403 | insufficient_scope | The key lacks the scope this endpoint needs. |
| 403 | approval_required | This change needs a person, or a key an admin allowed to confirm. |
| 403 | api_writes_blocked | A workspace admin paused writes from API keys. Reads still work. |
| 404 | not_found | No such commitment in this workspace. |
| 409 | conflict | It changed since you read it (If-Match mismatch), a matching change is already waiting for review, or the same Idempotency-Key is still processing. |
| 409 | invalid_transition | That move is not allowed from the current state. |
| 422 | idempotency_mismatch | The Idempotency-Key was already used for a different request. |
| 428 | precondition_required | Editing a confirmed commitment needs If-Match. |
| 429 | rate_limited | Too many requests from this key in the last minute. |
Rate limits and monthly allowance
Calls made with API keys (including the MCP server) are metered by plan. Requests per minute are counted per key; the monthly allowance is per workspace and resets on the first of each month (UTC). People using the Ordo app are not metered.
| Plan | Requests / minute / key | Calls / month / workspace |
|---|---|---|
| Free | 30 | 1,000 |
| Pro | 120 | 25,000 |
| Team | 300 | 100,000 |
| Enterprise | 1,200 | 1,000,000 |
- Over the per-minute limit:
429 rate_limited.RateLimit-Limit,RateLimit-RemainingandRateLimit-Resetheaders tell you where you stand; back off and retry. - Over the monthly allowance:
402 quota_exceededuntil the new month or an upgrade.Ordo-Quota-LimitandOrdo-Quota-Remainingcome back on every metered response.
Plans are on the pricing page.
API version 2026-11-17. Breaking changes are versioned; we email key holders before they ship. Request access.
