Developers
Menu
Collections API

Managing collections

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

Create a collection

curl -X POST https://streetartcities.com/api/collections \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Favourite murals", "public": true }'
FieldValue
nameThe name of the collection
publictrue to let others see it, false to keep it to themselves
artworksA 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:

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:

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.

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

Is this artwork saved?

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

curl "https://streetartcities.com/api/collections/lookup/108322" \
  -H "Authorization: Bearer ACCESS_TOKEN"
["5f0e8a2c-…", "a91b…"]