Valise API

Valise offers a REST API for programmatically accessing your data. You can use this API to build integrations on top of Valise, such as:

• Powering a website with artworks from your vault
• Updating data in other systems when it changes in Valise

Getting Started

To start using the API, create an API key from the developer settings of your dashboard. You can use this key to authenticate to the API calls described in the endpoints section.

Overview

Base URL

All requests should be made to the following base URL:

https://api.valise.works

Authentication

The API uses API keys to authenticate requests. For any endpoint, pass a Bearer token in the Authorization header of the request.

Authorization: Bearer <API_KEY>

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

fetch("https://api.valise.works/v0/artworks", {
  headers: {
    Authorization: "Bearer <API_KEY>",
  },
})

To generate an API key, go to the developer settings of your dashboard and press the Create API key button.

API keys are associated with a vault, not with a user account, so you don’t need to worry about leaving a vault revoking the key’s access. By default, keys don’t expire.

Permissions

When you create a key, you choose its scope:

• Read-only keys can fetch data using the GET endpoints. This is the default.
• Read and write keys can additionally create, update, and delete artworks.

If a read-only key is used on a write endpoint, the API responds with a 403 error. Keys created before scopes were introduced are read-only.

Pagination

When an API response returns a list of records, information about pages will be returned in the response.

By default, up to 100 items are returned per page, which is the maximum value. You can change this limit by passing the limit query parameter to the endpoint.

Paginated responses will look like this:

{
  "data": [ ... ],
  "page": {
    "count": 100, // Number of items in the current page
    "next": "https://api.valise.works/..." // Next page of results, or null if no more
  }
}

You can use the page.next URL to make additional requests to get all the records by looping through the values until they return null.

For example, here’s how you could fetch all the artworks in your vault in Javascript:

const fetchArtworks = async () => {
  let artworks = []
  let next = "https://api.valise.works/v0/artworks"
  while (next) {
    // Note: authentication and error handling are omitted here for brevity.
    const response = await fetch(next)
    const data = await response.json()
    artworks.push(...data.data)
    next = data.page.next
  }
  return artworks
}

Rate limiting

The API allows up to 300 requests per minute. Every response includes headers so you can track your usage:

If you exceed the limit, the API will return a 429 status code. You should wait for the number of seconds in the Retry-After header before retrying.

Response codes

We use standard HTTP codes to indicate the success or failure of a request. In general, 2xx codes indicate success, 4xx codes indicate client errors, and 5xx codes indicate infrastructure issues.

Errors

When an API request fails, Valise returns a structured error response that follows this format:

{
  "error": {
    "code": "unauthenticated",
    "message": "Please provide a valid API key with your request."
  }
}

The HTTP status code should give you a general sense of the error category, and the error.code field will give you a more specific reason for the error.

When a request fails validation, the response also includes a details array describing every problem at once, so you can fix them in a single pass. Each entry names the offending field (when applicable) and a message:

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid.",
    "details": [
      { "field": "title", "message": "Must be at most 500 characters." },
      { "field": "uid", "message": "Must be a valid UID, e.g. \"VD-123\"." }
    ]
  }
}

Endpoints

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",
      "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"
        }
      ],
      "createdAt": "2024-09-06T11:17:15.150Z",
      "updatedAt": "2024-09-06T11:17:15.150Z"
    }
  ],
  "page": {
    "count": 1,
    "next": null
  }
}

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

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.

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",
      "artworkIds": [
        "ahvxb9zbcew4a0fhroz9ijs0",
        "iogf1yv44dtudcam42a9rx8o",
        "bes9dncmjfv9o2xbtrskzc1r"
        // ...
      ],
      "createdAt": "2024-09-06T11:17:15.150Z",
      "updatedAt": "2024-09-06T11:17:15.150Z"
    }
  ],
  "page": {
    "count": 1,
    "next": null
  }
}

Community Resources

Valise users have built framework specific integrations on top of our API that may be helpful when working with the API:

• astro-loader-valise, for loading collections and artworks into an Astro-based site.