---
title: API
description: REST API with scoped keys, idempotent writes, signed webhooks and an OpenAPI 3.1 file.
---

# The API

Scoped keys, an Idempotency-Key header on writes, Standard Webhooks signatures with retries and replay, an OpenAPI 3.1 file at /api/v1/openapi.json.

## What it covers

Send a document from a template, list and read documents and templates, download the signed copy, read the audit log as CSV, send a reminder, void a document, start an embedded signing session, make a template from HTML or a file, and read reports and teams.

## Keys and scopes

Keys have two scopes: documents:read and documents:write. A key can only carry scopes its creator holds. A request with a missing or wrong key or scope gets the same 401 answer, so nothing tells a guesser which half was right.

## Writes you can safely retry

Requests that create a document or a template (send, make a template from HTML or from a file) need an Idempotency-Key header. Repeating a request with the same key and body returns the first answer instead of acting again, so a timeout never means two emails.

## Lists and errors

Lists take limit and cursor. Errors have one shape with a kind, a message, a request id and a retryable flag. The documentation page on errors and limits has the full table.

## List executed documents

```
curl "https://docustay.app/api/v1/documents?state=executed&limit=20" \
  -H "Authorization: Bearer $DOCUSTAY_KEY"
```

## Keep reading

- [Developers](/developers)
- [Docs: authentication](/docs/authentication)
- [Docs: errors and limits](/docs/errors-and-limits)
- [Docs: webhooks](/docs/webhooks)
- [SDKs](/developers/sdks)