Ordo

Developers

Live

API 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 log
The product contract holds here too: writes from a key land as proposals a person approves in Ordo, unless a workspace admin lets that specific key confirm. Admins can also pause all API writes; reads keep working.

Endpoints

EndpointScopeWhat it does
GET /v1Any keyCheck a key: the API version, the caller and its scopes.
GET /v1/openapi.jsonNo keyThe OpenAPI 3.1 contract. No key needed.
GET /v1/commitmentsreadList commitments, newest first.
POST /v1/commitmentsproposePropose a commitment directly. It starts as proposed.
GET /v1/commitments/{id}readGet one commitment, by its id or the id of the proposal it came from.
PATCH /v1/commitments/{id}proposeEdit owner, due date, condition, open question or requester.
POST /v1/commitments/{id}/transitionsproposeMove a commitment through its lifecycle.
GET /v1/commitments/{id}/eventsreadWhere it came from and everything that happened since, oldest first.
POST /v1/capturesproposeSend conversation text and get back the commitments Ordo proposes from it.
GET /v1/audit/eventsreadThe 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

StateMeaning
capturedText Ordo has received but not proposed from. Hidden from lists unless you ask for it.
proposedWaiting in the review queue for a person to confirm or dismiss.
confirmedA person approved it. Now a tracked commitment.
in_progressSomeone is working on it.
fulfilledThe promise was kept.
renegotiatedThe due date moved to a later one, on the record.
brokenIt will not happen.
dismissedA reviewer decided the proposal was not a commitment.

Move a commitment with POST /v1/commitments/{id}/transitions and a body of { "to": … }:

  • A proposed commitment moves to confirmed or dismissed. Both need confirm rights. Dismissing needs a reasonCode: not_a_commitment, not_actionable, duplicate, wrong_owner, wrong_due_date, already_done or other.
  • A confirmed commitment moves to in_progress, fulfilled, renegotiated (with a dueAt later than the current one) or broken. Without confirm rights the change is proposed and the response is 202.
  • fulfilled and broken are final. An optional note (500 characters) is kept on the record.
Transition bodies
{ "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.

202 Accepted
{
  "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.

Move a due date
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": "…"
  }
}
StatusCodeWhen
400validation_errorA field is missing or invalid. `details` names the field.
401unauthorizedNo key, or the key is wrong or revoked.
402quota_exceededThe workspace used its API calls for this calendar month.
403insufficient_scopeThe key lacks the scope this endpoint needs.
403approval_requiredThis change needs a person, or a key an admin allowed to confirm.
403api_writes_blockedA workspace admin paused writes from API keys. Reads still work.
404not_foundNo such commitment in this workspace.
409conflictIt changed since you read it (If-Match mismatch), a matching change is already waiting for review, or the same Idempotency-Key is still processing.
409invalid_transitionThat move is not allowed from the current state.
422idempotency_mismatchThe Idempotency-Key was already used for a different request.
428precondition_requiredEditing a confirmed commitment needs If-Match.
429rate_limitedToo 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.

PlanRequests / minute / keyCalls / month / workspace
Free301,000
Pro12025,000
Team300100,000
Enterprise1,2001,000,000
  • Over the per-minute limit: 429 rate_limited. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers tell you where you stand; back off and retry.
  • Over the monthly allowance: 402 quota_exceeded until the new month or an upgrade. Ordo-Quota-Limit and Ordo-Quota-Remaining come 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.

Start free

Try commitment infrastructure on one conversation.

Paste one email thread. Ordo proposes the next steps, and nothing happens until you confirm.