Tags API

Tags group artworks together. These endpoints cover the tag record and attaching tags to artworks. Every request needs an API key, as described in the API overview.

Tag names are compared without regard to case or punctuation, so a vault can’t hold both an “Oil on Canvas” and an “oil on canvas” tag. To merge two tags into one, use the Valise dashboard.

List tags

Get all the tags in your vault. Use the IDs here to attach tags to artworks.

GET /v0/tags

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

Here’s an example response:

{
  "data": [
    {
      "id": "d2qv8rb5i88kat33l28g",
      "title": "Painting",
      "slug": "painting"
    }
  ],
  "page": {
    "count": 1,
    "next": null
  }
}

The slug is unique within a vault, so a vault can’t hold both a “Painting” and a “painting” tag.

Create a tag

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

POST /v0/tags

curl https://api.valise.works/v0/tags
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"title": "Works on Paper"}'

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

{
  "data": {
    "id": "d2qv8rb5i88kat33l28g",
    "title": "Works on Paper",
    "slug": "works-on-paper"
  }
}

If a tag with the same name already exists, the API returns a 409 and nothing is created. Use the list tags endpoint to find the existing one.

Rename a tag

Change a tag’s name. The tag keeps its ID, so every artwork already carrying it keeps it. Requires a key with read and write permission.

PATCH /v0/tags/{id}

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

On success, the API returns a 200 status code with the updated tag. If another tag already has that name, the API returns a 409.

Delete a tag

Permanently delete a tag. It’s removed from every artwork carrying it, but the artworks are not deleted. This cannot be undone. Requires a key with read and write permission.

DELETE /v0/tags/{id}

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

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

Add a tag to an artwork

Attach an existing tag to an artwork. The tag must already be in the same vault, so create it first if it doesn’t exist. Requires a key with read and write permission.

POST /v0/artworks/{id}/tags

curl https://api.valise.works/v0/artworks/d2qv8sj5i88kat3bka30/tags
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"tagId": "d2qv8rb5i88kat33l28g"}'

On success, the API returns a 200 status code with the updated artwork. Adding a tag the artwork already has also returns 200 and changes nothing, so it’s safe to retry. If the artwork or the tag isn’t in your vault, the API returns a 404.

Remove a tag from an artwork

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

DELETE /v0/artworks/{id}/tags/{tagId}

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

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