# SignatureAPI — for agents

SignatureAPI is an API-first electronic signature platform. You send documents
for signature, recipients sign them, and you get back signed documents plus an
audit log.

## Surfaces

| Use | Surface |
| --- | --- |
| Live operations (create, read, cancel envelopes; read test-mode emails) | MCP — `https://mcp.signatureapi.com/mcp` |
| Writing code against the API | REST — `https://api.signatureapi.com/v1` |
| Exact schemas | OpenAPI — `https://spec.signatureapi.com/openapi.yaml` |
| Reading documentation | Any docs page + `.md` — e.g. `https://signatureapi.com/docs/api/webhooks.md`; index at `https://signatureapi.com/llms.txt` |
| Integrating into an app | `npx skills add signatureapi/skills` |

MCP tools: `create_envelope`, `get_envelope`, `list_envelopes`, `cancel_envelope`,
`delete_envelope`, `mint_upload_url`, `list_emails`, `get_email`,
`search_documentation`.

## Vocabulary

- **Envelope** — the container for documents and recipients. `processing` → `in_progress` → `completed` (or `failed`, `canceled`).
- **Document** — a PDF or DOCX file inside an envelope.
- **Place** — an interactive region on a document (signature, initials, text input, checkbox), bound to one recipient.
- **Recipient** — a `signer`, `approver`, `preparer`, or `automatic_signer`.
- **Ceremony** — one recipient's signing session.
- **Deliverable** — produced when the envelope completes: signed documents plus an audit log.

## Rules

- Authentication is the `X-API-Key` header. Test keys start with `key_test_`, live keys with `key_live_`.
- **Test mode sends no email.** Test envelopes are free, watermarked, and not legally binding. Read what would have been sent with the `list_emails` MCP tool, or at `https://dashboard.signatureapi.com/emails?mode=test`.
- Test and live are separate namespaces. A test envelope is invisible to a live key, and test webhooks only reach test endpoints.
- Request and response properties are `snake_case`.
- Errors are RFC 7807 problem details; `detail` names the offending field. Prefer 422 for validation, 409 for already-final state.
- For `email_link` recipients, the ceremony URL is never returned by the API — possession of the emailed link *is* the authentication. In test mode, reach it through `get_email`.
- `delete_envelope` only works on a final envelope. Cancel first, then delete.

## Two traps

- Some documentation pages are redirect stubs. Their `.md` twin is **0 bytes** — you get silence, not an error. If a `.md` fetch comes back empty, find the real page in `llms.txt`.
- The create-envelope reference page is ~108 KB. Query `https://spec.signatureapi.com/openapi.yaml` instead of loading the page.

## Minimal example

Create a test-mode envelope with one signer and one signature place:

```bash
curl -sS https://api.signatureapi.com/v1/envelopes \
  -H "X-API-Key: $SIGNATUREAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test agreement",
    "documents": [
      {
        "format": "pdf",
        "url": "https://example.com/agreement.pdf",
        "places": [
          { "key": "signer_signature", "type": "signature", "recipient_key": "signer" }
        ]
      }
    ],
    "recipients": [
      { "type": "signer", "key": "signer", "name": "Jane Doe", "email": "jane@example.com" }
    ]
  }'
```

Every place's `recipient_key` must match a recipient's `key`. Places bind to a
`[[place_key]]` marker in the document, or to a fixed position.

## Integrating into an application?

Install the skill — it carries the whole flow, including verifying end to end in
test mode. Install from GitHub, or straight from this site:

```bash
npx skills add signatureapi/skills
npx skills add https://signatureapi.com
```