Core concepts

Request IDs, versioning and conventions

The rules every endpoint follows, so you can write one HTTP layer for the whole API.

Base URL#

https://api.sign.yt/v1

The same API also answers as https://sign.yt/api/v1 and on every organization's verified custom domain under /api/v1. Requests and responses are JSON (application/json, UTF-8) except PDF uploads (multipart/form-data) and file downloads (application/pdf, image/png, text/csv, ZIP).

Versioning#

The major version is part of the path: /api/v1. Within v1 changes are additive:

New endpoints, new optional request fields, new response fields, new enum values, new error code strings and new webhook event types can appear at any time.
Existing fields are not removed or renamed and their types do not change within v1. Breaking changes ship as a new major version with a migration period.

Build tolerant clients: ignore unknown JSON fields, treat unknown enum values gracefully, and do not fail on unknown webhook events. Notable changes are listed in the changelog.

Request IDs#

Every response carries an X-Request-Id header, and every error body repeats it as request_id. Include it when you contact support; it identifies the request in our logs.

You may send your own X-Request-Id (8-64 characters from A-Z a-z 0-9 _ -) to correlate with your logs; a valid value is echoed back, anything else is replaced by a generated ID.

curl -sS -i "https://api.sign.yt/v1/documents?limit=1" \
  -H "Authorization: Bearer $SIGNYT_API_KEY" \
  -H "X-Request-Id: billing-sync-20261019-0001"
# X-Request-Id: billing-sync-20261019-0001

Status codes#

Status	Used for
`200 OK`	Reads and updates that return the resource.
`201 Created`	Resource created (`POST /documents`, `POST /templates`, `POST /templates/{id}/use`, `POST /webhooks`, `POST /flows`, ...).
`202 Accepted`	Queued for asynchronous processing, for example webhook redelivery.
`204 No Content`	Deletes and actions without a body (for example resending an invite).
`4xx` / `5xx`	Errors, always with the error envelope.

Datetimes and IDs#

Timestamps are ISO 8601 / RFC 3339 strings in UTC, for example 2026-10-19T09:12:44.123456Z or 2026-10-19T09:12:44.123456+00:00. Parse both forms; fractional seconds may be present.
When you send timestamps (such as expires_at), include an offset. Values without one are treated as UTC.
Resource IDs are UUIDs, returned as strings. Treat them as opaque.
Enum values are upper-case strings (PENDING, SIGNER, EMAIL_OTP). Webhook event names are lower-case dotted strings (document.completed).
Field positions are percentages of the page, measured from the top-left corner.

OpenAPI#

The machine-readable spec is at /openapi.json and rendered in the API reference. Multipart endpoints take a JSON string in their payload part; its shape is documented in the guides (for example document creation).