> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Authentication, conventions, rate limits, and error handling for the DocuTrust API.

# API Overview

The DocuTrust API is a RESTful JSON API for creating templates, managing submissions, and integrating document signing into your applications.

## Base URL

All API requests are made to your DocuTrust instance URL:

```
https://your-app.com/api
```

Replace `your-app.com` with your actual DocuTrust deployment domain.

## Authentication

Authenticate every request by including your API token in the `X-Auth-Token` header:

```bash theme={null}
curl -X GET https://your-app.com/api/templates \
  -H "X-Auth-Token: YOUR_API_TOKEN"
```

API tokens are created in **Settings > API** within the DocuTrust admin panel. Each token can be scoped to specific permissions. See the [Authentication guide](/guides/authentication) for details on creating and managing tokens.

<Warning>
  Never expose your API token in client-side code, public repositories, or browser requests. API tokens should only be used in server-to-server communication.
</Warning>

## Content Types

| Scenario                       | Content-Type          |
| ------------------------------ | --------------------- |
| JSON requests (most endpoints) | `application/json`    |
| File uploads                   | `multipart/form-data` |
| Responses                      | `application/json`    |

All request bodies must be valid JSON unless the endpoint accepts file uploads, in which case `multipart/form-data` is used.

## Rate Limits

API requests are rate-limited to **120 requests per minute** per API token.

| Header                  | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per window (120).          |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window. |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit window resets.   |

When the limit is exceeded, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "error": "Rate limit exceeded. Retry after 23 seconds."
}
```

The `Retry-After` header indicates the number of seconds to wait before retrying.

## Pagination

List endpoints use **cursor-based pagination** for consistent results even when data is being created or deleted between pages.

### Request Parameters

| Parameter | Type    | Default | Description                                                                                          |
| --------- | ------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `after`   | string  | —       | Return records after this cursor. Obtained from the `pagination.next` field of a previous response.  |
| `before`  | string  | —       | Return records before this cursor. Obtained from the `pagination.prev` field of a previous response. |
| `limit`   | integer | 10      | Number of records per page. Minimum: 1. Maximum: 100.                                                |

### Response Format

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "name": "Employment Agreement"
    },
    {
      "id": 2,
      "name": "Non-Disclosure Agreement"
    }
  ],
  "pagination": {
    "next": "eyJpZCI6Mn0",
    "prev": null
  }
}
```

| Field             | Type           | Description                                                        |
| ----------------- | -------------- | ------------------------------------------------------------------ |
| `data`            | array          | The list of records for the current page.                          |
| `pagination.next` | string or null | Cursor to fetch the next page. Null if there are no more records.  |
| `pagination.prev` | string or null | Cursor to fetch the previous page. Null if this is the first page. |

Pass the `next` cursor as the `after` parameter to fetch the next page:

```bash theme={null}
curl -X GET "https://your-app.com/api/templates?after=eyJpZCI6Mn0&limit=10" \
  -H "X-Auth-Token: YOUR_API_TOKEN"
```

## Error Handling

All errors return a JSON object with an `error` field containing a human-readable message:

```json theme={null}
{
  "error": "Template not found"
}
```

### HTTP Status Codes

| Status Code                 | Meaning                  | When It Occurs                                                                   |
| --------------------------- | ------------------------ | -------------------------------------------------------------------------------- |
| `200 OK`                    | Success                  | The request completed successfully.                                              |
| `201 Created`               | Resource created         | A new resource was created (e.g., template, submission).                         |
| `204 No Content`            | Success, no body         | The request completed successfully with no response body (e.g., DELETE).         |
| `400 Bad Request`           | Invalid request          | The request body is malformed or missing required fields.                        |
| `401 Unauthorized`          | Authentication failed    | The API token is missing, invalid, or expired.                                   |
| `403 Forbidden`             | Insufficient permissions | The API token does not have the required scope for this endpoint.                |
| `404 Not Found`             | Resource not found       | The requested resource does not exist or is not accessible to this token.        |
| `409 Conflict`              | Conflict detected        | The request conflicts with the current state (e.g., concurrent update detected). |
| `422 Unprocessable Entity`  | Validation failed        | The request body is valid JSON but contains invalid field values.                |
| `429 Too Many Requests`     | Rate limit exceeded      | Too many requests in the current time window.                                    |
| `500 Internal Server Error` | Server error             | An unexpected error occurred on the server. Contact support if this persists.    |

### Validation Errors

For `422` responses, the error message describes which field failed validation:

```json theme={null}
{
  "error": "Submitter email is invalid"
}
```

## Versioning

The DocuTrust API is currently at **version 1**. There is no version prefix in the URL — all endpoints are accessible directly under `/api/`.

```
https://your-app.com/api/templates
https://your-app.com/api/submissions
https://your-app.com/api/submitters
```

### Breaking Changes Policy

* Breaking changes will be announced at least **90 days** in advance via email and the [changelog](/resources/changelog).
* Non-breaking additions (new fields in responses, new optional parameters, new endpoints) are made without a version bump.
* When a new API version is introduced, the previous version will remain available for a deprecation period of at least **12 months**.

## Request IDs

Every API response includes an `X-Request-Id` header containing a unique identifier for the request. Include this ID when contacting support about a specific request:

```
X-Request-Id: req_a1b2c3d4e5f6
```

## Webhooks

DocuTrust can send real-time notifications to your server when events occur (e.g., a submission is completed, a submitter opens a document). Webhook payloads are signed with HMAC-SHA256 for verification. See the [Webhooks guide](/guides/webhooks) for configuration details.