Collections API

Collections are ordered groups of artworks. These endpoints cover the collection record and its membership. Every request needs an API key, as described in the API overview.

List collections

Get information about all the collections in a vault by calling this endpoint.

The artworkIds field is returned in the order of the works in the collection, and can be cross-referenced with data from the list artworks endpoint to display artworks as needed.

GET /v0/collections

curl https://api.valise.works/v0/collections
  --method GET
  --header "Authorization: Bearer <API_KEY>"

Here’s an example response:

{
  "data": [
    {
      "id": "ehptxdig36vlctxmpe89p34n",
      "title": "My Collection",
      "notes": "Works for the spring exhibition",
      "artworkIds": [
        "ahvxb9zbcew4a0fhroz9ijs0",
        "iogf1yv44dtudcam42a9rx8o",
        "bes9dncmjfv9o2xbtrskzc1r"
        // ...
      ],
      "createdAt": "2024-09-06T11:17:15.150Z",
      "updatedAt": "2024-09-06T11:17:15.150Z"
    }
  ],
  "page": {
    "count": 1,
    "next": null
  }
}

Get a collection

Fetch a single collection by its ID.

GET /v0/collections/{id}

curl https://api.valise.works/v0/collections/ehptxdig36vlctxmpe89p34n
  --header "Authorization: Bearer <API_KEY>"

The response is a single collection in the same shape as the entries in the list collections response.

Create a collection

Create a new collection in your vault. Requires a key with read and write permission.

POST /v0/collections

Every field is optional. Passing artworkIds fills the collection at creation time, in the order given; you can also add works later with the add an artwork endpoint.

curl https://api.valise.works/v0/collections
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"title": "Spring Show", "artworkIds": ["ahvxb9zbcew4a0fhroz9ijs0"]}'

On success, the API returns a 201 status code with the new collection. If any of the artworkIds don’t exist in your vault, the API returns a 409 instead and nothing is created.

Update a collection

Update an existing collection. Requires a key with read and write permission.

PATCH /v0/collections/{id}

Only the title and notes fields can be updated, and only the ones you include in the request body are changed. To clear a field, pass an empty string. To change which artworks are in the collection, use the endpoints below.

curl https://api.valise.works/v0/collections/ehptxdig36vlctxmpe89p34n
  --method PATCH
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"title": "Spring Show 2025"}'

On success, the API returns a 200 status code with the updated collection.

Delete a collection

Permanently delete a collection. The artworks in it are not deleted, only their membership in this collection. This cannot be undone. Requires a key with read and write permission.

DELETE /v0/collections/{id}

curl https://api.valise.works/v0/collections/ehptxdig36vlctxmpe89p34n
  --method DELETE
  --header "Authorization: Bearer <API_KEY>"

On success, the API returns a 204 status code with no response body.

Add an artwork to a collection

Add an artwork to the end of a collection. Requires a key with read and write permission.

POST /v0/collections/{id}/artworks

curl https://api.valise.works/v0/collections/ehptxdig36vlctxmpe89p34n/artworks
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"artworkId": "ahvxb9zbcew4a0fhroz9ijs0"}'

On success, the API returns a 200 status code with the updated collection. If the artwork is already in the collection, or isn’t in your vault, the API returns a 409.

Remove an artwork from a collection

Remove an artwork from a collection. The artwork itself is not deleted. Requires a key with read and write permission.

DELETE /v0/collections/{id}/artworks/{artworkId}

curl https://api.valise.works/v0/collections/ehptxdig36vlctxmpe89p34n/artworks/ahvxb9zbcew4a0fhroz9ijs0
  --method DELETE
  --header "Authorization: Bearer <API_KEY>"

On success, the API returns a 204 status code with no response body. Removing an artwork that isn’t in the collection also returns 204.

Reorder a collection

Set the order of the artworks in a collection. Requires a key with read and write permission.

POST /v0/collections/{id}/reorder

The artworkIds array must list every artwork currently in the collection exactly once. This endpoint only changes the order, so use the endpoints above to add or remove works.

curl https://api.valise.works/v0/collections/ehptxdig36vlctxmpe89p34n/reorder
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"artworkIds": ["iogf1yv44dtudcam42a9rx8o", "ahvxb9zbcew4a0fhroz9ijs0"]}'

On success, the API returns a 200 status code with the updated collection. If the list doesn’t match the collection’s current artworks, the API returns a 400 naming each work that’s missing, duplicated, or not in the collection.