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 uses token-based authentication. Every request must carry a valid Bearer token in the Authorization header. Tokens are tied to your user account and carry fine-grained scopes that control which operations they can perform.
API access is available on the Agency plan only. Tokens issued on Free or Pro accounts will receive a 403 response on all API endpoints, regardless of scope.

​
Creating an API token

  1. Log in to your Shootbin account.
  2. Open Account Settings and navigate to the API Tokens section.
  3. Give the token a descriptive name (e.g. ci-uploader or integration-prod).
  4. Select the scopes the token needs (see Token scopes below).
  5. Click Create and copy the token immediately — it is only shown once.
Store the token securely (for example in a secrets manager or CI/CD environment variable). Treat it like a password: anyone with the token can act on your behalf.

​
Attaching the token to requests

Include the token in every request using the Authorization header alongside Accept: application/json: 
curl -X GET https://your-shootbin-domain.com/api/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
The Accept: application/json header is required. Without it, the API may return an HTML redirect to the login page on authentication failures instead of a JSON error.
When using environment variables, store your token as SHOOTBIN_API_TOKEN and reference it as $SHOOTBIN_API_TOKEN in shell scripts to avoid leaking the value in your shell history.

​
Token scopes

When you create a token, you assign it one or more scopes. The API enforces these scopes on every request:
ScopeAliasWhat it allows
createpost:createCreate projects, albums, and upload photos
updatepost:updateApprove/unapprove photos, add or delete annotations, upload revisions
A token without the create scope will receive a 403 when it attempts to create a project or upload a photo. A token without update will receive a 403 when it tries to approve a photo or manage annotations.
You can issue multiple tokens with different scopes — for example a read-only reporting token and a separate upload token used in your editing pipeline.

​
Authentication errors

StatusCauseResolution
401 UnauthorizedToken is missing, malformed, or has been revokedCheck that the Authorization: Bearer header is present and the token is valid
403 ForbiddenToken is valid but lacks the required scope, or the account is not on the Agency planVerify the token’s scopes in account settings, or upgrade your plan
Example 401 response: 
{
  "message": "Unauthenticated."
}
Example 403 response when scope is missing: 
{
  "message": "This API token does not have permission to create projects."
}

​
Revoking a token

You can revoke any token from the API Tokens section of your account settings. Revoked tokens return 401 immediately on subsequent requests. Rotate tokens regularly and revoke any that are no longer needed.