Locations API

Manage the places where works are kept.

Locations are the places where works are kept: a studio, a storage unit, a gallery. Editions reference a location by its ID in their locationId field, so use these endpoints to turn that ID into a name. Every request needs an API key, as described in the API overview.

List locations

Get all the locations in your vault.

GET /v0/locations

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

Here’s an example response:

{
  "data": [
    {
      "id": "d2qv9c35i88kat3bkc7g",
      "title": "Studio",
      "notes": "Key with the front desk.",
      "createdAt": "2024-09-06T11:17:15.150Z",
      "updatedAt": "2024-09-06T11:17:15.150Z"
    }
  ],
  "page": {
    "count": 1,
    "next": null
  }
}

Get a location

Fetch a single location by its ID.

GET /v0/locations/{id}

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

The response has the same shape as a single entry in the list locations endpoint. If the location isn’t in your vault, the API returns a 404.

Create a location

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

POST /v0/locations

Field	Type	Description
`title`	string	The name of the location, up to 400 characters. Required.
`notes`	string	Free-form notes, up to 8,000 characters.

curl https://api.valise.works/v0/locations
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"title": "Storage Unit B", "notes": "Second floor, unit 12."}'

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

{
  "data": {
    "id": "d2qv9c35i88kat3bkc7g",
    "title": "Storage Unit B",
    "notes": "Second floor, unit 12.",
    "createdAt": "2024-09-06T11:17:15.150Z",
    "updatedAt": "2024-09-06T11:17:15.150Z"
  }
}

Update a location

Change a location’s name or notes. Only the fields you pass are changed, and the location keeps its ID, so every edition kept there keeps pointing to it. Requires a key with read and write permission.

PATCH /v0/locations/{id}

Field	Type	Description
`title`	string	The new name for the location, up to 400 characters.
`notes`	string	Free-form notes, up to 8,000 characters. Pass `""` to clear.

curl https://api.valise.works/v0/locations/d2qv9c35i88kat3bkc7g
  --method PATCH
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"title": "Storage Unit C"}'

On success, the API returns a 200 status code with the updated location.

Delete a location

Permanently delete a location. Editions kept there are left without a location, but the editions themselves are not deleted. This cannot be undone. Requires a key with read and write permission.

DELETE /v0/locations/{id}

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

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