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.

Annotations are pinned notes attached to a specific location on a photo. Each annotation has a comment text and an x_position/y_position pair that places the pin as a percentage of the image’s width and height — so x_position: 50, y_position: 50 pins the note to the exact center of the image regardless of display size. Annotations belong to the current version of a photo. When a new revision is uploaded, all active annotations are archived with that revision and the live photo starts with a clean slate.
Both creating and deleting annotations require the update (or post:update) token scope. The authenticated user must also have the update team permission on the project.

​
Add an annotation

Pins a new annotation to a specific position on a photo. 
POST /api/projects/{project}/albums/{album}/photos/{photo}/annotations

​
Path parameters

​
project
integer
required
The project ID.
​
album
integer
required
The album ID.
​
photo
integer
required
The photo ID to annotate.

​
Request body

​
comment
string
required
The annotation text. Maximum 255 characters.
​
x_position
float
required
Horizontal position of the pin as a percentage of the image width. Must be between 0 and 100.
​
y_position
float
required
Vertical position of the pin as a percentage of the image height. Must be between 0 and 100.

​
Example request

curl -X POST https://your-shootbin-domain.com/api/projects/PROJECT_ID/albums/ALBUM_ID/photos/PHOTO_ID/annotations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"comment":"Please retouch the hair on the left side.","x_position":42.5,"y_position":31.2}'

​
Example response

201 Created 
{
  "id": 9,
  "comment": "Please retouch the hair on the left side.",
  "x_position": 42.5,
  "y_position": 31.2,
  "created_at": "2025-04-02T11:00:00.000000Z"
}

​
Response fields

​
id
integer
The unique ID of the annotation. Use this value as {annotation} when deleting.
​
comment
string
The annotation text as stored.
​
x_position
float
Horizontal position, 0–100.
​
y_position
float
Vertical position, 0–100.
​
created_at
string
ISO 8601 timestamp of when the annotation was created.

​
Errors

StatusReason
403Token lacks update scope or user lacks team update permission
404Photo, album, or project not found, or the photo does not belong to the specified album
422Validation failed — comment missing, or position values out of the 0–100 range

​
Delete an annotation

Permanently removes an annotation from a photo. 
DELETE /api/projects/{project}/albums/{album}/photos/{photo}/annotations/{annotation}

​
Path parameters

​
project
integer
required
The project ID.
​
album
integer
required
The album ID.
​
photo
integer
required
The photo ID.
​
annotation
integer
required
The annotation ID to delete. Obtain this from the id field returned when creating an annotation, or from the annotations array on a photo response.

​
Example request

curl -X DELETE https://your-shootbin-domain.com/api/projects/PROJECT_ID/albums/ALBUM_ID/photos/PHOTO_ID/annotations/ANNOTATION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

​
Response

204 No Content — empty body on success.

​
Errors

StatusReason
403Token lacks update scope or user lacks team update permission
404Annotation not found, or does not belong to the specified photo
To clear all annotations from a photo at once, use the upload revision endpoint instead. Submitting a new revision archives the current photo along with all its annotations and starts the new version with a clean annotation set.