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.

A revision replaces the live version of a photo with a new file while preserving the history. When you upload a revision, Shootbin automatically archives the current photo (file, web variant, and all active annotations) as a numbered revision entry, then promotes the new file as the live version. The approval state is reset and all annotations are cleared from the new current photo. This workflow is designed for photographers who need to deliver retouched or corrected files after an initial review round without losing the annotation context from the previous version.
Uploading a revision requires both the update (or post:update) token scope and the authenticated user must be the owner of the project. Approver tokens cannot upload revisions. If the project is currently out for review (locked for photographer edits), the revision upload will be rejected with 403.

​
Upload a revision

Archives the current photo and replaces it with a new file. 
POST /api/projects/{project}/albums/{album}/photos/{photo}/revisions

​
Path parameters

​
project
integer
required
The project ID.
​
album
integer
required
The album ID.
​
photo
integer
required
The ID of the photo to replace with a new revision.

​
Request body

Send as multipart/form-data:
​
revision
file
required
The new image file. Must be a valid image. Maximum size: 10 MB.
​
client_original_filename
string
Override the filename stored as original_filename on the new live photo. Useful when your HTTP client reports a temporary path instead of the real filename. When omitted, the filename reported by the upload is used.

​
Example request

curl -X POST https://your-shootbin-domain.com/api/projects/PROJECT_ID/albums/ALBUM_ID/photos/PHOTO_ID/revisions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -F "revision=@/full/path/to/revision.jpg"

​
Example response

201 Created 
{
  "success": true,
  "message": "A new revision has been uploaded and is ready for review.",
  "photo": {
    "id": 124,
    "album_id": 12,
    "title": "Frame 001",
    "description": "Uploaded through the API",
    "tags": [],
    "original_filename": "revision.jpg",
    "approved_at": null,
    "revision_uploaded_at": "2025-04-03T08:45:00.000000Z",
    "has_annotations": false,
    "image_url": "https://your-shootbin-domain.com/photos/...",
    "revisions": [
      {
        "id": 5,
        "revision_number": 1,
        "original_filename": "photo.jpg",
        "uploaded_at": "2025-04-01T10:00:00.000000Z",
        "archived_annotations_count": 2,
        "image_url": "https://your-shootbin-domain.com/photos/revisions/..."
      }
    ],
    "annotations": []
  }
}

​
Response fields

​
success
boolean
Always true on a successful revision upload.
​
message
string
A human-readable confirmation message.
​
photo
object
The full photo payload reflecting the new live state. approved_at is null (approval reset), annotations is empty (cleared), and revisions includes the newly archived previous version.
​
photo.revision_uploaded_at
string
ISO 8601 timestamp of when this revision was uploaded. Updates each time a new revision is pushed.
​
photo.revisions
array
All previously archived versions. Each entry includes revision_number, original_filename, uploaded_at, archived_annotations_count, and image_url.

​
Errors

StatusReason
403Token lacks update scope, user is not the project owner, or project is locked for review
404Photo, album, or project not found
409Revision history is not available on your Shootbin instance — contact your administrator
422Validation failed — revision file is missing, not an image, or exceeds 10 MB
If you receive a 409 response, the revision history feature may not be enabled on your Shootbin instance. Contact your account administrator to ensure you are running the latest version.