# Managing collections

Create collections, add artworks to them and keep track of what people have seen.

## Create a collection

```bash
curl -X POST https://streetartcities.com/api/collections \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Favourite murals", "public": true }'
```

| Field      | Value                                                         |
| ---------- | ------------------------------------------------------------- |
| `name`     | The name of the collection                                    |
| `public`   | `true` to let others see it, `false` to keep it to themselves |
| `artworks` | A list of `{ "id", "thumbnail" }`, replacing all artworks     |

You get the new collection back.

## Change a collection

`POST /api/collections/:id` with the same fields. Only the fields you send change, so you can rename a collection or make it public without sending its artworks along.

## Add and remove artworks

Add one artwork at a time, with its ID and a thumbnail link:

```bash
curl -X POST https://streetartcities.com/api/collections/5f0e8a2c-…/items \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "108322", "thumbnail": "https://…/thumb.jpg" }'
```

Adding an artwork that's already in the collection does nothing. To remove it:

```bash
curl -X DELETE https://streetartcities.com/api/collections/5f0e8a2c-…/items/108322 \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## Collections by name

You can also use a collection's name instead of its ID. That's handy for collections every person has, like `Seen`. If there's no collection with that name yet, adding an artwork creates it.

```bash
# Mark an artwork as seen
curl -X POST https://streetartcities.com/api/collections/named/Seen/items \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "108322", "thumbnail": "https://…/thumb.jpg" }'

# And undo it
curl -X DELETE https://streetartcities.com/api/collections/named/Seen/items/108322 \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

<Admonition kind="info" title="Keep it real">
  The Street Art Cities app uses `Seen` to show people which artworks they've
  seen, so only add artworks they've actually seen in real life.
</Admonition>

## Is this artwork saved?

To show a "saved" state in your app, look up which of the person's collections contain an artwork:

```bash
curl "https://streetartcities.com/api/collections/lookup/108322" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

```json
["5f0e8a2c-…", "a91b…"]
```