REST API reference

The public Agreebase REST contract for creating, signing, retrieving, changing, notarising, and verifying records.

The REST base path is /api/v1.

The full generated contract, with exact request/response JSON schemas and security declarations for every route, is always available at /api/openapi.json. Treat it as the source of truth ahead of this page for field-level shapes.

Authentication

Public routes require no credentials. Protected routes accept a short-lived bearer token or an API key where the route supports that scope:

Authorization: Bearer <short-lived-token>

X-API-Key: <long-lived-key>

See Authentication and API keys.

Public verification routes

Method Route Purpose
GET /public/verify/{agr_reference} Return a public certificate and current-authority result.
POST /public/verify/{agr_reference} Verify text, body/content hash, document hash, or transaction hash.
GET /public/agreements/{agr_reference} Return redacted public record metadata.

Verification is also available through the browser at /verify.

Authentication and identity routes

Method Route Purpose
POST /verification/request-otp Request an OTP for authentication, confirmation, or linking.
POST /verification/verify-otp Verify an OTP and issue a bearer token where applicable.
GET /identity/contact-points List verified identity contact points.
POST /identity/link Link a verified email through a linking OTP.
GET /identity/agreements List records associated with the identity graph.
GET /api-keys List non-revoked API keys.
POST /api-keys Create an API key; the secret is returned once.
DELETE /api-keys/{key_id} Revoke an API key.

Creation routes

Method Route Required scope Purpose
POST /agreements create Create an agreement draft and initiator participant.
POST /declarations create Create a single-declarant draft.
POST /notarizations create Create a file, text, or hash notarization.

Agreement and declaration bodies contain 2–350 normalized words and at most 7,000 characters. Agreements support up to 15 signing participants including the initiator and up to 5 active witnesses. Notarizations support up to 14 co-notarizers and do not accept source file bytes.

Notarization requests accept content_type values file, text, or hash. Text requests include normalized-text validation; file and hash requests require a label or filename.

Agreement and declaration routes

Method Route Purpose
GET /agreements/{id_or_ref} Retrieve an authenticated participant view.
PATCH /agreements/{id_or_ref} Update an eligible draft.
POST /agreements/{id_or_ref}/submit Submit a signed ordinary draft for confirmation.
POST /agreements/{id_or_ref}/signature-execution Start or resume the caller's signature execution.
GET /agreements/{id_or_ref}/signature-execution Read signature execution state.
POST /agreements/{id_or_ref}/signature-execution/methods/{method}/start Start a method.
POST /agreements/{id_or_ref}/signature-execution/methods/{method}/submit Submit OTP, URL, or WebAuthn evidence.
POST /agreements/{id_or_ref}/signature-execution/methods/{method}/refresh Refresh an expiring method.
POST /agreements/{id_or_ref}/signature-execution/methods/{method}/cancel Cancel a pending method.
POST /agreements/{id_or_ref}/signature-execution/finalize Finalize the current participant signature.
GET /agreements/{id_or_ref}/document Download the sealed signed PDF.
GET /agreements/{id_or_ref}/card.png Download or lazily generate the private card.
POST /agreements/{id_or_ref}/card-ticket Issue a short-lived, single-use private card URL.

The returned ticket is redeemed by GET /artifacts/share-card/{token}. The token is opaque, scoped to one card, short-lived, and single-use; clients must not log or persist it.

The signature method values are email_otp, github_gist, x_post, reddit_post, telegram, and webauthn_passkey.

Notarizations have equivalent signature execution routes under /notarizations/{id_or_ref}/signature-execution, plus GET /notarizations/{id_or_ref} and GET /notarizations/{id_or_ref}/card.png and POST /notarizations/{id_or_ref}/card-ticket. Notarizations do not expose a PDF route.

Lifecycle routes

Method Route Effect
POST /agreements/{id_or_ref}/decline Decline as a non-initiator participant or witness.
POST /agreements/{id_or_ref}/participants/{party_id}/resend-invitation Resend an eligible invitation.
POST /agreements/{id_or_ref}/witnesses/{party_id}/waive Proceed without an eligible declined/removed witness.
POST /agreements/{id_or_ref}/co-notarizers/{party_id}/waive Complete a notarization without one declined co-notarizer.
POST /agreements/{id_or_ref}/participants/{party_id}/complete-without Proceed without an eligible declined/removed participant.
POST /agreements/{id_or_ref}/witnesses/{party_id}/replace Replace an eligible declined/removed witness.
POST /agreements/{id_or_ref}/rescind Initiator ends a pending agreement, declaration, or notarization.
POST /agreements/{id_or_ref}/amend Create a new amendment draft for a sealed agreement.
POST /agreements/{id_or_ref}/cancel Create a mutual cancellation draft for a sealed agreement.

These operations are state- and role-dependent. See Lifecycle and versions.

Counter-proposal routes

Counter-proposals are submitted by eligible non-initiator parties while an agreement is pending. Only one can be active.

Method Route Purpose
POST /agreements/{id_or_ref}/counter Submit a full proposed body.
GET /agreements/{id_or_ref}/counter/{counter_id} Retrieve a counter-proposal.
POST /agreements/{id_or_ref}/counter/{counter_id}/resolve Initiator accepts, partially accepts, or rejects.
POST /agreements/{id_or_ref}/counter/{counter_id}/withdraw Proposer withdraws a pending counter.

Partial acceptance requires a resolved body. An accepted body change increments the current version and resets affected signature work.

Response and error behavior

Successful record responses include the AGR reference, type, status, version, participants, witness summary, blockchain state where applicable, party-facing metadata when sealed, and compact optional image metadata. Identicons contain kind, digest, short_hash, width, height, alt_text, and available. They do not contain SVG bytes, data URIs, or internal algorithm/version fields by default. Share-card metadata never contains a storage path or ordinary download URL.

For authenticated agreement and signature retrieval, add image_representation=compatibility_data_uri only when an older client requires an inline SVG data URI. The default metadata representation is safe for ordinary clients and leaves internal identicon serializers and rendering APIs unchanged. Public verification and known-reference agreement responses expose document-identicon metadata only for sealed records; they do not expose signature identicons, cards, bodies, or private participant data. Authenticated full agreement responses may include permitted current party signature-identicon metadata, and authenticated signature-execution reads may include the current caller's finalized signature identicon. REST public routes never serialize those signature identicons.

The card-ticket endpoints require the same authenticated participant authorization as the existing binary card routes. A successful response uses the configured APP_BASE_URL, identifies no agreement data in its opaque URL, expires after five minutes by default, and can be redeemed once. Redemption uses Cache-Control: no-store, Referrer-Policy: no-referrer, and atomic single-use enforcement. The URL is intentionally not a presigned storage URL. An hourly maintenance job removes redeemed and expired ticket records.

Common HTTP outcomes include:

  • 400 for malformed requests.
  • 401 for missing or invalid authentication.
  • 403 for role or scope failure.
  • 404 for missing records or artifacts.
  • 409 for lifecycle conflicts or stale state.
  • 422 for validation errors.
  • 429 for OTP, provider, invitation, or route rate limits.

Do not retry a mutating request blindly after a timeout. Re-read the record and signature state, then follow the returned lifecycle state or next action.

Discard changes?

Are you sure? Your draft and any progress will be lost.