Valise API

Build developer integrations on top of Valise.

The API is a technical feature meant for developers. If you’re looking for ways to get your data out of Valise, check out our export options.

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

The API is currently in private beta. If you’d like to use it and provide feedback, please get in touch.

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 and have read-only access to your data.

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;
};

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.

Status	Description
`200`	Successful request
`400`	Check that the request parameters are correct
`401`	No API key was provided with the request
`403`	The API key provided is invalid
`404`	The resource was not found
`429`	The rate limit has been exceeded
`500`	An error happened with Valise’s servers

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.

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
  }
}

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
  }
}