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

# Safeclose API: conventions, errors, and resources

> Base URL, versioning, Bearer authentication, content type, HTTP status codes, and a map of all resource groups in the Safeclose REST API.

The Safeclose API is a JSON REST API. Every endpoint sits under the `/v1/` path prefix, requires a Bearer token for authentication, and returns JSON for both successful responses and errors. This page covers the conventions you need to understand before making your first request.

## Base URL

Your API base URL is the URL of your Safeclose API service. All examples in this reference use a placeholder:

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

Replace this with your actual API host. You can confirm the correct URL by calling the health endpoint — it returns `{ "service": "safeclose-api" }`:

```bash theme={null}
curl https://your-api.example.com/health
```

```json theme={null}
{
  "ok": true,
  "service": "safeclose-api",
  "ts": "2026-04-27T00:00:00.000Z"
}
```

<Tip>
  If you receive an HTML response instead of JSON, your base URL likely points at the Safeclose web app instead of the API service. Make sure you are using the correct API host URL — the health endpoint at `/health` should return `{ "service": "safeclose-api" }`.
</Tip>

## Versioning

All API endpoints are prefixed with `/v1/`. The current version is **v1**. Include the version prefix in every request path:

```
https://your-api.example.com/v1/signing/session
```

## Authentication

Every `/v1/` endpoint requires a `Bearer` token in the `Authorization` header. The token is a Clerk JWT session token obtained from an authenticated Safeclose session.

```http theme={null}
Authorization: Bearer <your-session-token>
```

See [Authenticate requests](/api/authentication) for full details on obtaining and using tokens.

## Content type

Send `Content-Type: application/json` for any request that includes a body. The API returns `application/json` for all responses, including errors.

```http theme={null}
Content-Type: application/json
```

## Error format

When a request fails, the API returns a JSON object with a single `error` field describing what went wrong:

```json theme={null}
{
  "error": "Missing Authorization Bearer token."
}
```

The HTTP status code indicates the category of failure. Parse the `error` string for a human-readable explanation.

## HTTP status codes

| Code  | Name                | When you'll see it                                                                                                              |
| ----- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK                  | Successful read or action                                                                                                       |
| `201` | Created             | Resource successfully created                                                                                                   |
| `204` | No Content          | Successful deletion; response body is empty                                                                                     |
| `400` | Bad Request         | Invalid request body or missing required parameters                                                                             |
| `401` | Unauthorized        | Authorization header is missing, malformed, or the token is expired                                                             |
| `403` | Forbidden           | Token is valid but your role does not have permission to access this resource                                                   |
| `404` | Not Found           | Resource does not exist or is not visible to your account                                                                       |
| `409` | Conflict            | Resource is already in the target state (for example, cancelling a signing that is already cancelled)                           |
| `503` | Service Unavailable | A required service dependency is not available (for example, the comments feature requires the real-time service to be enabled) |

## Rate limiting

Rate limiting is managed at the infrastructure level. Contact your organization administrator for details.

## Available API resources

| Group                                                         | Base path              | Description                                                                          |
| ------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------ |
| [Signing — session](/api/signing/session)                     | `/v1/signing/`         | Retrieve your signing session, RBAC capabilities, and role assignments               |
| [Signing — signer queue](/api/signing/signer-queue)           | `/v1/signing/signer/`  | Access assigned signing packages, documents, and co-signers; record e-signatures     |
| [Signing — manager signings](/api/signing/manager-signings)   | `/v1/signing/manager/` | Create and manage signing packages, view locations, companies, and organizations     |
| [Signing — templates and flows](/api/signing/templates-flows) | `/v1/signing/manager/` | List and update signing templates and flows                                          |
| [Documents](/api/documents/list)                              | `/v1/documents/`       | Create, list, update, and delete chattel documents; manage comments and RCM outreach |
| [Workspace](/api/workspace/organizations)                     | `/v1/workspace/`       | Query organization memberships and workspace settings                                |

## Health endpoints

Two unauthenticated endpoints are available for infrastructure probes:

| Endpoint      | Description                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `GET /health` | Returns `{ "ok": true, "service": "safeclose-api", "ts": "<iso-timestamp>" }`. Always returns `200` when the process is running. |
| `GET /ready`  | Returns `{ "ready": true }` when the database connection is reachable, or `503 { "ready": false }` if it is not.                 |

<Note>
  The health endpoints do not require an `Authorization` header. Use `/health` for liveness probes and `/ready` for readiness probes.
</Note>