Quickstart

Draft — ahead of the backend; nothing here is live yet. This surface is written against the design, not against a running server. There is no api.contracts.io to call, no key to issue, and every response below is an illustration rather than a recording. It is published so the shape can be argued with before it is built.It also predates CONTRACT-SCHEMA v0 and still uses the older nouns — ask for Proposal, receipt for Version, relationship for Room. The glossary maps them.

Eight steps, twelve calls, and a whole negotiation from nothing to signed. Both sides are here, because half of it happens in somebody else’s hands. The shape is always the same: find out who you are, draft, send, one reply cycle, sign.

Set these once. Every call below assumes them.

export CONTRACTS_KEY="sk_test_..."
export API="https://api.contracts.io"

1. Find out who you are

Every write names the person it acts for, and you do not have that person’s id yet. This is the call that hands it to you. Make it first.

curl $API/me \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Version: 2026-08-24"

200 OK

{
  "person_id": "per_9",
  "name": "Nora Whitfield",
  "email": "nora@acme.com",
  "org_id": "org_2",
  "org_name": "Acme",
  "parties": [],
  "person_rung": 1,
  "org_ceiling": 2,
  "effective_rung": 1,
  "scopes": ["contracts:read", "contracts:write", "decisions:write", "send", "sign"],
  "pinned_version": "2026-08-24",
  "credential": "org_key",
  "is_guest": false
}

export ACTING="per_9"        # the human this key acts for

A test key with no Contracts-Acting-Person header comes back with person_id: null. That is a key that can read across your org and write nothing. Bind it to a person in Settings, Developers, or send the header on every call, as we do below.

2. Draft a contract

Give a prompt or a template_id, not both.

curl -X POST $API/contracts \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Version: 2026-08-24" \
  -H "Contracts-Acting-Person: $ACTING" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "6-month contract PM at £600/day, send to sam@acme.com",
    "facts": { "governing_law": "England & Wales", "term_months": 6 }
  }'

201 Created

{
  "id": "con_1",
  "state": "draft",
  "origin": "api",
  "url": "https://contracts.io/c/con_1",
  "words_hash": "sha256:1a4d...",
  "head_sequence": 1,
  "blocks": [ { "id": "blk_1", "number": 1, "kind": "clause", "text": "..." } ],
  "facts": [
    { "id": "fct_law", "name": "governing_law", "value": "England & Wales",
      "inferred": false, "occurrences": ["blk_12"] },
    { "id": "fct_term", "name": "term_months", "value": "6 months",
      "inferred": false, "occurrences": ["blk_3", "blk_9"] }
  ],
  "questions": [ { "id": "q_1", "asks": "Who are the parties?" } ],
  "proposed_recipients": [
    { "email": "sam@acme.com", "capacity": ["negotiator", "signer"] }
  ]
}

Your prompt named a recipient, so you got proposed_recipients. Never a sent contract. That is the API’s version of a Send sheet, addressed, one button unpressed. Nothing has left your side.

questions[] is capped at three and only ever contains genuine forks: things the draft cannot resolve without you, not a form to fill in. Keep words_hash. Every call that changes anything returns it, and it is what you send as If-Match on the next one. You never need an extra GET to find it.

3. Fill a fact, before the first send

Before the first send you hold the words alone, so a fact change applies directly. fct_term came back in the response above.

curl -X POST $API/contracts/con_1/facts/fct_term \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING" \
  -H "If-Match: sha256:1a4d..." \
  -H "Content-Type: application/json" \
  -d '{ "value": "9 months" }'

200 OK

{ "applied": true, "blocks_touched": ["blk_3", "blk_9"], "words_hash": "sha256:6b02..." }

The hash moved. Carry the new one into the next call. After the first send this same request returns "applied": false and stages a proposal instead, and the hash comes back unchanged, because a proposal moves no words.

4. Send, and the room is born

Send is confirmation-class. confirmed_by is the per_… of the human who pressed the button, and the server checks that they are really on this contract and really allowed to do this.

curl -X POST $API/contracts/con_1/send \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING" \
  -H "If-Match: sha256:6b02..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "email": "sam@acme.com", "name": "Sam Ford", "capacity": ["negotiator", "signer"] }
    ],
    "note": "First draft. Shout if the cap is wrong.",
    "confirmed_by": "per_9"
  }'

200 OK

{
  "state": "sent",
  "letter": "let_1",
  "relationship": "rel_4",
  "relationship_created": true,
  "words_hash": "sha256:6b02..."
}

relationship_created: true is the only trace of a room being born. There was no POST /rooms, no routing order, no recipient roles configured before words moved, and no “send for signature” mode. Capacity did that work.

Drop confirmed_by and you get 409 confirmation_required. Do not retry it. Assemble the letter, put it in front of a person, and call again once they have pressed the button.

5. The other side counters

Sam has no account with us. He got an email with a link, and he can negotiate and sign through it. This is the normal way the other side arrives, so it is worth doing once here rather than discovering it in production. Reading uses the link, with the token as a query parameter:

curl "$API/contracts/con_1?t=gtk_8f3a..."

Writing uses a header. Sam wants nine months instead of twelve, and nobody has raised that question yet, so he names the clause rather than a question:

curl -X POST $API/contracts/con_1/decisions \
  -H "Authorization: Token gtk_8f3a..." \
  -H "If-Match: sha256:6b02..." \
  -H "Content-Type: application/json" \
  -d '{
    "block_id": "blk_9",
    "type": "counter",
    "text": "nine (9) months",
    "why": "We cannot commit past the end of our financial year."
  }'

201 Created

{
  "id": "dec_11", "state": "staged", "sent": false,
  "ask": "ask_12", "ask_created": true, "words_hash": "sha256:6b02..."
}

Then he commits the round:

curl -X POST $API/contracts/con_1/replies \
  -H "Authorization: Token gtk_8f3a..." \
  -H "If-Match: sha256:6b02..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "note": "One number, otherwise happy." }'

A guest call sends no Contracts-Acting-Person and no confirmed_by. The link token names one contract and one person, so it already supplies both. Sending either one returns 400 invalid_request rather than being quietly believed. Everything else works exactly as it does for a key: same If-Match, same Idempotency-Key, same conflict responses. See Guests.

Use block_id when nobody has raised the question yet, and ask_id once somebody has. Send one or the other, never both.

6. Read the inbound round and answer it

letter.received fires on your side. Fetch the round.

curl $API/contracts/con_1/letters/latest \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING"

200 OK

{
  "id": "let_2",
  "kind": "sent",
  "sequence": 4,
  "from": "pty_acme",
  "note": "One number, otherwise happy.",
  "asks": [
    {
      "id": "ask_12",
      "block": "blk_9",
      "type": "replace",
      "standing": "twelve (12) months",
      "proposed": "nine (9) months",
      "why": "We cannot commit past the end of our financial year.",
      "tally": { "agreed": ["pty_acme"], "awaiting": ["pty_north"] }
    }
  ]
}

The letter came from: "pty_acme", so pty_acme is in agreed. A party agrees by proposing. Unanimity is only countable if the proposer is counted, so never read agreed as “everyone but them”. Nine months is fine. Stage an accept. Staging writes to your unsent reply, and nothing leaves your side. The other party cannot see it, count it, or be told about it.

curl -X POST $API/contracts/con_1/decisions \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING" \
  -H "If-Match: sha256:6b02..." \
  -H "Content-Type: application/json" \
  -d '{ "ask_id": "ask_12", "type": "accept" }'

201 Created

{ "id": "dec_14", "state": "staged", "sent": false,
  "ask": "ask_12", "words_hash": "sha256:6b02..." }

Inspect the round before committing it, and back out anything you change your mind about:

# your staged decisions, your note, and the server's own dry run
curl $API/contracts/con_1/reply \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING"

# withdraw one decision
curl -X DELETE $API/contracts/con_1/decisions/dec_14 \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING"

# discard the whole round
curl -X DELETE $API/contracts/con_1/reply \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING"

GET /contracts/{id}/reply carries landed_if_sent, which is the server working out what would actually change if you sent this. Never compute that yourself.

why is required on a counter and on a decline. A counter without a reason is a fight.

7. Commit the reply

curl -X POST $API/contracts/con_1/replies \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING" \
  -H "If-Match: sha256:6b02..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Nine works.", "confirmed_by": "per_9" }'

200 OK

{
  "letter": "let_3",
  "state": "agreed",
  "landed": ["blk_9"],
  "re_asked": [],
  "asks_opened": [],
  "words_hash": "sha256:9f2c..."
}

Three fields carry the whole result:

landed are the clauses that reached unanimity on this send. This is the only way words ever change. blk_9 now reads “nine (9) months”, and the hash moved because of it.
asks_opened are questions this round put on the table. Empty here, because you accepted rather than countered. A counter always returns landed: []: it opens a question and waits, it does not move words.
re_asked are decisions killed because a letter from the other side moved that clause while your round was staged. Re-decide those, and only those, then commit again.

state is now agreed. Everyone has said yes to every clause, contract.agreed fires, and the signing block wakes up. If the hash you sent was stale, you get 409 words_changed instead, with the current hash and a non-empty re_asked. Refetch, re-decide, retry.

409 words_changed

{
  "error": {
    "type": "conflict_error",
    "code": "words_changed",
    "message": "The words moved while you were deciding.",
    "param": "If-Match",
    "doc_url": "https://docs.contracts.io/errors#words-changed"
  },
  "current_hash": "sha256:be71...",
  "re_asked": ["ask_7"]
}

8. Sign

Wait for agreed before you try this. Signing an unfinished contract is refused. Step 7 returned "state": "agreed", and contract.agreed fired on both sides. If you are polling instead of listening, GET /contracts/con_1/state is the check.

A signature binds to an exact text hash, never to “the contract”. Each person signs for themselves. You sign as your own signer, using your own key:

curl -X POST $API/contracts/con_1/signatures \
  -H "Authorization: Bearer $CONTRACTS_KEY" \
  -H "Contracts-Acting-Person: $ACTING" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "text_hash": "sha256:9f2c...",
    "signer": { "name": "Nora Whitfield", "email": "nora@acme.com" },
    "confirmed_by": "per_9",
    "intent": "I agree to be bound by these words."
  }'

201 Created

{
  "id": "sig_2", "state": "bound", "version": "ver_5", "executed": false,
  "signed_at": "2026-08-24T11:04:00Z", "words_hash": "sha256:9f2c..."
}

Sam signs through his own link, from his own browser:

curl -X POST $API/contracts/con_1/signatures \
  -H "Authorization: Token gtk_8f3a..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "text_hash": "sha256:9f2c...",
    "signer": { "name": "Sam Ford", "email": "sam@acme.com" },
    "intent": "I agree to be bound by these words."
  }'

You cannot sign for the person you sent to. The person in confirmed_by must be the person signing, must hold signing capacity, and must be in your own org. Anything else returns 403 not_a_signer. Consent is not something one side supplies on behalf of the other, and the API enforces that rather than trusting it.

If the words moved while a signer was reading, the compare-and-swap catches it:

409 words_changed

{
  "error": {
    "type": "conflict_error",
    "code": "words_changed",
    "message": "The words moved. Read the contract again and sign the current text.",
    "param": "text_hash",
    "doc_url": "https://docs.contracts.io/errors#words-changed"
  },
  "current_hash": "sha256:be71...",
  "your_signature": { "id": "sig_1", "state": "void", "bound_hash": "sha256:9f2c..." }
}

Never migrate a signature onto new text. A signature survives an open question as held. It voids only when the words mint a new hash, and the replacement is always a fresh POST /contracts/{id}/signatures against the hash that signer actually saw.

When the last required signature binds, contract.executed fires with a version and a certificate_url, and you can fetch the record any time from GET /contracts/{id}/certificate. executed is terminal. To change it, POST /contracts/{id}/amend.

The hash flow, in one picture

GET  /me                     → per_9
POST /contracts                 → words_hash: 1a4d
  ↓ If-Match: 1a4d
POST …/facts/fct_term        → applied, words_hash: 6b02
  ↓ If-Match: 6b02
POST …/send                  → letter let_1, relationship born
  ↓ If-Match: 6b02
POST …/decisions   [guest]   → ask_12 minted, staged (private, no hash move)
POST …/replies     [guest]   → letter let_2, landed[], asks_opened: [ask_12]
  ↓ If-Match: 6b02
POST …/decisions             → dec_14 staged (private, no hash move)
  ↓ If-Match: 6b02
POST …/replies               → landed: [blk_9], state agreed, words_hash: 9f2c
  ↓ text_hash: 9f2c
POST …/signatures            → sig_2 bound → ver_5 → executed

Staging never moves the hash. Only a landed clause does. That is why you can stage a whole round without racing the other side, and why the race, when it happens, surfaces exactly once: at the commit.

Every write and its headers

Which calls take If-Match, Idempotency-Key and confirmed_by.

Errors

Every code, its status, and how to recover.

Endpoint reference

Every public call, grouped by resource.

Webhooks

Eighteen event types, HMAC signing, and how to catch up after an outage.

Get started

Endpoints

Agents

Reference

1. Find out who you are

2. Draft a contract

3. Fill a fact, before the first send

4. Send, and the room is born

5. The other side counters

6. Read the inbound round and answer it

7. Commit the reply

8. Sign

The hash flow, in one picture

Next

Every write and its headers

Errors

Endpoint reference

Webhooks

​1. Find out who you are

​2. Draft a contract

​3. Fill a fact, before the first send

​4. Send, and the room is born

​5. The other side counters

​6. Read the inbound round and answer it

​7. Commit the reply

​8. Sign

​The hash flow, in one picture

​Next

Every write and its headers

Errors

Endpoint reference

Webhooks

1. Find out who you are

2. Draft a contract

3. Fill a fact, before the first send

4. Send, and the room is born

5. The other side counters

6. Read the inbound round and answer it

7. Commit the reply

8. Sign

The hash flow, in one picture

Next