REST API Reference

REST API reference

Use this reference together with the deployment's interactive docs and source-verified behavior. All paths are relative to the deployment API origin. Examples use placeholders, not real credentials or infrastructure addresses.

Versions and route families

Family	Base path	Access
Document integration CRUD	/api/v1/documents	Bearer token and document scopes
Document v2 and default aliases	/api/v2/documents, /api/documents	Same document router in the inspected implementation
Agreement and workflow	/api/v1/agreements	User authentication and operation permissions
Recipient portal	/api/v1/sign/{token}	Private signer-link capability and applicable consent/OTP checks
Templates	/api/v1/templates	User authentication, template permissions and access
Webhooks	/api/v1/webhooks	Scoped authentication except the event catalog
Client bindings and request logs	/api/v1/organisations/me	Relevant management/read scope
Signing and certificates	/api/v1/signing, /api/v1/certificates	Authenticated permissions
Public verification	/verify, /api/v1/verify	No normal workspace login required
Interactive documentation	/api/v1/docs, /api/v1/docs/openapi.json	Public documentation

v2 is a document-router alias, not a second version of every family. Unsupported version prefixes return a structured VERSION_NOT_SUPPORTED error with HTTP 404. The current OpenAPI content is partial; a documented placeholder such as a document /sign operation is not an implemented workflow endpoint.

Document operations

Method	Path under /api/v1/documents	Required scope	Normal success
GET	/	documents:read	200 list
POST	/	documents:create	201 object; stored idempotent replay 200
GET	/{id}	documents:read	200 object
PUT	/{id}	documents:update	200 object
PATCH	/{id}	documents:update	200 object
DELETE	/{id}	documents:delete	204, no response body

Access is evaluated within the authenticated organization. Updates require DRAFT; deletion additionally follows the agreement service's state rules. DELETE soft-deletes the underlying record.

POST body

Property	Type	Requirement
name	string	Required, 1–255 characters; downstream agreement validation also applies
content	string	Required, nonempty text or base64 representation
contentEncoding	utf-8 or base64	Defaults to utf-8
mimeType	string	application/pdf, text/markdown, or text/plain
description	string	Optional, at most 1,000 characters
tags	string array	At most 20 tags, each at most 50 characters
metadata	object	Optional; folder at most 100 characters; additional properties permitted

Omitted MIME type resolves to PDF for base64 or Markdown for UTF-8. Match the encoding and type to the actual content. Document integration CRUD does not accept Word MIME types even though the browser agreement upload flow supports Word.

PUT and PATCH

PUT requires name and optionally accepts content and other create-like properties plus expectedRevision. Its handler updates selected draft properties; it does not fully replace binary file content or clear all omitted properties. Metadata is merged and some omitted values are preserved. Avoid using it as a general-purpose binary replacement API.

PATCH accepts optional name, description, tags, metadata, and expectedRevision. It does not accept content. Metadata is merged. Neither handler enforces expectedRevision; applications needing concurrency protection must coordinate writes rather than assume an optimistic lock.

GET list parameters

Parameter	Meaning
page	Page number, at least 1; default mode begins at page 1
limit	1–100; default 20
cursor	Cursor mode; cursor= starts that mode, later use nextCursor
status	DRAFT, SENT, IN_PROGRESS, COMPLETED, DECLINED, CANCELLED, EXPIRED
folder	Match metadata.folder
search	Case-insensitive title or description search, up to 200 characters
from, to	Creation-time bounds as ISO 8601 timestamps with timezone

Do not combine page and cursor. IN_REVIEW and APPROVED are workflow states but are not accepted by this document-list status schema. sort and order are accepted by the schema, but the handler currently sorts by creation time descending and ID descending.

List response shape:

{
  "data": [],
  "pagination": {
    "page": 1,
    "total": 0,
    "limit": 20,
    "hasMore": false,
    "nextCursor": null
  }
}

Cursor responses omit page and total. Continue while hasMore is true using the returned cursor. Each object contains id, name, description, status, version, mimeType, fileSize, tags, metadata, createdAt, and updatedAt. Content and sensitive internal file/token properties are excluded from the document DTO.

Idempotency

POST document creation accepts Idempotency-Key or X-Idempotency-Key, 1–128 characters. Reuse a key only to retry the same logical request with identical body bytes and path. Successful stored replays include Idempotency-Replayed: true and X-Idempotent-Replay: true. Do not assume the same behavior applies to every mutation endpoint or that browser CORS exposes every optional header.

Public verification API

Both /verify and /api/v1/verify mount the same routes:

Method	Suffix	Input / result
GET	/{token}	Verification report for the supplied supported identifier
POST	/hash	JSON { "hash": "<SHA256_HEX>" }
POST	/file	JSON fileData and optional expectedToken
POST	/offline	JSON fileData and optional certificatePem
POST	/batch	JSON items array, up to 100 items; each supports token, hash, or fileData, plus optional filename
POST	/batch/export	JSON items and format (csv or pdf)
GET	/{token}/certificate	Verification certificate JSON; ?format=pdf downloads PDF

Read the validity fields in the report; HTTP 200 is not a validity verdict. File-based endpoints can transmit document content. See Cryptographic Signing and Verification.

Other references

• Agreement and Workflow API
• Template API
• Account and Organization API
• Search API
• Certificates and Signing API
• Webhooks and REST API Integration
• API Quick Start

Certificate routes include list/detail/default, generate, upload, set-default, and delete. Signing routes include POST /api/v1/signing/seal/{agreementId}, POST /api/v1/signing/batch, and POST /api/v1/signing/verify. CSC-style protocol routes are mounted under /csc/v2 for information, credentials, signature hashes, and timestamps; this does not by itself establish protocol conformance or interoperability. Use approved deployment-specific guidance for key provisioning and signing operations.

Errors and recovery

Most application errors use a nested error object containing code, message, requestId, and usually timestamp and path. Some verification validation errors use a different body. Do not assume a universal success envelope across route families.

HTTP status	Meaning	Recommended handling
400	Invalid JSON, parameters, or input	Correct the request before retrying
401	Missing, invalid, expired, or revoked token	Obtain a valid token through the approved flow
403	Insufficient authorization	Check roles, scopes, and resource access
404	Missing/inaccessible resource or unsupported path/version	Confirm origin, path, version, identifier, and workspace
409	Conflict or duplicate request in progress	Resolve conflicting data or retry the identical idempotent request later
422	State or validation rule prevents the operation	Check agreement state and detailed message
429	Request limited, where enforced	Follow server guidance and reduce traffic
5xx	Server or dependency failure	Record request ID; use bounded retries for safe operations

Keep the response request ID for private support. Do not publish tokens, full private request bodies, or internal error details.