{ "openapi": "3.1.0", "info": { "title": "Signclad API", "version": "1.0.0", "summary": "eSignature API for documents, templates, bulk sends, and webhooks.", "description": "Signclad's `/api/v1` is the single source of truth for request validation, reference\ndocumentation, generated SDKs, and MCP tool schemas.\n\n## Compatibility\n\nEvery operation that is **not** marked `x-signclad-extension: true` is wire-compatible with\nthe third-party API described in `docs/compatibility-reference.md`: same paths, methods,\nrequest fields, response fields, status strings, error envelopes, and webhook event names.\nA client that works against that API works against Signclad after changing the base URL and\nthe API key.\n\nBehavior that OpenAPI cannot express, and that Signclad guarantees anyway:\n\n- **Trailing slashes.** Every path routes with and without a trailing slash\n (`/documents/{id}` and `/documents/{id}/`).\n- **Unknown keys are ignored.** No request is ever rejected for carrying a property this\n document does not define. Every request body schema is `additionalProperties: true`.\n- **`metadata` values are strings.** Up to 50 pairs, key under 40 characters, value under\n 500 characters.\n- **`completed_pdf` returns 404**, not 403, until every signer has finished.\n- **Status casing** is returned exactly as the enums in this document spell it.\n\n## Roles, capabilities, and plans\n\nEvery request resolves to an actor and a workspace. A **role** grants capabilities:\n\n| Capability | owner | admin | member | viewer |\n|---|---|---|---|---|\n| `view_documents` | ✓ | ✓ | ✓ | ✓ |\n| `send_documents` | ✓ | ✓ | ✓ | – |\n| `manage_templates` | ✓ | ✓ | ✓ | – |\n| `manage_members` | ✓ | ✓ | – | – |\n| `manage_settings` | ✓ | ✓ | – | – |\n| `manage_billing` | ✓ | – | – | – |\n\nAn **API key acts as an admin** — `GET /me` reports `role: admin` for one, and compatibility\nclients depend on that — but never gets `manage_billing`: a leaked integration key must not be\nable to cancel the subscription, transfer ownership, or delete a workspace. A missing\ncapability is `403 insufficient_permissions` with the capability named. A feature the plan does\nnot include is `422 not_available_on_plan`; an account behind on billing is\n`422 account_read_only`; templates over the plan's cap are `422 template_read_only` rather than\ndeleted.\n\n## Extensions\n\nOperations, parameters, and response fields marked `x-signclad-extension: true` are additive.\nThey never change the behavior of a compatibility request that does not use them. Extension\noperations are grouped under the `Extensions` tag.\n\n## Headers\n\n| Header | Direction | Meaning |\n|---|---|---|\n| `X-Api-Key` | request | API key. Sandbox keys are prefixed `sk_test_`, live keys `sk_live_`. |\n| `Api-Version` | request | Dated API version, e.g. `2026-09-09`. **Not yet implemented**: nothing reads it and no response returns one. |\n| `Idempotency-Key` | request | Safe retry for any `POST`/`PATCH`/`PUT`. Scoped to **credential** + method + path — an API key, an OAuth token or a session each get their own — and kept 24 hours. A replayed response carries `Idempotent-Replay: true`. |\n| `X-Signclad-Source` | request | Provenance — `mcp` or `zapier`, nothing else. Validated on **every** request, so an unrecognized value is `422 errors.source` whatever the route. It sets `documents.source` and affects nothing else. |\n| `X-Workspace-Id` | request | For a session caller in several workspaces, which one this request is for. A workspace the caller is not a live member of is ignored rather than refused, and their current workspace is used. Ignored for API keys, which belong to one workspace already. |\n| `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset` | response | On every `/api/v1` response. The root-mounted routes — sign-in, OAuth, SSO, SCIM — use their own named limiters and carry none of these. `x-ratelimit-reset` is an **ISO 8601 timestamp** (`2026-09-09T20:56:00+00:00`), not a number of seconds. |\n| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | response | Additive mirror of the three above, with `RateLimit-Reset` as seconds. |\n| `Retry-After` | response | On every `429`. Nothing sets it on a `503`. `meta.retry_after` appears only on a lockout. |\n| `X-Request-Id` | response | A plain UUID v4, present on every response and echoed in error bodies as `request_id`. Send your own — as `X-Request-Id` or the lowercase `request_id` — and it is used instead, so your trace and ours share an id. |\n\nRate limits are per minute and the bucket is chosen by the request, not configured per route.\nAn integration — an API key or an OAuth token — sees three of them: **120** general, **10**\nfor creates and mutations, and **50** unauthenticated. The create bucket is charged even when\nthe create fails, so a run of `422`s exhausts it.\n\nTwo details of that split are easy to get wrong. **`DELETE` is charged to the general bucket**,\nnot the create one: the tight bucket exists to slow document creation down, and a client\ncleaning up after a failed batch should not exhaust its create budget doing so. And **`POST\n/files` has its own `upload` bucket of 120**, because each file in a batch is a separate\nrequest and uploads must not spend the document-creation allowance before a draft can be made.\n\nA browser session is metered separately, so ordinary app usage never competes with an\nintegration's allowance: **300** for general app requests, **10** for unsafe `/security/*`\ncalls, and **60** for `POST /activity` telemetry. Sign-in itself has its own named limiters.\n\n## Status on a create response\n\nA create or send response carries a **transient** status, not the settled one. `POST\n/documents` and `POST /document_templates` always answer `Created`, whatever `draft` was;\n`POST /documents/{id}/send` and `POST /document_templates/documents` always answer `Draft`.\nThe real status appears on subsequent `GET`s. An emailed document may remain `Sending`\nwhile its provider hand-off is pending before it becomes `Sent`; drafts and templates\nsettle to `Draft` or `Available`. Do not drive a state machine off the create response.\n\n## Authentication\n\n- `ApiKey` — `X-Api-Key: `. The default for server-to-server use.\n- `OAuth2` — authorization code with PKCE, or client credentials, on the API's own origin.\n Discover the endpoints at `/.well-known/oauth-authorization-server`. A token is scoped to one\n workspace and one audience.\n- `SignerSession` — a short-lived bearer token held by the signer app. It is the only scheme\n accepted by the `Signer` operations and is never accepted anywhere else.\n- `Session` — the browser session Signclad's own web app holds. Not for integrations, but\n listed on every operation that accepts it, because a large part of this surface acts on a\n person and refuses an API key.\n\nEvery operation carries its own `security` block. Read it rather than assuming the document's\ndefault: the scope an OAuth token needs varies by family — `documents:*`, `templates:*`,\n`webhooks:*`, `account:read` — and a good deal of the surface is reachable by **no** scope at\nall, which is why those operations list no `OAuth2` alternative.\n", "contact": { "name": "Signclad API support", "url": "https://signclad.com/support", "email": "api@signclad.com" }, "license": { "name": "Proprietary", "url": "https://signclad.com/terms" }, "termsOfService": "https://signclad.com/terms" }, "externalDocs": { "description": "Signclad developer documentation", "url": "https://developers.signclad.com" }, "servers": [ { "url": "https://api.signclad.com/api/v1", "description": "Production. Sandbox is a property of the key (`sk_test_`), not a separate host." } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Documents", "description": "Create, send, inspect, and download documents." }, { "name": "Templates", "description": "Reusable documents with placeholders instead of recipients." }, { "name": "Bulk sends", "description": "Send one or more templates to many recipients from a CSV." }, { "name": "Hooks", "description": "Compatibility webhook registration. One callback URL receives every event." }, { "name": "API applications", "description": "Embedded branding and callback configuration for partner applications." }, { "name": "Account", "description": "The authenticated membership, its user, account, and workspace." }, { "name": "Extensions", "description": "Additive Signclad operations. Not part of the compatibility surface; every one of them is\nmarked `x-signclad-extension: true` and is safe to ignore.\n" }, { "name": "Files", "description": "Upload a file once and reference it by id everywhere a file is accepted." }, { "name": "Accounts", "description": "Workspaces, members and invitations, API keys, billing, and the workspace audit log. Every\noperation here is an extension; no compatibility client calls any of it.\n" }, { "name": "Security", "description": "The authenticated half of identity: MFA enrolment, passkeys, recovery codes, the session\nlist, and the security event log. An API key authenticates but is refused — a key is a\ncredential, not a person.\n" }, { "name": "Authentication", "description": "Sign-in itself: register, log in, log out, Google, magic links, password reset, email\nverification. These set and clear a session cookie, live on the API root rather than under\n`/api/v1`, and are not part of the versioned contract.\n" }, { "name": "OAuth", "description": "The OAuth 2.1 authorization server and the SPA's view of it. The protocol endpoints live on\nthe API root, unversioned, because the RFCs are their contract and the metadata document\nadvertises them there.\n" }, { "name": "Branding", "description": "Workspace branding and API application branding — the same three layers, two surfaces." }, { "name": "Template links", "description": "The public fill link, and the settings behind it." }, { "name": "Admin", "description": "Staff-only. Every route answers `404` to everyone else, so the existence of the surface is\nnever confirmed to a stranger.\n" }, { "name": "Signer", "description": "The API the signer app (`app.signclad.com/sign/...`) calls with a signer session bearer token.\nDocumented for completeness; it is not part of the public integration surface and is not\nreachable with an API key.\n" } ], "paths": { "/documents": { "post": { "tags": [ "Documents" ], "operationId": "createDocument", "summary": "Create a document", "description": "Creates a document from one or more files and sends it for signature. `draft: true`\nkeeps it editable and returns a document-level `embedded_edit_url` instead of sending.\n\nReturns `201` immediately with the **transient** status `Created`, whatever `draft`\nwas; subsequent `GET`s report `Draft`, or `Sending` followed by `Sent` once the email\nprovider accepts the initial invitation.\n`files[].pages_number` is `0` in this response and carries the real count on the next\n`GET`; the extension field `files[].status` is `processing` until ingest finishes.\nSigning and embedded URLs are valid straight away.\n\nUnknown properties are dropped silently: they are neither rejected nor echoed back.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SourceHeader" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreateRequest" }, "examples": { "simple": { "$ref": "#/components/examples/DocumentCreateSimple" }, "embeddedDraft": { "$ref": "#/components/examples/DocumentCreateEmbeddedDraft" } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "examples": { "created": { "$ref": "#/components/examples/DocumentCreated" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "Extensions", "Documents" ], "operationId": "listDocuments", "summary": "List documents", "description": "Cursor-paginated list of the workspace's documents, newest first. Replaces polling\ndocuments one id at a time.\n\nThis list sends `total_count`: a second count over the same filters, so tab badges\ndo not need a page walk.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/FilterStatus" }, { "$ref": "#/components/parameters/FilterLabel" }, { "$ref": "#/components/parameters/FilterRecipientEmail" }, { "$ref": "#/components/parameters/FilterUpdatedSince" }, { "$ref": "#/components/parameters/FilterMetadata" }, { "$ref": "#/components/parameters/FilterQuery" }, { "$ref": "#/components/parameters/FilterArchived" }, { "$ref": "#/components/parameters/FilterArchivedOnly" }, { "$ref": "#/components/parameters/FilterTestMode" }, { "$ref": "#/components/parameters/SortBy" }, { "$ref": "#/components/parameters/SortDirection" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/CursorLimit" }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "A page of documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Documents" ], "operationId": "getDocument", "summary": "Get a document", "description": "The full document object, including recipients, fields, and files. This is where the\nsettled status lives: a document that answered `Created` at create reads `Draft` or\n`Sent` here.\n\n`fields` comes back grouped by field type, not in the order it was sent. Address fields\nby `api_id`, never by index.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "examples": { "sent": { "$ref": "#/components/examples/DocumentSent" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "tags": [ "Extensions", "Documents" ], "operationId": "updateDocument", "summary": "Update a draft document", "description": "Updates settings, recipients, and fields on a document that is still a draft. Sending a\ndraft is `POST /documents/{id}/send`; this operation never sends.\n\nReturns `409 document_not_active` when the document has left the draft state — **except**\nfor `archived`. A body that carries nothing but `archived` is applied to a document in any\nstate, including a completed or canceled one, and writes no revision. Archiving is\nfiling, not editing.\n\nA sent document is not frozen, though: a recipient who has not started can still be\ncorrected through `PATCH /documents/{id}/recipients` while the document is `Sent`,\n`Viewed` or `Pending`.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdateRequest" } } } }, "responses": { "200": { "description": "The updated draft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "Documents" ], "operationId": "deleteDocument", "summary": "Delete a document", "description": "Deletes the document and cancels signing that is in progress.", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/send": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "post": { "tags": [ "Documents" ], "operationId": "sendDocument", "summary": "Update and send a draft", "description": "Sends a draft document. Accepts most create-time settings, but not `files`,\n`recipients`, or `fields`; edit those through the builder or `PATCH /documents/{id}`\nbefore sending.\n\nThe response carries the transient status `Draft`; subsequent `GET`s report `Sending`\nuntil the email provider accepts the initial invitation, then `Sent`. Sending also\nregenerates every recipient's `signing_url`, so a URL captured from the draft response\nis dead once this call returns.\n\nReturns `409 document_not_active` when the document is not a draft, and applies none of\nthe settings in the body when it does: the state is checked before anything is written.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSendRequest" }, "examples": { "withMessage": { "summary": "Send with an overridden subject and message", "value": { "subject": "Your loan documents are ready", "message": "

Please review and sign.

", "reminders": true } } } } } }, "responses": { "201": { "description": "Sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/remind": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "post": { "tags": [ "Documents" ], "operationId": "remindDocument", "summary": "Send a reminder", "description": "Reminds recipients who have not finished. Omitting `recipients` reminds every unsigned\nrecipient.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRemindRequest" }, "examples": { "one": { "summary": "Remind one recipient", "value": { "recipients": [ { "email": "jane@example.com", "name": "Jane Doe" } ] } } } } } }, "responses": { "201": { "description": "Reminder queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/recipients": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "patch": { "tags": [ "Documents" ], "operationId": "updateDocumentRecipients", "summary": "Update recipients", "description": "Corrects recipient name and email on a live document. Allowed only while the document is\n`Sent`, `Viewed` or `Pending`, and only for recipients who have not started signing — a\nrecipient who has saved a value or signed is past correcting. Any other state is\n`409 document_not_active`.\n\nThis is how a typo in an address is fixed after sending, and the reason `PATCH\n/documents/{id}` refusing a non-draft is not the end of the story.\n\n`delivery_method` and `phone_number` cannot be changed here. Non-embedded recipients are\ne-mailed again; every updated recipient's old links stop working.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientsUpdateRequest" }, "examples": { "fixTypo": { "summary": "Fix a mistyped address", "value": { "recipients": [ { "id": "signer-1", "name": "Jane Doe", "email": "jane.doe@example.com" } ] } } } } } }, "responses": { "200": { "description": "The updated document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/authentication": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "patch": { "tags": [ "Documents" ], "operationId": "updateDocumentAuthentication", "summary": "Update recipient authentication", "description": "Sets or clears the passcode and passcode delivery for individual recipients.", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationUpdateRequest" }, "examples": { "setPasscode": { "summary": "Add a passcode delivered by email", "value": { "recipients": [ { "id": "signer-1", "passcode": "482913", "passcode_delivery": { "enabled": true, "methods": [ "email" ], "expire_after_access": true } } ] } } } } } }, "responses": { "200": { "description": "The updated document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/completed_pdf": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Documents" ], "operationId": "getCompletedPdf", "summary": "Download the completed PDF", "description": "Returns the sealed PDF bytes, or a short-lived link when `url_only` is true. The bytes\ncome back as `application/pdf` with `content-disposition: inline`, filenamed from the\ndocument name plus each signer's name, lowercased and underscore-joined.\n\nReturns `404` (never `403`) until every signer has finished, so a retry loop can key on\nthe status code alone. That `404` body is byte-identical to the one for a document that\ndoes not exist, so only context distinguishes them.\n\n**Long-term validation is served by default.** A workspace whose plan includes `pades_lt`\ngets the `completed_lt` artifact — the PAdES B-LT/B-LTA enrichment — from this route with\nno parameter, whenever the document has one. There is no opt-in because a customer who\npaid for a file that still verifies in ten years should not have to change their\nintegration to receive it. The substitution is safe: the enrichment is an incremental\nupdate appended after the canonical file's `%%EOF`, so the canonical bytes are a **prefix**\nof what comes back, every signature over them still verifies, and the `completed`\nartifact's SHA-256 still describes the first `source_size` bytes. `GET /verify/{hash}`\nrecognises the enriched file's own hash. See `api/docs/ltv.md`.\n\n`audit_page=false` is unaffected: only the canonical artifact is enriched.\n\nOn a 21 CFR Part 11 document the audit page is part of the record: `audit_page=false` and\n`file_format=zip` answer `422` with `errors.audit_page` or `errors.file_format` keyed\n`not_available_on_cfr_part11` — the artifact asked for is not one this document may\nproduce, and a `404` would not say so.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "parameters": [ { "name": "url_only", "in": "query", "required": false, "description": "Return a JSON object with a short-lived download URL instead of the bytes.", "schema": { "type": "boolean", "default": false } }, { "name": "audit_page", "in": "query", "required": false, "description": "Include the audit page. `false` returns the separately generated and sealed\nno-audit artifact. Cannot be disabled on 21 CFR Part 11 documents.\n", "schema": { "type": "boolean", "default": true } }, { "name": "audit_only", "in": "query", "required": false, "description": "Return the signed `audit.json` — the event chain, the chain head, the revision\nmanifest hash, and the hashes of the PDF artifacts — instead of a PDF.\n", "schema": { "type": "boolean", "default": false }, "x-signclad-extension": true }, { "name": "file_format", "in": "query", "required": false, "description": "`pdf` returns one PDF. `zip` returns the sealed PDF, per-file variants, requested\nattachments, and the signed `audit.json`.\n", "schema": { "type": "string", "enum": [ "pdf", "zip" ], "default": "pdf" } } ], "responses": { "200": { "description": "The completed file, or its URL when `url_only=true`.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CompletedPdfUrl" }, "examples": { "urlOnly": { "summary": "url_only=true", "value": { "completed_pdf_url": "https://files.signclad.com/signed/8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60.pdf?expires=1789050000&signature=...", "audit_trail_url": "https://files.signclad.com/audit/8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60.json?expires=1789050000&signature=...", "expires_at": "2026-09-09T18:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The document does not exist for this workspace, or it is not complete yet. Both\ncases share this body.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notComplete": { "summary": "Byte-identical to the 404 for a document that does not exist", "value": { "message": "Not found", "meta": { "error": "record_not_found", "message": "Couldn't find the document requested", "messages": [ "Couldn't find the document requested" ] } } } } } } }, "422": { "description": "The artifact asked for cannot exist for this document — `errors.audit_page` or\n`errors.file_format` keyed `not_available_on_cfr_part11` on a Part 11 document.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorBody" }, "examples": { "part11": { "value": { "errors": { "audit_page": { "not_available_on_cfr_part11": "The audit page is part of the record on a 21 CFR Part 11 document." } } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/completed/download": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Documents" ], "operationId": "downloadCompletedCopy", "summary": "Download the completed PDF from a signed email link", "description": "The completed copy, for whoever it was emailed to. **Unauthenticated** — the signature in\nthe query string is the whole credential, which is what makes it usable by a signer, who\nhas no Signclad account and no session.\n\nThe HMAC covers the document id, the `audience` and the `expires` value together, so a\nforwarded link cannot be re-aimed at another document, another recipient, or a later\nexpiry. It is minted by the completed-copy email and nowhere else; there is no endpoint\nthat issues one on request.\n\nOnly the canonical `completed` artifact is served. `file_format`, `audit_only`,\n`audit_page` and the long-term-validation substitution are all choices for\n`GET /documents/{id}/completed_pdf`, which takes a credential and can afford them.\n\nEvery failure is the same `404`, byte-identical to the one for a document that does not\nexist: a bad signature, a tampered `audience`, an expired link, an unsealed document and\nan unknown id are indistinguishable from outside.\n", "x-signclad-extension": true, "security": [], "parameters": [ { "name": "audience", "in": "query", "required": true, "description": "Who the copy was addressed to — a recipient id, an email address, or `copy`. Covered by the signature.", "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": true, "description": "Unix timestamp after which the link stops working. Covered by the signature.", "schema": { "type": "integer", "format": "int64" } }, { "name": "signature", "in": "query", "required": true, "description": "HMAC-SHA256 over the path, `audience` and `expires`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The sealed PDF bytes.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Bad or expired signature, tampered `audience`, unknown document, or a document that is\nnot sealed. All of them share this body.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "anyFailure": { "summary": "Byte-identical whatever went wrong", "value": { "message": "Not found", "meta": { "error": "record_not_found", "message": "Couldn't find the document requested", "messages": [ "Couldn't find the document requested" ] } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/nom151_certificate": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Documents" ], "operationId": "getNom151Certificate", "summary": "Download the NOM-151 constancia", "description": "Mexico NOM-151 constancia de conservación for a completed document, issued by a\ncertification service provider after sealing.\n\nThree answers, from one `200`: the ZIP bytes by default, a link with `url_only`, or the\nparsed constancia with `object_only`. `url_only` wins if both are set.\n\nThe order of the refusals is the contract, and each means something different to act on. A\ndocument in another workspace is `404` before anything else. Then, in order:\n\n- `422 not_available_on_plan` — the plan does not carry NOM-151. Unchanged from before the\n feature shipped, so a client written against that answer keeps working.\n- `422 not_enabled` — the plan carries it and the workspace has not switched it on. This\n never becomes true by retrying; somebody has to change a setting.\n- `422 certificate_unavailable` — switched on, and the constancia is not issued **yet**. The\n only one of the three worth retrying.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "parameters": [ { "name": "url_only", "in": "query", "required": false, "description": "Return a JSON object with a short-lived download URL instead of the bytes.", "schema": { "type": "boolean", "default": false } }, { "name": "object_only", "in": "query", "required": false, "description": "Return the parsed constancia object instead of the file.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The constancia. A ZIP by default — it holds the certificate, the certified file, and the\nchain — a link with `url_only`, or the parsed object with `object_only`.\n", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Nom151Certificate" }, { "type": "object", "additionalProperties": true, "properties": { "file_url": { "type": "string", "format": "uri" } }, "required": [ "file_url" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "One of three, under `errors.base`: `not_available_on_plan` (with `meta.feature`),\n`not_enabled`, or `certificate_unavailable`. Only the last is worth retrying.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorBody" }, "examples": { "notOnPlan": { "value": { "errors": { "base": { "not_available_on_plan": "This feature is not available on your plan." } }, "meta": { "feature": "nom151" } } }, "notEnabled": { "value": { "errors": { "base": { "not_enabled": "NOM-151 conservation is not enabled for this workspace. Turn it on in compliance settings." } } } }, "notIssuedYet": { "value": { "errors": { "base": { "certificate_unavailable": "A NOM-151 conservation certificate has not been issued for this document yet." } } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/events": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Extensions", "Documents" ], "operationId": "listDocumentEvents", "summary": "List document events", "description": "The document's audit trail: every event with its sequence, actor, IP, user agent, and\nhash-chain link. The same rows that produce the audit page and `audit.json`.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "required": false, "description": "Events per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "type", "in": "query", "required": false, "description": "Filter to one or more event types.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "A page of events, oldest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentEventList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/attachments": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Extensions", "Documents" ], "operationId": "listDocumentAttachments", "summary": "List uploaded attachments", "description": "Files that recipients uploaded to satisfy `attachment_requests`.", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The attachments.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "post": { "tags": [ "Extensions", "Documents" ], "operationId": "cancelDocument", "summary": "Cancel a document", "description": "Stops signing and moves the document to `Canceled` without deleting it, so the audit\ntrail survives. `DELETE /documents/{id}` cancels and deletes.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "The canceled document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/complete": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "post": { "tags": [ "Extensions", "Documents" ], "operationId": "completeDocument", "summary": "Mark a document manually completed", "description": "Ends signing early and seals what has been signed so far. The document's status becomes\n`Manually completed` and the reason is recorded in the audit trail.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteRequest" } } } }, "responses": { "200": { "description": "The completed document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/recipients/{recipient_id}/reassign": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/RecipientId" } ], "post": { "tags": [ "Extensions", "Documents" ], "operationId": "reassignRecipient", "summary": "Reassign a recipient", "description": "Hands a recipient's turn to somebody else. The original recipient's links stop working,\na new recipient row is created with `reassigned_from`, and the reassignment is recorded\nin the audit trail. Allowed only while `allow_reassign` is true and the recipient has\nnot signed.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignRequest" }, "examples": { "toColleague": { "value": { "name": "Sam Rivera", "email": "sam@example.com", "reason": "Jane is out of office" } } } } } }, "responses": { "201": { "description": "The new recipient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recipient" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/recipients/{recipient_id}/signing_url": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/RecipientId" } ], "post": { "tags": [ "Extensions", "Documents" ], "operationId": "createRecipientSigningUrl", "summary": "Regenerate a signing URL", "description": "Issues a fresh single-use embedded signing URL for one recipient. This is the only\nregeneration route; there is no `GET`. Hosts call it instead of recreating the document\nevery time somebody opens their portal.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningUrlRequest" } } } }, "responses": { "201": { "description": "A new signing URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningUrlResult" }, "examples": { "created": { "value": { "embedded_signing_url": "https://app.signclad.com/sign/embedded/4f8c1b7a2e9d05364c8b1e7a2d9f06354b8c1e7a2d9f06354b8c1e7a2d9f0635", "signing_url": "https://app.signclad.com/sign/4f8c1b7a2e9d05364c8b1e7a2d9f06354b8c1e7a2d9f06354b8c1e7a2d9f0635", "expires_at": "2026-09-09T18:15:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/recipients/{recipient_id}/in_person_session": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/RecipientId" } ], "post": { "tags": [ "Extensions", "Documents" ], "operationId": "createInPersonSession", "summary": "Start an in-person signing session", "description": "Signing in person: the host is standing next to the signer with a tablet and hands it over.\nNo email, no link, nothing to click — which is the point, because the situations this is\nfor are the ones where the signer has no working email in the room.\n\nA write on the **sender's** credential. What comes back is a signer bearer token scoped to\nexactly one recipient, with the same lifetime every other signer session has, so the tablet\ncan be handed over without exposing the sender's own session. Present it as\n`Authorization: Bearer ` against `/signer/*`, exactly as a token from\n`POST /signer/exchange`.\n\nThe guards are the link exchange's, minus the two that are about a link: the document has\nto be open, the recipient has to be a signer who has not finished (`409\nrecipient_not_a_signer` / `recipient_not_signable`), and the signing order has to have\nreached them (`403 not_your_turn`). The passcode gate is deliberately **not** applied — a\npasscode proves that the person who received the email is the one opening it, and here the\nhost has identified the signer face to face.\n\nThe session is recorded as a `signer_session_started` event with `source: in_person`, and a\ndocument whose `source` is `web` is promoted to `in_person`. A document created through the\nAPI, a bulk send or a template link keeps the provenance it was created with, so the column\nnever disagrees with the usage row written when it was sent.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "A signer session for the host's device.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InPersonSession" }, "examples": { "created": { "value": { "token": "sgn_sess_9c8f2b1a4d6e5f70819a2b3c4d5e6f70", "token_type": "Bearer", "expires_at": "2026-09-09T18:15:00Z", "scope": "in_person", "document_id": "8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60", "recipient_id": "recipient_1", "session_id": "01J9K3P2S5N7Q8R0T2V4X6Z8A0" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/PlanRestricted" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/embedded_edit_url": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" } ], "post": { "tags": [ "Extensions", "Documents" ], "operationId": "createDocumentEmbeddedEditUrl", "summary": "Regenerate an embedded builder URL", "description": "Issues a fresh single-use `embedded_edit_url` for the document builder. The embed script\nnormally receives a renewal URL from the iframe in its `setId` message; this route is\nfor hosts that lost it.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedEditUrlRequest" } } } }, "responses": { "201": { "description": "A new builder URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedEditUrlResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}/files/{position}": { "parameters": [ { "$ref": "#/components/parameters/DocumentId" }, { "$ref": "#/components/parameters/FilePosition" } ], "put": { "tags": [ "Extensions", "Documents" ], "operationId": "replaceDocumentFile", "summary": "Replace a file on a draft", "description": "Swaps one file of a draft document and re-anchors its fields. Run it once with\n`dry_run: true` to see the report, then again with `dry_run: false` and the\n`expected_revision` the dry run returned.\n\n`PUT /document_templates/{id}/files/{position}` is the template equivalent and behaves\nidentically, against template revisions instead of draft revisions.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileReplaceRequest" }, "examples": { "dryRun": { "$ref": "#/components/examples/FileReplaceDryRun" } } } } }, "responses": { "200": { "description": "The replacement report. Nothing changed when `dry_run` was true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileReplaceResult" }, "examples": { "report": { "$ref": "#/components/examples/FileReplaceReportExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document_templates": { "post": { "tags": [ "Templates" ], "operationId": "createTemplate", "summary": "Create a template", "description": "Same shape as a document, with `placeholders` instead of `recipients` and\n`placeholder_id` on fields. `draft: false` publishes the template; `draft: true` returns\nan `embedded_edit_url` for the template builder.\n\nThe response carries the transient status `Created` in both cases. The settled status\n(`Draft` or `Available`) appears on the next `GET`, and `PUT {draft: false}` moves a\ndraft to `Available`.\n\n`fields` is accepted both as an array of arrays (one inner array per file) and as an\nobject keyed by file and field, for compatibility with clients that build it as a map.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SourceHeader" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreateRequest" }, "examples": { "draftBuilder": { "$ref": "#/components/examples/TemplateCreateDraft" } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" }, "examples": { "created": { "$ref": "#/components/examples/TemplateCreated" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "Extensions", "Templates" ], "operationId": "listTemplates", "summary": "List templates", "description": "Cursor-paginated list of the workspace's templates. `total_count` counts every template\nmatching the filters so navigation badges do not need to fetch and serialize every row.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:read" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/FilterTemplateStatus" }, { "$ref": "#/components/parameters/FilterLabel" }, { "$ref": "#/components/parameters/FilterUpdatedSince" }, { "$ref": "#/components/parameters/FilterMetadata" }, { "$ref": "#/components/parameters/FilterQuery" }, { "$ref": "#/components/parameters/FilterArchived" }, { "$ref": "#/components/parameters/FilterTestMode" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/CursorLimit" } ], "responses": { "200": { "description": "A page of templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document_templates/{id}": { "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "get": { "tags": [ "Templates" ], "operationId": "getTemplate", "summary": "Get a template", "description": "The full template, including `placeholders`, `copied_placeholders`, `template_link`\n(the public fill link, which works even while the template is still a draft) and a\nsingle-use `embedded_edit_url`. `fields` is an array of arrays, one per file, and each\nfield carries `placeholder_name` — never `placeholder_id`.\n\nThis is where a template's settled status lives; a create answered `Created`.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" }, "examples": { "available": { "$ref": "#/components/examples/TemplateAvailable" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "tags": [ "Templates" ], "operationId": "saveTemplate", "summary": "Save a template editor snapshot", "description": "Saves fields and roles atomically with settings and a revision. Fields replace the entire\nfield collection and address roles by `placeholder_name` or `placeholder_id`, and every\nplaceholder must carry its `id` — this is a snapshot of an editor that already knows them,\nnot a create. `draft: true` returns the template to Draft; `false` publishes it.\n\n`files` is a **replacement of the whole ordered set**, by `file_id`, and files dropped from\nit are scheduled for deletion. It takes no new sources: upload through `POST /files` first.\nOmit the key to leave the files alone.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:write" ] }, { "Session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TemplateUpdateRequest" }, { "type": "object", "required": [ "placeholders", "fields" ], "properties": { "placeholders": { "type": "array", "minItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/Placeholder" }, { "type": "object", "required": [ "id" ] } ] } }, "fields": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } } }, "files": { "type": "array", "maxItems": 20, "description": "The ordered file set, replaced wholesale. Files left out are scheduled for\ndeletion. Omit the key to leave the set alone.\n", "items": { "type": "object", "additionalProperties": true, "properties": { "file_id": { "type": "string" }, "name": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "file_id" ] } } } } ] } } } }, "responses": { "200": { "description": "The saved template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "Templates" ], "operationId": "updateTemplate", "summary": "Update template settings", "description": "Settings only; files, placeholders, and fields are edited in the builder.\n\n`labels` and `checkbox_groups` are replaced wholesale by what the request carries.\n`conditional_rules` are upserted by `id`; send `{\"id\": \"...\", \"deleted\": true}` to\nremove one.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUpdateRequest" }, "examples": { "settings": { "summary": "Rename and re-label", "value": { "name": "Loan agreement (2026)", "subject": "Your loan agreement", "expires_in": 30, "labels": [ "loans", "onboarding" ] } } } } } }, "responses": { "200": { "description": "The updated template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "Templates" ], "operationId": "deleteTemplate", "summary": "Delete a template", "description": "Documents already created from the template are unaffected.", "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:write" ] }, { "Session": [] } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document_templates/documents": { "post": { "tags": [ "Templates" ], "operationId": "createDocumentFromTemplate", "summary": "Create a document from templates", "description": "Creates a document from one template (`template_id`) or several composed in order\n(`template_ids`). Exactly one of the two is required.\n\nRecipients are assigned to placeholders by `placeholder_name` and inherit that\nplaceholder's fields and settings. `files` and `fields` are **appended**: they never\nreplace the template's files, and each inner `fields` array belongs to one appended\nfile.\n\nSignatures and initials already applied on the template are copied in as content: they\nstay visible, create no signing event, fire no `document_signed`, and do not change any\nrecipient's status. If the request adds new unsigned signature or initials fields for\nthe same signer, the pre-applied ones are cleared so that signer signs once.\n\nThe response carries the transient status `Draft` whatever `draft` was; the settled\nstatus appears on the next `GET`.\n\nOn a composed document a field's identity is the pair (source template, `api_id`).\nNothing is renamed, every field in the response carries `template_id`, and rule and\ngroup references resolve inside their source template. A `template_fields` entry may be\n`{api_id, value}` when the `api_id` is unique across the templates, and must be\n`{template_id, api_id, value}` when it is not; an ambiguous bare reference is `422`\n`ambiguous_field_reference` and lists the candidates.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SourceHeader" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDocumentCreateRequest" }, "examples": { "fromOneTemplate": { "$ref": "#/components/examples/TemplateDocumentCreate" } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Validation failed. A single bad `template_fields` entry rejects the whole request\nwith `errors.template_fields`, unless `skip_invalid_fields: true` was sent, in\nwhich case the bad entries are dropped and listed in `warnings[]`. A draft or\narchived template cannot spawn a document.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorBody" }, "examples": { "badTemplateField": { "summary": "A bare Y-m-d date, keyed by the field's api_id then by the error code", "value": { "errors": { "template_fields": { "tdate1": { "invalid_date_format": "DateField value must be in Iso8601 format." } } } } }, "unknownTemplate": { "summary": "An unknown template id and an unmatched placeholder, reported together", "value": { "errors": { "template_id": { "not_in_account": "There's no template with id 00000000-0000-0000-0000-000000000000 in your account." }, "recipients": { "recipient_1": { "unexisting_placeholder_name": "This placeholder_name is not present in the template(s): signer." } } } } }, "templateNotFinished": { "summary": "A draft or archived template cannot spawn a document", "value": { "errors": { "template_id": { "not_finished": "Template 3f1c9a2e is present in your account but is not finished." } } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document_templates/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "post": { "tags": [ "Extensions", "Templates" ], "operationId": "duplicateTemplate", "summary": "Duplicate a template", "description": "Copies files, placeholders, fields, checkbox groups, conditional rules, and settings\ninto a new template. Field `api_id`s are preserved, so field mappings keep working.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTemplateRequest" } } } }, "responses": { "201": { "description": "The new template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document_templates/{id}/embedded_edit_url": { "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "post": { "tags": [ "Extensions", "Templates" ], "operationId": "createTemplateEmbeddedEditUrl", "summary": "Regenerate a template builder URL", "description": "Issues a fresh single-use `embedded_edit_url` for the template builder.", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:write" ] }, { "Session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedEditUrlRequest" } } } }, "responses": { "201": { "description": "A new builder URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedEditUrlResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document_templates/{id}/files/{position}": { "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/FilePosition" } ], "put": { "tags": [ "Extensions", "Templates" ], "operationId": "replaceTemplateFile", "summary": "Replace a file on a template", "description": "Swaps one file of a template and re-anchors its fields, producing a new template\nrevision. Dry run first, then commit with the `expected_revision` from the dry run;\na template that changed in between fails with `409 revision_mismatch`.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "templates:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileReplaceRequest" }, "examples": { "commit": { "summary": "Commit against a known revision", "value": { "file_id": "file_01J9K3P2S5N7Q8R1T2V3W4X5", "strategy": "anchors", "scale_to_page": true, "dry_run": false, "expected_revision": 7 } } } } } }, "responses": { "200": { "description": "The replacement report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileReplaceResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/files": { "get": { "tags": [ "Extensions", "Documents" ], "operationId": "listStoredFiles", "summary": "List reusable stored files", "description": "Lists ready original files in the current workspace. Members see files in\naccessible documents and templates; owners, admins, and workspace credentials\nalso see unattached uploads and retained history. Sandbox restrictions apply.\nFiles are returned once, newest first, in pages of 20. No storage is copied.\n`can_delete` is false while any live reference or saved history needs the file.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "A page of reusable files", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "properties": { "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/UploadedFile" }, { "type": "object", "required": [ "can_delete", "delete_blocked_reason" ], "properties": { "can_delete": { "type": "boolean" }, "delete_blocked_reason": { "type": [ "string", "null" ] } } } ] } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Extensions", "Documents" ], "operationId": "uploadFile", "summary": "Upload a file", "description": "Uploads a file once and returns an id usable as `files[].file_id` anywhere `file_url`\nor `file_base64` is accepted. 25 MB per file. The response `status` is `processing`\nuntil ingest finishes; a file may be referenced before it is `ready`.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": true, "properties": { "file": { "type": "string", "format": "binary", "description": "The file bytes." }, "name": { "type": "string", "description": "Display name. Defaults to the uploaded filename." }, "purpose": { "type": "string", "enum": [ "document", "attachment", "import" ], "default": "document" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "The stored file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedFile" }, "examples": { "created": { "value": { "id": "file_01J9K3P2S5N7Q8R1T2V3W4X5", "name": "loan-agreement.pdf", "mime": "application/pdf", "size": 184320, "status": "processing", "pages_number": 0, "created_at": "2026-09-09T17:44:10Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk_sends": { "post": { "tags": [ "Bulk sends" ], "operationId": "createBulkSend", "summary": "Start a bulk send", "description": "Sends one or more templates to every row of a CSV. The CSV columns are\n`_`, plus a name and email column per placeholder; fetch\na matching header row from `GET /bulk_sends/csv_template`.\n\nThe response status starts at `Enqueuing` while rows are turned into documents.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSendCreateRequest" }, "examples": { "fromCsv": { "summary": "One template, base64 CSV", "value": { "name": "Q3 onboarding", "template_ids": [ "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b" ], "bulk_send_csv": "U2lnbmVyX05hbWUsU2lnbmVyX0VtYWlsCkphbmUgRG9lLGphbmVAZXhhbXBsZS5jb20K", "skip_row_errors": false, "subject": "Please sign your onboarding packet", "message": "

This takes about two minutes.

", "apply_signing_order": true } } } } } }, "responses": { "201": { "description": "The bulk send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSend" }, "examples": { "enqueuing": { "$ref": "#/components/examples/BulkSendEnqueuing" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "Bulk sends" ], "operationId": "listBulkSends", "summary": "List bulk sends", "description": "Every bulk send in the workspace, newest first, up to 200. The body is a **bare array**,\nnot a `data` envelope, and takes no pagination parameters.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The bulk sends.", "content": { "application/json": { "schema": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BulkSend" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/PlanRestricted" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk_sends/csv_template": { "get": { "tags": [ "Bulk sends" ], "operationId": "getBulkSendCsvTemplate", "summary": "Get a CSV template", "description": "Returns the header row for the given templates: a `_Name` and\n`_Email` column per placeholder, then one `_`\ncolumn per fillable field. Signature, initials, `autofill_*`, and locked date fields get\nno column — nothing in the CSV could fill them.\n\nThe CSV form carries a UTF-8 byte-order mark so spreadsheet software opens it correctly;\nthe base64 form does not.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "parameters": [ { "name": "template_ids[]", "in": "query", "required": true, "description": "One or more template ids, in the order they will be composed.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "style": "form", "explode": true }, { "name": "base64", "in": "query", "required": false, "description": "Return the CSV base64-encoded inside a JSON object instead of raw text.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The CSV template.", "content": { "text/csv": { "schema": { "type": "string" }, "examples": { "headerRow": { "value": "Signer_Name,Signer_Email,Signer_Full name,Signer_Start date\n" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/BulkSendCsvTemplate" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "There is no id in the path, so a template that does not exist, is not in this\nworkspace, or is not finished is a validation failure rather than a `404`:\n`errors['template_ids.not_found']` and `errors['template_ids.not_finished']` name the\nid. A plan without bulk send answers here too, as `errors.base.not_available_on_plan`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk_sends/validate_csv": { "post": { "tags": [ "Bulk sends" ], "operationId": "validateBulkSendCsv", "summary": "Validate a bulk send CSV", "description": "Dry run. Parses the CSV against the templates and reports per-row errors without\ncreating anything.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:write" ] }, { "Session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSendValidateCsvRequest" } } } }, "responses": { "200": { "description": "The validation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSendValidationResult" }, "examples": { "oneBadRow": { "value": { "valid": false, "rows_count": 42, "valid_rows_count": 41, "row_errors": [ { "row": 17, "column": "Signer_Email", "error": "is not a valid email address", "errors": { "Signer_Email": "is not a valid email address" } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk_sends/{id}": { "parameters": [ { "$ref": "#/components/parameters/BulkSendId" } ], "get": { "tags": [ "Bulk sends" ], "operationId": "getBulkSend", "summary": "Get a bulk send", "description": "Counts and status for one bulk send, plus the templates it used.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The bulk send.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSend" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PlanRestricted" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk_sends/{id}/documents": { "parameters": [ { "$ref": "#/components/parameters/BulkSendId" } ], "get": { "tags": [ "Bulk sends" ], "operationId": "listBulkSendDocuments", "summary": "List a bulk send's documents", "description": "The documents a bulk send produced, page by page. This is the one paginated\ncompatibility endpoint and it uses page numbers, not cursors.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Documents per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "A page of documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSendDocumentsPage" }, "examples": { "firstPage": { "$ref": "#/components/examples/BulkSendDocumentsPageExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PlanRestricted" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/hooks": { "get": { "tags": [ "Hooks" ], "operationId": "listHooks", "summary": "List webhook callbacks", "description": "The workspace's compatibility callbacks. Endpoints created here receive every event and\nare active immediately, with no ping. Signclad's own webhook management, with per-event\nsubscriptions, secrets, health, and delivery logs, is at `/webhook_endpoints`; the same\nendpoints appear in both listings.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The callbacks.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Hook" } }, "examples": { "one": { "value": [ { "id": "6d2f8b31-7a4c-4e19-9c53-0f8a1b2c3d4e", "callback_url": "https://app.example.com/webhooks/signclad" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Hooks" ], "operationId": "createHook", "summary": "Create a webhook callback", "description": "Registers a callback URL. Every event is delivered to it. The `id` is also the key of\nthe compatibility `event.hash`, so store it.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookCreateRequest" }, "examples": { "global": { "value": { "callback_url": "https://app.example.com/webhooks/signclad" } } } } } }, "responses": { "201": { "description": "The callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/hooks/{id}": { "parameters": [ { "$ref": "#/components/parameters/HookId" } ], "delete": { "tags": [ "Hooks" ], "operationId": "deleteHook", "summary": "Delete a webhook callback", "description": "Stops delivery immediately. Undelivered events are dropped.", "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api_applications/{id}": { "parameters": [ { "$ref": "#/components/parameters/ApiApplicationId" } ], "get": { "tags": [ "API applications" ], "operationId": "getApiApplication", "summary": "Get an API application", "description": "Branding and callback configuration for an embedded partner application.\n", "security": [ { "ApiKey": [] }, { "Session": [] } ], "responses": { "200": { "description": "The API application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiApplication" }, "examples": { "app": { "$ref": "#/components/examples/ApiApplicationExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "tags": [ "Extensions", "API applications" ], "operationId": "updateApiApplication", "summary": "Update an API application", "description": "Only the keys present change; a key present and `null` clears it. Colours are hex, origins\nare scheme-and-host, and `default_webhook_id` must name an endpoint in this workspace.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "Session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiApplicationWrite" } } } }, "responses": { "200": { "description": "The updated application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiApplication" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "delete": { "tags": [ "API applications" ], "operationId": "deleteApiApplication", "summary": "Delete an API application", "description": "API applications are created in the web app; there is no create endpoint. Deleting one\ndetaches it from its documents and stops its embedded pages from loading.\n", "security": [ { "ApiKey": [] }, { "Session": [] } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/me": { "patch": { "tags": [ "Extensions", "Account" ], "operationId": "updateMe", "summary": "Update your profile", "description": "Name, locale, and timezone. The address is not here — changing where sign-in links go goes\nthrough `POST /me/email` and needs the password.\n\n`name` and the two halves are kept consistent by one resolver: send `first_name` or\n`last_name` and they win, with `name` recomposed; send only `name` and the halves are\nre-derived by splitting on the first space. People only.\n\nReturns the same body as `GET /me`.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "Session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 120 }, "first_name": { "type": [ "string", "null" ], "maxLength": 60 }, "last_name": { "type": [ "string", "null" ], "maxLength": 60 }, "locale": { "type": [ "string", "null" ], "maxLength": 12, "description": "A language tag such as `en` or `en-GB`." }, "timezone": { "type": [ "string", "null" ], "maxLength": 64, "description": "An IANA name such as `America/Denver`." } } } } } }, "responses": { "200": { "description": "The membership, as `GET /me` returns it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Get the current membership", "description": "The membership the credential resolves to, with its user, account, workspace, and\ncontact. Use it to check which workspace an API key belongs to.\n", "security": [ { "ApiKey": [] }, { "OAuth2": [] }, { "Session": [] } ], "responses": { "200": { "description": "The membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "examples": { "me": { "$ref": "#/components/examples/MeExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook_endpoints": { "get": { "tags": [ "Extensions", "Hooks" ], "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Every endpoint in the workspace, including those registered through the compatibility\n`POST /hooks` route, with subscriptions and current health.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:read" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/CursorLimit" } ], "responses": { "200": { "description": "A page of endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Extensions", "Hooks" ], "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Creates an endpoint with its own signing secret and event subscriptions. The `secret` is\nreturned once, on creation and on rotation, and never again.\n\n`verify: true` sends a `ping` first and activates the endpoint only if it answers `2xx`.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateRequest" }, "examples": { "subscribed": { "value": { "url": "https://app.example.com/webhooks/signclad", "description": "Production receiver", "event_types": [ "document_completed", "document_declined", "document_error" ], "include_test_mode": false, "verify": true } } } } } }, "responses": { "201": { "description": "The endpoint, with its secret shown once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook_endpoints/{id}": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "get": { "tags": [ "Extensions", "Hooks" ], "operationId": "getWebhookEndpoint", "summary": "Get a webhook endpoint", "description": "The endpoint with its subscriptions, health, and delivery metrics.", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "healthy": { "$ref": "#/components/examples/WebhookEndpointExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "tags": [ "Extensions", "Hooks" ], "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Changes the URL, description, subscriptions, test-mode inclusion, or active state.\nPausing an endpoint keeps its events queued for replay; disabling drops them.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdateRequest" } } } }, "responses": { "200": { "description": "The updated endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "Extensions", "Hooks" ], "operationId": "replaceWebhookEndpoint", "summary": "Update a webhook endpoint (PUT alias)", "description": "The same operation as `PATCH`, accepted as `PUT` for clients whose HTTP layer cannot send\na `PATCH`. It is still a partial update: only the properties present are changed.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdateRequest" } } } }, "responses": { "200": { "description": "The updated endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "Extensions", "Hooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Deletes the endpoint and its queued deliveries. Delivery logs are kept 30 days.", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook_endpoints/{id}/rotate_secret": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "post": { "tags": [ "Extensions", "Hooks" ], "operationId": "rotateWebhookEndpointSecret", "summary": "Rotate the signing secret", "description": "Issues a new secret and keeps the old one valid for an overlap window, so both signatures\nverify while the receiver is redeployed. Deliveries during the overlap carry two `v1`\nsignature values, one per secret.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "overlap_hours": { "type": "integer", "minimum": 0, "maximum": 168, "default": 24, "description": "How long the previous secret keeps signing alongside the new one." } } } } } }, "responses": { "201": { "description": "The new secret, shown once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointSecret" }, "examples": { "rotated": { "value": { "id": "6d2f8b31-7a4c-4e19-9c53-0f8a1b2c3d4e", "secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0", "previous_secret_expires_at": "2026-09-10T17:44:10Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook_endpoints/{id}/health": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "get": { "tags": [ "Extensions", "Hooks" ], "operationId": "getWebhookEndpointHealth", "summary": "Get endpoint health", "description": "Current health state and the counters behind it. `healthy` → `degraded` (3 consecutive\nfailures, or over 10% failures in an hour) → `failing` (25 consecutive failures, or 100%\nover 24 hours) → `disabled` (5 days of continuous failure). While `failing`, attempts\nare skipped and the endpoint is probed hourly.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The health record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointHealth" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook_endpoints/{id}/ping": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "post": { "tags": [ "Extensions", "Hooks" ], "operationId": "pingWebhookEndpoint", "summary": "Send a test event", "description": "Delivers a synthetic event synchronously and returns what the endpoint answered. Pass\n`event_type` to send a realistic sample of that event instead of `ping`.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "event_type": { "$ref": "#/components/schemas/EventType" } } } } } }, "responses": { "200": { "description": "The delivery result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPingResult" }, "examples": { "ok": { "value": { "delivered": true, "status_code": 200, "latency_ms": 143, "response_excerpt": "{\"ok\":true}", "delivery_id": "01j9k3p2s5n7q8r1t2v3w4x5" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook_endpoints/{id}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "get": { "tags": [ "Extensions", "Hooks" ], "operationId": "listWebhookDeliveries", "summary": "List deliveries", "description": "The delivery log: every attempt with its request headers and body, response status and\nbody excerpt, and latency. Dead letters are kept 30 days.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:read" ] }, { "Session": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by delivery outcome.", "schema": { "type": "string", "enum": [ "pending", "delivered", "failed", "dead" ] } }, { "name": "event_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/EventType" } }, { "name": "event", "in": "query", "required": false, "description": "Alias of `event_type`, accepted because that is what the field is called in the app.", "schema": { "$ref": "#/components/schemas/EventType" } }, { "name": "document_id", "in": "query", "required": false, "description": "Only deliveries whose event belongs to this document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/CursorLimit" } ], "responses": { "200": { "description": "A page of deliveries. The request body, request headers, and response excerpt are\nomitted here; `GET .../deliveries/{delivery_id}` carries them.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" }, "examples": { "failed": { "$ref": "#/components/examples/WebhookDeliveryExample" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook_endpoints/{id}/deliveries/{delivery_id}/replay": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/DeliveryId" } ], "post": { "tags": [ "Extensions", "Hooks" ], "operationId": "replayWebhookDelivery", "summary": "Replay a delivery", "description": "Re-sends the stored payload. `event.id`, `event.time`, and the body are unchanged, so\nreceivers that dedupe by `event.id` see a duplicate and drop it; the signature timestamp,\n`X-Signclad-Delivery`, and `X-Signclad-Attempt` are fresh.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "webhooks:write" ] }, { "Session": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "The replay was queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/events": { "get": { "tags": [ "Extensions", "Hooks" ], "operationId": "listEventCatalog", "summary": "Get the event catalog", "description": "Every event Signclad emits, what triggers it, and what its `data.object` carries, along\nwith the signature scheme and the retry schedule. Generated from the same table the\ndelivery pipeline validates subscriptions against, so the catalog cannot claim an event\nthat is not deliverable and cannot omit one that is.\n\nEvents a deployment has turned off are absent from the catalog, so subscribe from this\nlist rather than from a hard-coded one.\n", "x-signclad-extension": true, "security": [ { "ApiKey": [] }, { "OAuth2": [ "documents:read" ] }, { "Session": [] } ], "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCatalog" }, "examples": { "catalog": { "value": { "data": [ { "type": "document_completed", "summary": "Every signer has finished and the document is sealed.", "object": "document", "compatibility": true, "carries_related_signer": false } ], "signature": { "header": "X-Signclad-Signature", "scheme": "t=,v1=.\")>", "tolerance_seconds": 300, "compatibility_hash": "hex(hmac-sha256(key = , data = \"@