# Collections API overview

Read and manage people's collections of artworks, including the artworks they've seen.

People save artworks they love to **collections**. The mobile app also keeps a special collection called `Seen`, with every artwork someone has marked as seen.

**Base link:** `https://streetartcities.com/api/collections`

## A collection

```json
{
  "id": "5f0e8a2c-…",
  "name": "Favourite murals",
  "createdBy": "9b1c…",
  "artworks": [{ "id": "108322", "thumbnail": "https://…/thumb.jpg" }],
  "publicToken": "e1f2…",
  "createdAt": "2026-05-01T12:00:00.000Z",
  "updatedAt": "2026-09-20T08:30:00.000Z"
}
```

A collection is public when it has a `publicToken`. People can find other people's public collections on their profile.

## Endpoints

| Endpoint                                               | Scope               | What it does                                                                                                                   |
| ------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `GET /api/collections`                                 | `collections:read`  | [The person's collections, most recently changed first](/collections-api/reference/list-your-collections/)                     |
| `GET /api/users/:userId/collections`                   | `collections:read`  | [Someone's public collections (or all, if it's them)](/collections-api/reference/list-someones-collections/)                   |
| `GET /api/collections/lookup/:artworkId`               | `collections:read`  | [IDs of the person's collections with this artwork](/collections-api/reference/find-collections-with-an-artwork/)              |
| `GET /api/collections/:id`                             | none                | [A collection, with full details for each artwork](/collections-api/reference/get-a-collection/)                               |
| `POST /api/collections`                                | `collections:write` | [Create a collection](/collections-api/reference/create-a-collection/)                                                         |
| `POST /api/collections/:id`                            | `collections:write` | [Change a collection](/collections-api/reference/change-a-collection/)                                                         |
| `DELETE /api/collections/:id`                          | `collections:write` | [Delete a collection](/collections-api/reference/delete-a-collection/)                                                         |
| `POST /api/collections/:id/items`                      | `collections:write` | [Add an artwork](/collections-api/reference/add-an-artwork/)                                                                   |
| `DELETE /api/collections/:id/items/:artworkId`         | `collections:write` | [Remove an artwork](/collections-api/reference/remove-an-artwork/)                                                             |
| `POST /api/collections/named/:name/items`              | `collections:write` | [Add an artwork to a collection by name](/collections-api/reference/add-an-artwork-to-a-collection-by-name/)                   |
| `DELETE /api/collections/named/:name/items/:artworkId` | `collections:write` | [Remove an artwork from a collection by name](/collections-api/reference/remove-an-artwork-from-a-collection-by-name/)         |
| `DELETE /api/collections/items/:artworkId`             | `collections:write` | [Remove an artwork from all the person's collections](/collections-api/reference/remove-an-artwork-from-all-your-collections/) |

`lookup` takes an optional `collectionName` query parameter, to only look in collections with that name.

## Errors

Errors look like this:

```json
{ "error": { "message": "Artwork collection not found." } }
```

You get `401` when changing a collection that belongs to someone else, and `404` when it doesn't exist.