Skip to the content
Get started

API Reference

API reference

Generated from the OpenAPI 3.1 file (version 2026-10-07). Every request needs Authorization: Bearer $DOCUSTAY_KEY; writes take an Idempotency-Key. Download openapi.json.

Documents

Templates you can send

GET/api/v1/documents/templates

Answers

  • 200Approved, current templates.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

List documents

GET/api/v1/documents

Filter by your own reference: `externalId=…`, and `metadata[key]=value` (repeat for more keys; a document must match all).

Parameters

statestring · query
limitinteger · query
cursorstring · query
externalIdstring · query
Only documents with this `externalId`.

Answers

  • 200A page of documents, newest first.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Make a document from words and people

POST/api/v1/documents

People first: each person has a name, an email and (optionally) a role word from the text. The document is left as a **draft** unless `sendNow` is true. Needs an `Idempotency-Key`.

Request body (JSON)

emailobject
Your own wording for the emails about THIS document. The workspace's saved wording (Settings → Email templates) applies underneath; what you give here wins.
metadataobject
Your own key-value text (up to 20 keys; keys 1–40 letters, digits, dot, dash or underscore; values up to 500 characters). Returned in every response and every webhook for this document; never shown to a signer.
externalIdstring
Your own id for this thing, so you can match it to your records. Filter lists with `externalId=`.
titlestringrequired
sourceobjectrequired
A written document: TipTap JSON `{type:"doc",content:[…]}`. Field tags (`fieldTag` with name, type, role, required, autofill, editable, placeholder, tooltip, locked, options, default…), merge chips (`variableChip`; `custom.<key>` chips are the template's questions), and headings with `audience: "sender"` (Sender only: in nothing a signer sees, signs or receives).
peoplearray of objectrequired
factsobject
Merge text: `org.name`, `sender.name`, `custom.<key>` …
variableValuesobject
paperletter | a4
sendobject
descriptionstring
sendNowboolean
Also send it. The same checks as the screen's Send apply (a payment field needs Stripe connected).

Answers

  • 201The document.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

One document and where each person is

GET/api/v1/documents/{id}

Parameters

idstring · pathrequired

Answers

  • 200The document.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 404No such document.
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Download the signed copy

GET/api/v1/documents/{id}/signed.pdf

Parameters

idstring · pathrequired

Answers

  • 200The sealed PDF, with its certificate.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 404Not signed yet, or no such document.
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Send a template to people to sign

POST/api/v1/documents/send

Makes a document from the template, puts each person on their seat and sends it. Needs an `Idempotency-Key` header (8–200 characters): a retry with the same key and body does not send again.

Request body (JSON)

templateIdstringrequired
emailobject
Your own wording for the emails about THIS document. The workspace's saved wording (Settings → Email templates) applies underneath; what you give here wins.
metadataobject
Your own key-value text (up to 20 keys; keys 1–40 letters, digits, dot, dash or underscore; values up to 500 characters). Returned in every response and every webhook for this document; never shown to a signer.
externalIdstring
Your own id for this thing, so you can match it to your records. Filter lists with `externalId=`.
titlestring
messagestring or null
subjectstring
languageen | es | fr | de | pt | it | nl | pl | tr | ru | ar | ja | zh | ko
expiryDaysinteger
embeddedarray of string
Seats signed inside your own app instead of by emailed link (for example ["signer_1"]). Nobody is emailed for these seats: you ask for a session with POST /api/v1/documents/{id}/embed-session and show it on a website you listed under Settings → Developers → Embedding.
partiesarray of objectrequired
One entry for each seat of the template (see GET /api/v1/documents/templates).

Answers

  • 201Sent.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Ask for an AI-written draft

POST/api/v1/documents/ai/draft

Starts a draft and answers at once with a job id; poll `GET /api/v1/documents/ai/jobs/{id}`. The draft is a suggestion for a person to read; nothing is saved or sent. Refused plainly when AI drafting is switched off for the workspace or a limit is reached.

Request body (JSON)

promptstring
briefobject
The wizard's answers (see GET /api/v1/ai/wizard for the questions).
modetemplate | document

Answers

  • 202Started.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Read an AI draft job

GET/api/v1/documents/ai/jobs/{id}

Parameters

idstring · pathrequired

Answers

  • 200The job. When `state` is `done`, `source` is the draft and `patches.notes` lists what to check.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 404No such job.
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

The document's audit log as CSV

GET/api/v1/documents/{id}/audit-log.csv

Parameters

idstring · pathrequired

Answers

  • 200One row per event: time (UTC), event, description, person, document, detail.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 404No such document.
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Remind the people who still have to sign

POST/api/v1/documents/{id}/remind

Parameters

idstring · pathrequired

Request body (JSON)

seatstring
Remind only this seat (for example signer_2). Leave out to remind everyone who is up.

Answers

  • 200Reminded.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 409Nobody is waiting to be reminded.
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Start an embedded signing session for a seat

POST/api/v1/documents/{id}/embed-session

For a seat that was sent in `embedded`. Returns a link that works for one hour and is meant for an iframe or the `<docustay-sign>` element on one of your allowed websites. It is the only way a key can put someone in front of a signing form, and only for seats you marked embedded yourself. Needs an `Idempotency-Key` header.

Parameters

idstring · pathrequired

Request body (JSON)

seatstringrequired
originstringrequired
The website that will show the form; must be on your allowed list.

Answers

  • 200The session.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 409The seat was not sent as embedded, it is not their turn, the website is not allowed, or embedding is off.
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Sign a test document (test mode only)

POST/api/v1/documents/{id}/test-sign

Signs one seat of a **test** document with sample answers, through the same code a person's signature uses: consent, signing order, the audit trail and your webhooks all happen. Only a test key (`dsk_test_…`) may call it, and only on a test document; a live key gets `403`. A seat with a payment field cannot be test-signed: pay it with a Stripe test card.

Parameters

idstring · pathrequired

Request body (JSON)

seatstringrequired
The seat to sign, for example `signer_1`.

Answers

  • 200Signed.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Void a document that is still out for signature

POST/api/v1/documents/{id}/void

Parameters

idstring · pathrequired

Request body (JSON)

reasonstring

Answers

  • 200Voided.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Check a document's words before making it

POST/api/v1/documents/check

Request body (JSON)

sourceobjectrequired
A written document: TipTap JSON `{type:"doc",content:[…]}`. Field tags (`fieldTag` with name, type, role, required, autofill, editable, placeholder, tooltip, locked, options, default…), merge chips (`variableChip`; `custom.<key>` chips are the template's questions), and headings with `audience: "sender"` (Sender only: in nothing a signer sees, signs or receives).
factsobject
peoplearray of object
With people, each person's own merge text is known, as when the document is made.
variableValuesobject
requireSignatureboolean
forTemplateboolean

Answers

  • 200What a person would be told.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

The words, people and choices of a draft

GET/api/v1/documents/{id}/source

Parameters

idstring · pathrequired

Answers

  • 200The draft's source.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Change the words of a draft

POST/api/v1/documents/{id}/revise

A draft is never edited in place: the new words are printed into a NEW draft that takes the people and choices, and the old draft is deleted. **The id changes** (use `id` in the answer). Needs an `Idempotency-Key`.

Parameters

idstring · pathrequired

Request body (JSON)

sourceobjectrequired
A written document: TipTap JSON `{type:"doc",content:[…]}`. Field tags (`fieldTag` with name, type, role, required, autofill, editable, placeholder, tooltip, locked, options, default…), merge chips (`variableChip`; `custom.<key>` chips are the template's questions), and headings with `audience: "sender"` (Sender only: in nothing a signer sees, signs or receives).
factsobject
variableValuesobject
roleMapobject
Old role word → new role word when you renamed a role.

Answers

  • 201The new draft.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Send a draft

POST/api/v1/documents/{id}/send

Sends a draft made with `POST /api/v1/documents`. The same checks as the screen's Send; a payment field needs Stripe connected. Needs an `Idempotency-Key`.

Parameters

idstring · pathrequired

Answers

  • 201Sent.
  • 202A draft-only key: the request waits for a person to approve it in the app. The document is still a draft.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Ask the assistant to change a document

POST/api/v1/documents/ai/edit

Starts an edit job and answers at once; poll `GET /api/v1/documents/ai/jobs/{id}`. The answer is a list of **proposed changes** (`patches.applied`); nothing is changed until you apply the ones you accept with your own copy of the source. If you pass the template's questions in `variables`, `patches.values` carries proposed answers.

Request body (JSON)

requeststringrequired
sourceobjectrequired
A written document: TipTap JSON `{type:"doc",content:[…]}`. Field tags (`fieldTag` with name, type, role, required, autofill, editable, placeholder, tooltip, locked, options, default…), merge chips (`variableChip`; `custom.<key>` chips are the template's questions), and headings with `audience: "sender"` (Sender only: in nothing a signer sees, signs or receives).
modetemplate | document
variablesarray of object

Answers

  • 202Started.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Cancel an AI job

POST/api/v1/documents/ai/jobs/{id}/cancel

Parameters

idstring · pathrequired

Answers

  • 200The job.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

The wizard's questions

GET/api/v1/ai/wizard

The questions the screen's Describe wizard asks, so an integration asks the same ones and sends the answers as `brief` to `POST /api/v1/documents/ai/draft`. Includes the payment questions and the currencies offered.

Answers

  • 200The questions.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Templates

Make a template from HTML with text tags

POST/api/v1/templates/html

Prints your HTML to a PDF and places a field wherever a text tag sits, then keeps the result as a template you can send with `POST /api/v1/documents/send`. Needs an `Idempotency-Key` header.

Request body (JSON)

metadataobject
Your own key-value text (up to 20 keys; keys 1–40 letters, digits, dot, dash or underscore; values up to 500 characters). Returned in every response and every webhook for this document; never shown to a signer.
externalIdstring
Your own id for this thing, so you can match it to your records. Filter lists with `externalId=`.
namestringrequired
htmlstringrequired
HTML with text tags such as {{Tenant signature;type=signature;role=Tenant}}. Scripts, styles, frames, forms and remote addresses are removed; pictures must be data: addresses. Up to 2 MB.
paperletter | a4

Answers

  • 201The template.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Make a template from a file with text tags

POST/api/v1/templates/file

Reads a PDF, Word, Excel, PowerPoint or image file, places a field wherever a text tag is written in it, and keeps the result as a template. Needs an `Idempotency-Key` header.

Request body (JSON)

metadataobject
Your own key-value text (up to 20 keys; keys 1–40 letters, digits, dot, dash or underscore; values up to 500 characters). Returned in every response and every webhook for this document; never shown to a signer.
externalIdstring
Your own id for this thing, so you can match it to your records. Filter lists with `externalId=`.
namestringrequired
fileNamestringrequired
filestringrequired
The file, base64-encoded: a PDF, Word, Excel, PowerPoint or image file with text tags written in it.

Answers

  • 201The template.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Make a template from a document source

POST/api/v1/templates/source

Keeps a document written in the shared editor's format as a template (profile `typeset` by default). Needs an `Idempotency-Key` header.

Request body (JSON)

metadataobject
Your own key-value text (up to 20 keys; keys 1–40 letters, digits, dot, dash or underscore; values up to 500 characters). Returned in every response and every webhook for this document; never shown to a signer.
externalIdstring
Your own id for this thing, so you can match it to your records. Filter lists with `externalId=`.
namestringrequired
sourceobjectrequired
The document source: a ProseMirror/TipTap JSON document (`{type:"doc",content:[…]}`) using headings, paragraphs, lists, tables, `fieldTag`, `signatureBlock`, `variableChip`. See the guide on document sources.
profiletypeset | contract
paperletter | a4

Answers

  • 201The template.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

One template and its seats

GET/api/v1/templates/{id}

Parameters

idstring · pathrequired

Answers

  • 200The template.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 404No such template.
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Use a written template for people

POST/api/v1/templates/{id}/documents

Makes a document from a template made with `POST /api/v1/templates/source`: the people, the template's questions answered in `variableValues` (see `GET /api/v1/templates/{id}`), the template's own defaults first. A draft unless `sendNow`. Needs an `Idempotency-Key`.

Parameters

idstring · pathrequired

Request body (JSON)

emailobject
Your own wording for the emails about THIS document. The workspace's saved wording (Settings → Email templates) applies underneath; what you give here wins.
metadataobject
Your own key-value text (up to 20 keys; keys 1–40 letters, digits, dot, dash or underscore; values up to 500 characters). Returned in every response and every webhook for this document; never shown to a signer.
externalIdstring
Your own id for this thing, so you can match it to your records. Filter lists with `externalId=`.
titlestring
peoplearray of objectrequired
variableValuesobject
factsobject
sendobject
sendNowboolean

Answers

  • 201The document.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Set what a document made from a template starts with

POST/api/v1/templates/{id}/defaults

Parameters

idstring · pathrequired

Request body (JSON)

descriptionstring or null
clientDescriptionstring or null
messagestring or null
sendobject

Answers

  • 200Saved.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Account

Documents and emails used against your plan

GET/api/v1/usage

Documents sent this calendar month (UTC) and emails sent today, with the plan's limits. `limit` is null when the plan has no limit.

Answers

  • 200Usage.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Is Stripe ready to take a payment?

GET/api/v1/payments/status

`connected` (details submitted, charges on, nothing due), `needs_attention` (Stripe still needs information) or `not_connected`. A document with a payment field can only be sent when this says `connected`.

Answers

  • 200The status.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Reports

Counts of what was sent and completed

GET/api/v1/reports

Real documents only — documents made in test mode are never counted. Dates are in the workspace's own time zone; `to` is inclusive; the default window is the last 30 days.

Parameters

fromstring · query
tostring · query
teamstring · query

Answers

  • 200The report.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Teams

Teams and their members

GET/api/v1/teams

Answers

  • 200The teams.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Email

The workspace's email wording

GET/api/v1/email-templates

Parameters

localestring · query

Answers

  • 200The eight message types with the standard and the saved wording.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Set the wording of one email

PUT/api/v1/email-templates/{kind}

Variables look like `{{document.title}}`; each message type accepts only its own (see GET). A blank field means the standard wording.

Parameters

kindstring · pathrequired
invitation, reminder, completed, declined, voided, expired, code or receipt

Request body (JSON)

localestring
subjectstring or null
previewstring or null
bodystring or null
buttonLabelstring or null
footerstring or null

Answers

  • 200The saved wording.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Back to the standard wording

DELETE/api/v1/email-templates/{kind}

Parameters

kindstring · pathrequired
invitation, reminder, completed, declined, voided, expired, code or receipt
localestring · query

Answers

  • 200The standard wording again.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Preview an email with made-up names

POST/api/v1/email-templates/{kind}/preview

Parameters

kindstring · pathrequired
invitation, reminder, completed, declined, voided, expired, code or receipt

Request body (JSON)

localestring
subjectstring or null
previewstring or null
bodystring or null
buttonLabelstring or null
footerstring or null

Answers

  • 200Subject, preview line, body and the HTML.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

The log of email about your documents

GET/api/v1/emails

Every email sent about a document, to a person named on it: kind, subject, status (sent, delivered, bounced, complained, failed, paused). Filter by `documentId`, `to`, `status`, `kind`. No bodies, no links.

Parameters

documentIdstring · query
tostring · query
statusstring · query
kindstring · query
limitinteger · query
cursorstring · query

Answers

  • 200A page of emails, newest first.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Plays

List plays

GET/api/v1/plays

The built-in plays and your published ones: name, one-line description, kind and category.

Parameters

kindstring · query
categorystring · query

Answers

  • 200List plays
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Save a play (a new version)

POST/api/v1/plays

`source` is the play file: Markdown with a block of YAML at the top. Every save is a new immutable version; publish it to use it. Data only: a play cannot add tools, run code, send or take payments.

Request body (JSON)

sourcestringrequired

Answers

  • 201Save a play (a new version)
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

One play

GET/api/v1/plays/{name}

Parameters

namestring · pathrequired

Answers

  • 200One play
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Archive a play

DELETE/api/v1/plays/{name}

Parameters

namestring · pathrequired

Answers

  • 200Archive a play
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Check a play without saving it

POST/api/v1/plays/test

A dry run: parses the play file, reports every problem, and shows what the picker and the interview would use. Creates nothing.

Request body (JSON)

sourcestringrequired

Answers

  • 200Check a play without saving it
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Publish a play version

POST/api/v1/plays/{name}/publish

Parameters

namestring · pathrequired

Request body (JSON)

versioninteger

Answers

  • 200Publish a play version
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Copy a play under a new name

POST/api/v1/plays/{name}/duplicate

Parameters

namestring · pathrequired

Request body (JSON)

asstring

Answers

  • 201Copy a play under a new name
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

List playbooks

GET/api/v1/playbooks

Named bundles of plays.

Answers

  • 200List playbooks
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Save a playbook

POST/api/v1/playbooks

Request body (JSON)

namestringrequired
titlestringrequired
descriptionstring
playsarray of stringrequired

Answers

  • 201Save a playbook
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Start a draft from a play

POST/api/v1/drafts

Returns `status: needs_input` with up to 4 questions (each with 2 to 4 options and a `draftRef`) until the play's must-ask questions are answered, then `status: draft` with the new draft's id. Nothing is ever sent: a draft is a draft. Answer with `POST /api/v1/drafts/{draftRef}/answers`.

Request body (JSON)

playstringrequired
titlestring
peoplearray of objectrequired
answersobject
useDefaultsboolean

Answers

  • 200Start a draft from a play
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Answer a play's questions

POST/api/v1/drafts/{draftRef}/answers

Parameters

draftRefstring · pathrequired

Request body (JSON)

answersobjectrequired
useDefaultsboolean

Answers

  • 200Answer a play's questions
  • 400Not valid.
  • 403Not allowed (Pro) or the key lacks the scope.
Show the request

Webhooks

The events a webhook can subscribe to

GET/api/v1/webhooks/topics

Answers

  • 200The event names.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

List webhooks

GET/api/v1/webhooks

Answers

  • 200Your webhook endpoints, newest first.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Add a webhook

POST/api/v1/webhooks

Give an `https` `url` that can be reached from the internet, or `relay: true` for an endpoint that keeps its signed deliveries for `docustay listen` to fetch to your own computer. The signing secret is in the answer **once**. Events are signed with HMAC-SHA256 (Standard Webhooks headers `webhook-id`, `webhook-timestamp`, `webhook-signature`; also `keystone-signature`).

Request body (JSON)

urlstring
relayboolean
namestring
eventTypesarray of stringrequired
From `GET /api/v1/webhooks/topics`.

Answers

  • 201Added. `secret` is shown once.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Remove a webhook

DELETE/api/v1/webhooks/{id}

Parameters

idstring · pathrequired

Answers

  • 200Removed: it receives nothing more. Its past deliveries stay in the record.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Send a test event

POST/api/v1/webhooks/{id}/test

Sends a sample signed event (`test: true` in its payload) to the webhook now and returns the receiver's answer. Nothing is stored and failures here never count toward disabling the webhook.

Parameters

idstring · pathrequired

Request body (JSON)

topicstring

Answers

  • 200What the receiver answered.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Rotate the signing secret

POST/api/v1/webhooks/{id}/rotate

Makes a new secret (shown once). For `windowHours` (default 24) every event is signed with both the new and the old secret, so your receiver can switch without a gap.

Parameters

idstring · pathrequired

Request body (JSON)

windowHoursinteger

Answers

  • 200The new secret.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Recent deliveries

GET/api/v1/webhooks/{id}/deliveries

Parameters

idstring · pathrequired

Answers

  • 200The last 50 delivery attempts, newest first.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Fetch stored deliveries of a relay webhook

GET/api/v1/webhooks/{id}/relay

For `docustay listen`. Returns deliveries stored since `after` (an id from a previous answer; leave out for the newest few), oldest first, each with the exact headers to forward so the signature checks out. Waits up to `wait` seconds (max 25) when there is nothing yet. Kept 24 hours.

Parameters

idstring · pathrequired
afterstring · query
waitinteger or null · query
limitinteger · query

Answers

  • 200Stored deliveries.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Embedding

Start an embedded template builder session

POST/api/v1/embedded/builder-session

Returns a link that works for one hour and is meant for an iframe or the `<docustay-builder>` element on one of your allowed websites. The builder lets the person write a document, drop signature and other fields on it, and save it as a template; the saved template's id comes back to your page in a `saved` event. The link holds a key of its own that can only read and write templates and stops working after an hour. Needs an `Idempotency-Key` header.

Request body (JSON)

originstringrequired
The website that will show the builder; must be on your allowed list.
namestring
A name to start the template with.

Answers

  • 200The session.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request

Start an embedded Scribe session

POST/api/v1/embedded/scribe-session

Returns a link that works for one hour and is meant for an iframe or the `<docustay-scribe>` element on one of your allowed websites. The person picks a play, names who signs, answers a few clickable questions and gets a DRAFT; the draft's id comes back to your page in a `drafted` event. The link holds a key of its own that is draft-only (it cannot send: asking to send files an approval a person decides in Docustay), allows 50 drafts a day and stops working after an hour. Needs an `Idempotency-Key` header.

Request body (JSON)

originstringrequired
The website that will show Scribe; must be on your allowed list.
namestring

Answers

  • 200The session.
  • 400The request is not valid. `message` says which field and why.
  • 401The key is missing, wrong, revoked, or lacks the scope. Every credential failure gets this same answer.
  • 403The key is valid but not allowed to do this (a plan limit, or the action is not permitted for keys).
  • 429Too many requests. Wait `Retry-After` seconds, then try again.
Show the request
CtrlI