REST API reference

Pixieset API

13 endpoints for Pixieset. Each one is a POST with a JSON body, called with your API key.

Base URL
https://cotlet.dev/api/v1/pixieset
Connects with
Your own Pixieset account (owner of the studio)
Integration page
Pixieset
Pixieset Endpoints
Endpoint Access Description
list_collections read Client gallery collections with name, event date, photo count and gallery URL.
get_collection read One collection with photo count, privacy settings, cover and gallery URL.
list_favorites read Photos clients marked as favorites in a collection, with their comments.
get_download_activity read Who downloaded from a collection and when.
list_contacts read Studio Manager contacts: clients, leads and other connections.
list_sessions read Booked sessions in a date range with client, session type and time.
list_invoices read Invoices with client, total, amount paid and due date.
create_collection write New client gallery collection. Nothing reaches the client until you share it.
upload_photos write Add photos to a collection from image URLs.
share_collection write Send the branded email invite with the gallery link to one or more clients.
create_contact write Add a client or lead to Studio Manager contacts.
create_invoice write Draft invoice for a contact with line items. Not sent until you send it.
send_invoice write Email a draft invoice to the client with a link to pay online.

List collections

read

POST https://cotlet.dev/api/v1/pixieset/list_collections

Lists the collections in your Client Gallery, newest first. Use query to find one by name, then pass its collection_id to the other tools. Pages hold up to 100 collections; pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_collections
NameTypeDescription
query string Filter by collection name.
limit integer 1 to 100. Default: 25.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/list_collections \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("pixieset", "list_collections")
Node.js
const result = await cotlet.call('pixieset', 'list_collections');
CLI
cotlet call pixieset list_collections

Example response

{
  "collections": [
    {
      "collection_id": "col_5530",
      "name": "Johnson Family Session",
      "event_date": "2026-09-27",
      "photos": 84,
      "url": "https://studioexample.pixieset.com/johnsonfamily/"
    },
    {
      "collection_id": "col_5521",
      "name": "Lee Family Session",
      "event_date": "2026-09-13",
      "photos": 112,
      "url": "https://studioexample.pixieset.com/leefamily/"
    }
  ],
  "next_cursor": null
}

Get collection

read

POST https://cotlet.dev/api/v1/pixieset/get_collection

Returns one collection: name, event date, photo count and gallery URL, plus whether it is password protected and whether downloads need a PIN. It never returns the password or the PIN itself.

Parameters

Parameters: get_collection
NameTypeDescription
collection_id required string Collection ID from list_collections.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/get_collection \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_id":"collection_8c41d2"}'
Python
result = client.call("pixieset", "get_collection", {"collection_id":"collection_8c41d2"})
Node.js
const result = await cotlet.call('pixieset', 'get_collection', {"collection_id":"collection_8c41d2"});
CLI
cotlet call pixieset get_collection --data '{"collection_id":"collection_8c41d2"}'

Example response

{
  "collection_id": "col_5530",
  "name": "Johnson Family Session",
  "event_date": "2026-09-27",
  "photos": 84,
  "password_protected": true,
  "download_pin": true,
  "url": "https://studioexample.pixieset.com/johnsonfamily/"
}

List favorites

read

POST https://cotlet.dev/api/v1/pixieset/list_favorites

Returns the photos clients favorited in one collection, with the file name of each and any note or editing request the client added to that image. Set with_comments_only to get only photos that have a comment. Nothing is changed or sent.

Parameters

Parameters: list_favorites
NameTypeDescription
collection_id required string Collection ID from list_collections.
with_comments_only boolean Only photos with a client comment.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/list_favorites \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_id":"col_5521","with_comments_only":true}'
Python
result = client.call("pixieset", "list_favorites", {"collection_id":"col_5521","with_comments_only":True})
Node.js
const result = await cotlet.call('pixieset', 'list_favorites', {"collection_id":"col_5521","with_comments_only":true});
CLI
cotlet call pixieset list_favorites --data '{"collection_id":"col_5521","with_comments_only":true}'

Example response

{
  "collection_id": "col_5521",
  "favorites": [
    {
      "file_name": "IMG_2041.jpg",
      "comment": "Please brighten this one."
    },
    {
      "file_name": "IMG_2077.jpg",
      "comment": null
    }
  ]
}

Get download activity

read

POST https://cotlet.dev/api/v1/pixieset/get_download_activity

Returns the download activity Pixieset shows for one collection: who downloaded and when. An empty list means nobody has downloaded yet. Nothing is changed or sent.

Parameters

Parameters: get_download_activity
NameTypeDescription
collection_id required string Collection ID from list_collections.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/get_download_activity \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_id":"col_5530"}'
Python
result = client.call("pixieset", "get_download_activity", {"collection_id":"col_5530"})
Node.js
const result = await cotlet.call('pixieset', 'get_download_activity', {"collection_id":"col_5530"});
CLI
cotlet call pixieset get_download_activity --data '{"collection_id":"col_5530"}'

Example response

{
  "collection_id": "col_5530",
  "downloads": [
    {
      "email": "client@example.com",
      "downloaded_at": "2026-10-03T18:42:00Z"
    }
  ]
}

List contacts

read

POST https://cotlet.dev/api/v1/pixieset/list_contacts

Lists the contacts in Studio Manager with email and phone, newest first. Search by name or email to find the contact_id that create_invoice needs. Pages hold up to 100 contacts; pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_contacts
NameTypeDescription
query string Search by name or email.
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/list_contacts \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("pixieset", "list_contacts")
Node.js
const result = await cotlet.call('pixieset', 'list_contacts');
CLI
cotlet call pixieset list_contacts

Example response

{
  "contacts": [
    {
      "contact_id": "ct_3071",
      "name": "Maya Brooks",
      "email": "maya@example.com",
      "phone": "+1 555 0100",
      "type": "lead"
    }
  ],
  "next_cursor": null
}

List sessions

read

POST https://cotlet.dev/api/v1/pixieset/list_sessions

Lists sessions from Studio Manager in a date range, earliest first: the ones clients booked on your booking site and the ones you added. Without dates it covers the coming days from today.

Parameters

Parameters: list_sessions
NameTypeDescription
from date Start of the range. Default: today.
to date End of the range. Default: 7 days after from.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/list_sessions \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("pixieset", "list_sessions")
Node.js
const result = await cotlet.call('pixieset', 'list_sessions');
CLI
cotlet call pixieset list_sessions

Example response

{
  "sessions": [
    {
      "session_id": "se_8812",
      "client": "Maya Brooks",
      "type": "Family portrait",
      "starts_at": "2026-10-14T10:00:00-07:00"
    },
    {
      "session_id": "se_8820",
      "client": "Tom Reyes",
      "type": "Headshots",
      "starts_at": "2026-10-16T15:30:00-07:00"
    }
  ]
}

List invoices

read

POST https://cotlet.dev/api/v1/pixieset/list_invoices

Lists invoices from Studio Manager, newest first, with client, total, amount paid and due date. Set unpaid_only to keep invoices that are not fully paid. Nothing is changed or sent to a client.

Parameters

Parameters: list_invoices
NameTypeDescription
unpaid_only boolean Only invoices that are not fully paid.
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/list_invoices \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("pixieset", "list_invoices")
Node.js
const result = await cotlet.call('pixieset', 'list_invoices');
CLI
cotlet call pixieset list_invoices

Example response

{
  "invoices": [
    {
      "invoice_id": "inv_1204",
      "client": "Maya Brooks",
      "total": 450,
      "paid": 0,
      "currency": "USD",
      "due_date": "2026-10-25"
    },
    {
      "invoice_id": "inv_1198",
      "client": "Tom Reyes",
      "total": 300,
      "paid": 100,
      "currency": "USD",
      "due_date": "2026-10-08"
    }
  ],
  "next_cursor": null
}

Create collection

write

POST https://cotlet.dev/api/v1/pixieset/create_collection

Creates an empty collection in your Client Gallery and returns its ID and gallery URL. The client is not told anything until share_collection runs. It reaches no one, so it runs without asking.

Parameters

Parameters: create_collection
NameTypeDescription
name required string Collection name, e.g. "Smith Wedding".
event_date date Date of the shoot.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/create_collection \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Smith Wedding","event_date":"2026-10-04"}'
Python
result = client.call("pixieset", "create_collection", {"name":"Smith Wedding","event_date":"2026-10-04"})
Node.js
const result = await cotlet.call('pixieset', 'create_collection', {"name":"Smith Wedding","event_date":"2026-10-04"});
CLI
cotlet call pixieset create_collection --data '{"name":"Smith Wedding","event_date":"2026-10-04"}'

Example response

{
  "collection_id": "col_5544",
  "name": "Smith Wedding",
  "event_date": "2026-10-04",
  "photos": 0,
  "url": "https://studioexample.pixieset.com/smithwedding/"
}

Upload photos

write

POST https://cotlet.dev/api/v1/pixieset/upload_photos

Downloads each image URL and adds it to the collection. Returns how many photos were added and which URLs failed. It reaches no one, so it runs without asking. Storage counts against your Pixieset plan.

Parameters

Parameters: upload_photos
NameTypeDescription
collection_id required string Collection ID from list_collections.
photo_urls required string[] Image URLs, publicly reachable.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/upload_photos \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_id":"collection_8c41d2","photo_urls":["https://example.com"]}'
Python
result = client.call("pixieset", "upload_photos", {"collection_id":"collection_8c41d2","photo_urls":["https://example.com"]})
Node.js
const result = await cotlet.call('pixieset', 'upload_photos', {"collection_id":"collection_8c41d2","photo_urls":["https://example.com"]});
CLI
cotlet call pixieset upload_photos --data '{"collection_id":"collection_8c41d2","photo_urls":["https://example.com"]}'

Example response

{
  "collection_id": "col_5544",
  "added": 2,
  "failed": [],
  "photos_total": 2
}

Share collection

write Confirm

POST https://cotlet.dev/api/v1/pixieset/share_collection

Sends Pixieset's branded email invite with the gallery link to the addresses you give, with an optional personal note. The email goes out from your studio. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: share_collection
NameTypeDescription
collection_id required string Collection ID from list_collections.
emails required string[] Recipient emails.
message string Personal note in the invite.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/share_collection \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_id":"col_5544","emails":["client@example.com"],"message":"Your wedding photos are ready!"}'
Python
result = client.call("pixieset", "share_collection", {"collection_id":"col_5544","emails":["client@example.com"],"message":"Your wedding photos are ready!"})
Node.js
const result = await cotlet.call('pixieset', 'share_collection', {"collection_id":"col_5544","emails":["client@example.com"],"message":"Your wedding photos are ready!"});
CLI
cotlet call pixieset share_collection --data '{"collection_id":"col_5544","emails":["client@example.com"],"message":"Your wedding photos are ready!"}'

Example response

{
  "collection_id": "col_5544",
  "status": "shared",
  "recipients": 1,
  "gallery_url": "https://studioexample.pixieset.com/smithwedding/",
  "sent_at": "2026-10-12T10:15:00-07:00"
}

Create contact

write

POST https://cotlet.dev/api/v1/pixieset/create_contact

Adds one contact to Studio Manager and returns its contact_id. Nothing is sent to the person. It reaches no one, so it runs without asking.

Parameters

Parameters: create_contact
NameTypeDescription
name required string Full name.
email required string Contact email.
phone string Phone number.
type string Contact type as Studio Manager shows it, e.g. lead or client.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/create_contact \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com"}'
Python
result = client.call("pixieset", "create_contact", {"name":"Jane Doe","email":"jane@example.com"})
Node.js
const result = await cotlet.call('pixieset', 'create_contact', {"name":"Jane Doe","email":"jane@example.com"});
CLI
cotlet call pixieset create_contact --data '{"name":"Jane Doe","email":"jane@example.com"}'

Example response

{
  "contact_id": "ct_3071",
  "name": "Maya Brooks",
  "email": "maya@example.com",
  "type": "lead"
}

Create invoice

write

POST https://cotlet.dev/api/v1/pixieset/create_invoice

Creates a draft invoice for one contact from line items and returns its invoice_id and total. The client gets nothing until send_invoice runs. It reaches no one, so it runs without asking.

Parameters

Parameters: create_invoice
NameTypeDescription
contact_id required string Contact ID from list_contacts or create_contact.
items required object Line items: list of { name, quantity, unit_price }.
due_date date Payment due date.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/create_invoice \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"contact_8c41d2","items":"items"}'
Python
result = client.call("pixieset", "create_invoice", {"contact_id":"contact_8c41d2","items":"items"})
Node.js
const result = await cotlet.call('pixieset', 'create_invoice', {"contact_id":"contact_8c41d2","items":"items"});
CLI
cotlet call pixieset create_invoice --data '{"contact_id":"contact_8c41d2","items":"items"}'

Example response

{
  "invoice_id": "inv_1204",
  "contact_id": "ct_3071",
  "status": "draft",
  "total": 450,
  "currency": "USD",
  "due_date": "2026-10-25"
}

Send invoice

write Confirm

POST https://cotlet.dev/api/v1/pixieset/send_invoice

Emails the invoice to the client so they can pay online. This asks the client for money. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_invoice
NameTypeDescription
invoice_id required string Invoice ID from list_invoices or create_invoice.
message string Note in the email.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/pixieset/send_invoice \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"invoice_8c41d2"}'
Python
result = client.call("pixieset", "send_invoice", {"invoice_id":"invoice_8c41d2"})
Node.js
const result = await cotlet.call('pixieset', 'send_invoice', {"invoice_id":"invoice_8c41d2"});
CLI
cotlet call pixieset send_invoice --data '{"invoice_id":"invoice_8c41d2"}'

Example response

{
  "invoice_id": "inv_1204",
  "status": "sent",
  "sent_to": "maya@example.com",
  "sent_at": "2026-10-12T10:20:00-07:00"
}