Artworks API

These endpoints cover the artwork record itself and its images. 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"
        }
      ],
      "artistIds": ["d2qv9c35i88kat3bkc7g"],
      "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.

Unassigned editions aren’t included in the list.

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

The artistIds field lists the contacts credited as artists on the work, and is empty when no one is credited. Change it with the credit and remove endpoints.

The images field lists the artwork’s images in gallery order. Each image’s id is the ID of the upload holding its file. Add them with the add an image endpoint.

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.

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": [],
    "artistIds": [],
    "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.

Add an image

Add an uploaded image to an artwork. Requires a key with read and write permission.

POST /v0/artworks/{id}/images

First create an upload with the artworkImage kind and send it the file. Once the upload is ready, link it here. The image appears in the artwork’s images, last in the gallery unless you give it a position. Adding an image the artwork already has succeeds and changes nothing. An upload can only be linked once.

curl https://api.valise.works/v0/artworks/d2qv8sj5i88kat3bka30/images
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"uploadId": "d2qv94c5i88kavrvigcg", "position": 0}'

On success, the API returns a 200 status code with the updated artwork, in the same shape as the get artwork response. If the upload’s file hasn’t arrived yet, or it’s already linked to another artwork, the API returns a 409. If the upload was created with another kind, it returns a 400.

Remove an image

Remove an image from an artwork. Requires a key with read and write permission.

DELETE /v0/artworks/{id}/images/{uploadId}

The uploadId is the image’s id in the artwork’s images.

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

On success, the API returns a 204 status code with no response body. Removing an image the artwork doesn’t have also returns 204.