Skip to main content

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.

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: 
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

API access requires the Agency plan. If your account is on a Free or Pro plan, all API requests will be rejected. Upgrade your subscription from the Billing page in your account settings before making API calls.

​
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. 
-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 page for full details, including token scopes and how to handle 401 errors.

​
Content types

Request typeContent-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: 
{
  "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:
StatusMeaning
400Validation error — check the errors field for field-level messages
401Missing or invalid API token
403Valid token but insufficient permissions or wrong plan
404Resource not found or does not belong to the requested project/album
422Unprocessable entity — business rule violation (e.g. selection limit exceeded)
{
  "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.