Reference
Cheat sheet
Every common SignatureAPI operation as a CLI command and as a curl request, side by side, for envelopes, recipients, events, deliverables, and uploads.
Each operation below shows the CLI command and the matching REST API request with curl. Both send the same request.
The curl requests read the key from SIGNATUREAPI_KEY, the variable init writes. Export it from your env file first, for example with set -a; . ./.env; set +a. The CLI acts in test mode unless you pass --mode live or use a live key; curl acts in the mode of the key you send.
envelope.json is a Create an envelope body, such as the one in Request bodies.
Envelopes
Create and send an envelope
npx signatureapi envelopes create --body envelope.jsoncurl -X POST https://api.signatureapi.com/v1/envelopes \
-H "X-API-Key: $SIGNATUREAPI_KEY" \
-H "Content-Type: application/json" \
-d @envelope.jsonList envelopes
npx signatureapi envelopes list --status completed --limit 20curl "https://api.signatureapi.com/v1/envelopes?status=completed&limit=20" \
-H "X-API-Key: $SIGNATUREAPI_KEY"For the next page, pass the result’s next_cursor to the CLI as --cursor, or follow links.next with curl.
Get an envelope
npx signatureapi envelopes get eb4cf433-a8af-4161-b37b-7ef57d423e56curl https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56 \
-H "X-API-Key: $SIGNATUREAPI_KEY"Cancel an envelope
The CLI asks for confirmation before it cancels or deletes. In a script, add --yes.
npx signatureapi envelopes cancel eb4cf433-a8af-4161-b37b-7ef57d423e56 --reason "Replaced by a new version"curl -X POST https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56/cancel \
-H "X-API-Key: $SIGNATUREAPI_KEY" \
-H "Content-Type: application/json" \
-d '{"reason": "Replaced by a new version"}'Delete an envelope
Only a completed, canceled, or failed envelope can be deleted.
npx signatureapi envelopes delete eb4cf433-a8af-4161-b37b-7ef57d423e56curl -X DELETE https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56 \
-H "X-API-Key: $SIGNATUREAPI_KEY"Recipients
Resend a signing request
npx signatureapi recipients resend re_49r1R2jpPDz8hSpP75ZkPpcurl -X POST https://api.signatureapi.com/v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/resend \
-H "X-API-Key: $SIGNATUREAPI_KEY"Replace a recipient
npx signatureapi recipients replace re_49r1R2jpPDz8hSpP75ZkPp --name "John Smith" --email john.smith@example.comcurl -X POST https://api.signatureapi.com/v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/replace \
-H "X-API-Key: $SIGNATUREAPI_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "John Smith", "email": "john.smith@example.com"}'Create a ceremony
ceremony.json is a Create a ceremony body, such as {"authentication": [{"type": "email_link"}]}.
npx signatureapi recipients ceremony re_49r1R2jpPDz8hSpP75ZkPp --body ceremony.jsoncurl -X POST https://api.signatureapi.com/v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies \
-H "X-API-Key: $SIGNATUREAPI_KEY" \
-H "Content-Type: application/json" \
-d @ceremony.jsonEvents and deliverables
List an envelope’s events
npx signatureapi events list --envelope eb4cf433-a8af-4161-b37b-7ef57d423e56curl https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56/events \
-H "X-API-Key: $SIGNATUREAPI_KEY"List an envelope’s deliverables
npx signatureapi deliverables list --envelope eb4cf433-a8af-4161-b37b-7ef57d423e56curl https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56/deliverables \
-H "X-API-Key: $SIGNATUREAPI_KEY"Get a deliverable
npx signatureapi deliverables get del_6FF89lKNyTNamOJCJd1tLLcurl https://api.signatureapi.com/v1/deliverables/del_6FF89lKNyTNamOJCJd1tLL \
-H "X-API-Key: $SIGNATUREAPI_KEY"Uploads
Upload a document
npx signatureapi uploads create contract.pdfcurl -X POST https://api.signatureapi.com/v1/uploads \
-H "X-API-Key: $SIGNATUREAPI_KEY" \
-H "Content-Type: application/pdf" \
--data-binary @contract.pdfUse the returned url as a document’s url in envelope.json. Uploads expire after 24 hours.
Inspect an upload
npx signatureapi uploads inspect upl_3JJz6t1o8A5YjX5VpnX27Zcurl https://api.signatureapi.com/v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z/structure \
-H "X-API-Key: $SIGNATUREAPI_KEY"CLI only
These commands have no curl equivalent: they set up your machine rather than call one API operation.
| Task | Command |
|---|---|
Write the test API key into .env | npx signatureapi init |
| Write a new live key into another file | npx signatureapi init --mode live --env-path .env.live |
| List API keys | npx signatureapi api-keys list |
| Roll the test key | npx signatureapi api-keys roll key_... --mode test --replace |
| Receive test webhooks at a local handler | npx signatureapi listen --forward-to http://127.0.0.1:3000/webhooks |
| Send an example event to the listener | npx signatureapi trigger envelope.completed |
| Show the account the CLI acts for | npx signatureapi whoami |
| Set up a coding agent | npx signatureapi agent setup --skills --mcp --agent claude-code --yes |
Add --json to any command for machine-readable output. The full option list for each command is in Resources and in npx signatureapi <command> --help.