Integrate

REST API reference

Every endpoint, its auth, body, response and errors.

Base URL: https://befitting-mosquito-713.convex.site. All bodies are JSON. Authenticate with an API key from Settings & developers:

bash
curl https://befitting-mosquito-713.convex.site/v1/me -H "Authorization: Bearer sk_..."

The full API is described in an OpenAPI 3.1 spec: import it into Postman, generate a client, or point your AI coding assistant at it.

Conventions

  • Money is integer cents (30000 = $300.00). Views also return formatted strings; display those.
  • Times are epoch milliseconds.
  • Lists come back as { "data": [...] }.
  • Errors are { "error": { "code", "message", ...details } } with an HTTP status:
CodeStatusMeaning
UNAUTHENTICATED401Missing, invalid or revoked key
FORBIDDEN403You're not allowed to do this on this promise
NOT_FOUND404Doesn't exist, or you're not a party to it
INVALID_ARGUMENT400The body is wrong (details explain)
INVALID_STATE409Not possible in the current status (read nextActions)
CONFLICT409A concurrent change won; re-read and retry
RATE_LIMITED429Slow down; retryAfterMs says how long
VERIFICATION_FAILED422The terms aren't proved
PAYMENT_FAILED402PayPal declined; paypalCode has the reason
AI_FAILED, CONFIG_MISSING503The AI step failed or isn't configured

Account

MethodPathBodyReturns
GET/v1/meYour profile
POST/v1/verify{ ir, feeBps? }{ valid, report | issues }; rate limited per account

Promises (contracts)

MethodPathBodyReturns
POST/v1/contracts{ role: "funder" | "payee", prompt, counterpartyEmail?, ir?, compile? }{ contractId, inviteToken, inviteUrl, compiling }
GET/v1/contracts{ data: [card] }
GET/v1/contracts/{id}The full view: status, parties, rendered, verification, approvals, funding, deadlines, ledger, money strings, nextActions
POST/v1/contracts/{id}/compile{ started, poll }; Claude writes and proves the rules
GET/v1/contracts/{id}/compileLive run: status, stage, steps[], assumptions, questions
PUT/v1/contracts/{id}/terms{ ir }{ irHash }; replaces the terms and re-verifies
POST/v1/contracts/{id}/approve{ termsHash }{ status }
POST/v1/contracts/{id}/cancelBefore funding only
POST/v1/invites/accept{ token }{ contractId }

Funding

MethodPathReturns
POST/v1/contracts/{id}/fund{ orderId, approveUrl }; send the payer to approveUrl
POST/v1/contracts/{id}/fund/confirm{ status, pending?, returned? }; idempotent
POST/v1/contracts/{id}/fund/reset{ status }; abandons a checkout the payer never approved

Deliveries (evidence)

MethodPathBodyReturns
POST/v1/contracts/{id}/uploads{ uploadUrl, maxBytes, allowedTypes }; POST the file there to get { storageId }
POST/v1/contracts/{id}/evidence{ slotId, storageId?, fileName?, text?, url? }{ evidenceId, status }
GET/v1/contracts/{id}/evidence{ data: [item] } with status, AI verdict, timer and can* flags
POST/v1/evidence/{id}/acceptPayer accepts
POST/v1/evidence/{id}/reject{ reason }Payer rejects (payee may dispute)
POST/v1/evidence/{id}/challenge{ reason }Payer objects during the challenge window
POST/v1/evidence/{id}/dispute{ reason }Payee disputes a rejection

Receipts

MethodPathAuthReturns
GET/v1/contracts/{id}/journal?limit=key{ data: [signed entry] }
GET/v1/contracts/{id}/proofkeyThe proof pack (kept-proof-pack/v1)
GET/v1/transparency/checkpoints?limit=publicSigned Merkle checkpoints
GET/v1/transparency/proof/{entryHash}publicInclusion proof for one entry
GET/.well-known/kept-keys.jsonpublicEd25519 public keys

Agent budgets (mandates)

MethodPathBodyReturns
POST/v1/mandates{ policy, prompt? }{ mandateId, verified, report }
GET/v1/mandates{ data: [card] }
GET/v1/mandates/{id}The full view
POST/v1/mandates/{id}/fund{ orderId, approveUrl }
POST/v1/mandates/{id}/fund/confirm{ status, returned? }
POST/v1/mandates/{id}/tokens{ label, expiresInHours? }{ token, mcpUrl, agentApiUrl, ... }, shown once
POST/v1/mandates/{id}/revokeCloses it and releases the unused hold
GET/v1/mandates/{id}/spends{ data: [spend] }
POST/v1/spends/{id}/decide{ approve, reason? }{ status }

Webhooks

MethodPathBodyReturns
POST/v1/webhooks/endpoints{ url, events? }{ endpointId, url, events, secret }, secret shown once

See Webhooks for payloads and signatures, and AI agents & MCP for the agent API (/agent/v1).

Improve this page on GitHub