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

# introduction

The Shootbin API gives you programmatic access to every part of the photo proofing workflow. You can create projects and albums, upload photos, manage approval states, pin annotations on specific coordinates of an image, push new revisions, and manage the users in your team, all over HTTP using standard JSON and multipart requests.

## Base URL

All API endpoints are relative to your Shootbin instance URL:

```text theme={null}
https://your-shootbin-domain.com/api/
```

Every endpoint listed in this reference should be prefixed with the above base URL. For example, the projects list endpoint is available at `https://your-shootbin-domain.com/api/projects`.

## Plan requirement

<Warning>
  API access requires the **Agency plan**. If your account is on a Hobby or Studio plan, all API requests will be rejected. Upgrade your subscription from the Billing page in your account settings before making API calls.
</Warning>

## Authentication

All requests must include an `Authorization` header with a Bearer token. You also need to send `Accept: application/json` so the API returns JSON error responses instead of HTML redirects.

```bash theme={null}
-H "Authorization: Bearer YOUR_API_TOKEN"
-H "Accept: application/json"
```

API tokens are created from the **API Tokens** section in your Shootbin account settings. See the [Authentication](/api/authentication) page for full details, including token scopes and how to handle `401` errors.

## Content types

| Request type                                 | Content-Type header                                    |
| -------------------------------------------- | ------------------------------------------------------ |
| JSON body (projects, approvals, annotations) | `application/json`                                     |
| File uploads (photos, revisions)             | `multipart/form-data` (set automatically by curl `-F`) |

Do not set `Content-Type: application/json` for file upload requests, curl handles the correct multipart boundary when you use the `-F` flag.

## Response format

Successful responses return JSON. The shape varies by endpoint, but collection endpoints follow this general structure:

```json theme={null}
{
  "data": [...],
  "next_cursor": "eyJpZCI6MTIzfQ",
  "has_more": true,
  "meta": {
    "per_page": 50
  }
}
```

Single-resource endpoints return the resource object directly. Creation endpoints return `201 Created` with the new resource. Delete endpoints return `204 No Content` with an empty body.

## Error responses

All errors return a JSON object. Common HTTP status codes you will encounter:

| Status | Meaning                                                                       |
| ------ | ----------------------------------------------------------------------------- |
| `400`  | Validation error, check the `errors` field for field-level messages           |
| `401`  | Missing or invalid API token                                                  |
| `403`  | Valid token but insufficient permissions or wrong plan                        |
| `404`  | Resource not found or does not belong to the requested project/album          |
| `422`  | Unprocessable entity, business rule violation (e.g. selection limit exceeded) |

```json theme={null}
{
  "message": "This API token does not have permission to create projects.",
  "errors": {}
}
```

## Rate limiting

The API uses token-based authentication with no additional rate limit tier. Avoid making high-frequency polling requests in tight loops; use cursor pagination and process responses before requesting the next page.