Artworks API

List, create, update, and delete artworks.

These endpoints cover the artwork record itself. Tags on an artwork are managed through the tags endpoints, and the location of an edition through the locations endpoints. Every request needs an API key, as described in the API overview.

List artworks

Get information about all the artworks in your vault by calling this endpoint.

GET /v0/artworks

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

Here’s an example response:

{
  "data": [
    {
      "id": "d2qv8sj5i88kat3bka30",
      "uid": "VD-123",
      "title": "My Artwork",
      "year": "2022",
      "medium": "Acrylic on paper",
      "dimensions": "35.56h x 31.75w x 3.81d cm; 14.0h x 13.0w x 2.0d in",
      "notes": "Stored in the flat file, second drawer.",
      "images": [
        {
          "id": "d2qv94c5i88kavrvigcg",
          "type": "image",
          "url": "https://uploads.valise.works/...",
          "width": 1024,
          "height": 1024,
          "filename": "my-artwork.jpg"
        }
      ],
      "tags": [
        {
          "id": "d2qv8rb5i88kat33l28g",
          "slug": "painting",
          "title": "Painting"
        }
      ],
      "editions": [],
      "createdAt": "2024-09-06T11:17:15.150Z",
      "updatedAt": "2024-09-06T11:17:15.150Z"
    }
  ],
  "page": {
    "count": 1,
    "next": null
  }
}

If the artwork has editions, they’re listed in the editions array:

{
  "id": "d2qv8sj5i88kat3bkbb0",
  "type": "ap",
  "editionNumber": 1,
  "editionSize": 2,
  "locationId": "d2qv9c35i88kat3bkc7g"
}

The type is none for regular editions, ap for artist proofs, pp for printer proofs, and ec for exhibition copies. An artwork of 12+2AP has an editionSize of 12 for the regular editions and 2 for the artist proofs.

The locationId points to the location where the edition is kept, and is left out when the edition has none.

Get an artwork

Fetch a single artwork by its ID.

GET /v0/artworks/{id}

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

The response is a single artwork in the same shape as the entries in the list artworks response:

{
  "data": {
    "id": "d2qv8sj5i88kat3bka30",
    "uid": "VD-123",
    "title": "My Artwork"
    // ...
  }
}

Create an artwork

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

POST /v0/artworks

The request body accepts the following fields. Only title is required; Valise generates the artwork’s id and, if you don’t provide one, its uid.

Field	Type	Description
`title`	string	The title of the artwork. Required.
`uid`	string	A user-provided ID (e.g. `VD-123`). If omitted, Valise generates the next UID for the vault.
`year`	string	The year the artwork was created.
`medium`	string	The medium of the artwork.
`dimensions`	string	The dimensions of the artwork.
`notes`	string	Free-form notes about the artwork.

curl https://api.valise.works/v0/artworks
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"title": "My Artwork", "year": "2022", "medium": "Acrylic on paper"}'

On success, the API returns a 201 status code with the new artwork:

{
  "data": {
    "id": "d2qv8sj5i88kat3bka30",
    "uid": "VD-123",
    "title": "My Artwork",
    "year": "2022",
    "medium": "Acrylic on paper",
    "dimensions": "",
    "notes": "",
    "images": [],
    "tags": [],
    "editions": [],
    "createdAt": "2024-09-06T11:17:15.150Z",
    "updatedAt": "2024-09-06T11:17:15.150Z"
  }
}

Update an artwork

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

PATCH /v0/artworks/{id}

Only the fields you include in the request body are changed; omitted fields are left untouched. The body accepts the same fields as creating an artwork, all of which are optional here. To clear a field, pass an empty string.

Every artwork keeps a uid, so it can’t be cleared. Pass a new value to change it.

curl https://api.valise.works/v0/artworks/d2qv8sj5i88kat3bka30
  --method PATCH
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"title": "Updated Title"}'

On success, the API returns a 200 status code with the updated artwork, in the same shape as the create response.

Delete an artwork

Permanently delete an artwork and all of its associated data. This cannot be undone. Requires a key with read and write permission.

DELETE /v0/artworks/{id}

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

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