# Pixieset API

> Every Pixieset endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/pixieset

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

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: https://cotlet.dev/integrations/pixieset-api-mcp-server

## 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

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | no | Filter by collection name. |
| `limit` | integer | no | 1 to 100. Default: 25. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/pixieset/list_collections \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("pixieset", "list_collections")
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'list_collections');
```

**CLI**

```bash
cotlet call pixieset list_collections
```

### Example response

```json
{
  "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

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `collection_id` | string | yes | Collection ID from list_collections. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "get_collection", {"collection_id":"collection_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'get_collection', {"collection_id":"collection_8c41d2"});
```

**CLI**

```bash
cotlet call pixieset get_collection --data '{"collection_id":"collection_8c41d2"}'
```

### Example response

```json
{
  "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

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `collection_id` | string | yes | Collection ID from list_collections. |
| `with_comments_only` | boolean | no | Only photos with a client comment. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "list_favorites", {"collection_id":"col_5521","with_comments_only":True})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'list_favorites', {"collection_id":"col_5521","with_comments_only":true});
```

**CLI**

```bash
cotlet call pixieset list_favorites --data '{"collection_id":"col_5521","with_comments_only":true}'
```

### Example response

```json
{
  "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

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `collection_id` | string | yes | Collection ID from list_collections. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "get_download_activity", {"collection_id":"col_5530"})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'get_download_activity', {"collection_id":"col_5530"});
```

**CLI**

```bash
cotlet call pixieset get_download_activity --data '{"collection_id":"col_5530"}'
```

### Example response

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

## List contacts

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | no | Search by name or email. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/pixieset/list_contacts \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("pixieset", "list_contacts")
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'list_contacts');
```

**CLI**

```bash
cotlet call pixieset list_contacts
```

### Example response

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

## List sessions

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | no | Start of the range. Default: today. |
| `to` | date | no | End of the range. Default: 7 days after from. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/pixieset/list_sessions \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("pixieset", "list_sessions")
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'list_sessions');
```

**CLI**

```bash
cotlet call pixieset list_sessions
```

### Example response

```json
{
  "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

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `unpaid_only` | boolean | no | Only invoices that are not fully paid. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/pixieset/list_invoices \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("pixieset", "list_invoices")
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'list_invoices');
```

**CLI**

```bash
cotlet call pixieset list_invoices
```

### Example response

```json
{
  "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

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

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Collection name, e.g. "Smith Wedding". |
| `event_date` | date | no | Date of the shoot. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "create_collection", {"name":"Smith Wedding","event_date":"2026-10-04"})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'create_collection', {"name":"Smith Wedding","event_date":"2026-10-04"});
```

**CLI**

```bash
cotlet call pixieset create_collection --data '{"name":"Smith Wedding","event_date":"2026-10-04"}'
```

### Example response

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

## Upload photos

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

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `collection_id` | string | yes | Collection ID from list_collections. |
| `photo_urls` | string[] | yes | Image URLs, publicly reachable. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "upload_photos", {"collection_id":"collection_8c41d2","photo_urls":["https://example.com"]})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'upload_photos', {"collection_id":"collection_8c41d2","photo_urls":["https://example.com"]});
```

**CLI**

```bash
cotlet call pixieset upload_photos --data '{"collection_id":"collection_8c41d2","photo_urls":["https://example.com"]}'
```

### Example response

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

## Share collection

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

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `collection_id` | string | yes | Collection ID from list_collections. |
| `emails` | string[] | yes | Recipient emails. |
| `message` | string | no | Personal note in the invite. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "share_collection", {"collection_id":"col_5544","emails":["client@example.com"],"message":"Your wedding photos are ready!"})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'share_collection', {"collection_id":"col_5544","emails":["client@example.com"],"message":"Your wedding photos are ready!"});
```

**CLI**

```bash
cotlet call pixieset share_collection --data '{"collection_id":"col_5544","emails":["client@example.com"],"message":"Your wedding photos are ready!"}'
```

### Example response

```json
{
  "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

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

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Full name. |
| `email` | string | yes | Contact email. |
| `phone` | string | no | Phone number. |
| `type` | string | no | Contact type as Studio Manager shows it, e.g. lead or client. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "create_contact", {"name":"Jane Doe","email":"jane@example.com"})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'create_contact', {"name":"Jane Doe","email":"jane@example.com"});
```

**CLI**

```bash
cotlet call pixieset create_contact --data '{"name":"Jane Doe","email":"jane@example.com"}'
```

### Example response

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

## Create invoice

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

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from list_contacts or create_contact. |
| `items` | object | yes | Line items: list of { name, quantity, unit_price }. |
| `due_date` | date | no | Payment due date. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "create_invoice", {"contact_id":"contact_8c41d2","items":"items"})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'create_invoice', {"contact_id":"contact_8c41d2","items":"items"});
```

**CLI**

```bash
cotlet call pixieset create_invoice --data '{"contact_id":"contact_8c41d2","items":"items"}'
```

### Example response

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

## Send invoice

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

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `invoice_id` | string | yes | Invoice ID from list_invoices or create_invoice. |
| `message` | string | no | Note in the email. |

### Request

**cURL**

```bash
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**

```python
result = client.call("pixieset", "send_invoice", {"invoice_id":"invoice_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('pixieset', 'send_invoice', {"invoice_id":"invoice_8c41d2"});
```

**CLI**

```bash
cotlet call pixieset send_invoice --data '{"invoice_id":"invoice_8c41d2"}'
```

### Example response

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