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.

Albums group related photos within a project. A single project can contain multiple albums — for example one per look, scene, or shooting day. The albums API lets you retrieve all albums in a project and create new ones from your own tooling or automation pipeline.
You must be a member of the project to list or create albums. Creating an album additionally requires the create (or post:create) token scope and the create team permission.

​
List albums in a project

Returns all albums belonging to the specified project, ordered newest first. Each album includes a photos_count field reflecting how many photos it currently contains. 
GET /api/projects/{project}/albums

​
Path parameters

​
project
integer
required
The ID of the project. Obtain this from the List projects endpoint.

​
Example request

curl -X GET https://your-shootbin-domain.com/api/projects/PROJECT_ID/albums \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

​
Example response

[
  {
    "id": 12,
    "team_id": 3,
    "name": "Look 1",
    "description": "Opening look — outdoor terrace",
    "photos_count": 47,
    "created_at": "2025-03-20T10:00:00.000000Z",
    "updated_at": "2025-03-20T10:00:00.000000Z"
  },
  {
    "id": 11,
    "team_id": 3,
    "name": "BTS",
    "description": null,
    "photos_count": 12,
    "created_at": "2025-03-18T14:30:00.000000Z",
    "updated_at": "2025-03-18T14:30:00.000000Z"
  }
]

​
Response fields

​
id
integer
The unique identifier of the album. Use this value as the {album} path parameter in all photo API calls.
​
team_id
integer
The ID of the project this album belongs to.
​
name
string
The album name.
​
description
string | null
Optional description. null if not set.
​
photos_count
integer
The number of photos currently in the album.

​
Create an album

Creates a new album inside the specified project. 
POST /api/projects/{project}/albums
If the project is currently out for review (locked for photographer edits), album creation will be rejected with a 403. Close the review workflow before adding new albums.

​
Path parameters

​
project
integer
required
The ID of the project to create the album in.

​
Request body

This endpoint accepts multipart/form-data fields (the same format used by curl -F):
​
name
string
required
The album name. Maximum 255 characters.
​
description
string
An optional description for the album.

​
Example request

curl -X POST https://your-shootbin-domain.com/api/projects/PROJECT_ID/albums \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -F "name=Look 1" \
  -F "description=First API upload album"

​
Example response

201 Created 
{
  "id": 13,
  "team_id": 3,
  "name": "Look 1",
  "description": "First API upload album",
  "photos_count": 0,
  "created_at": "2025-04-01T09:30:00.000000Z",
  "updated_at": "2025-04-01T09:30:00.000000Z"
}

​
Errors

StatusReason
403Token lacks create scope, user lacks team create permission, project is locked for review, or album plan limit reached
404Project not found
422Validation failed — name is missing or too long