Skip to content

Overview

The Artist Alley REST API is served under /api/v1 on your instance. Requests and responses normally use JSON. Some endpoints use other media types, for example to upload or download files, and their pages say which.

Authenticating

Most requests must be authenticated with one of these two methods:

  • Session cookie: POST /auth/login with a username and password sets a user session cookie. Browser clients use this automatically.
  • API token: from a signed-in session, POST /auth/tokens mints a personal access token that looks like aa_pat_…. Send it on every request: Authorization: Bearer aa_pat_…. A token acts with your account’s full permissions: scopes can be recorded on a token, but they are not enforced yet. Give each token an expiry and revoke the ones you no longer use.

A first request

curl https://your-instance/api/v1/auth/me \
  -H "Authorization: Bearer aa_pat_your_token_here"

Errors

A failed request returns a 4xx or 5xx HTTP status. The body is usually JSON, with a short, human-readable message in an error field: { "error": "…" }.

Not every error looks like that, so check the status code before you read the body. Some errors add more fields or return a different body, and a few have no body at all. If a parameter or the request body can’t be parsed, or the server fails unexpectedly, you can get a plain-text body instead.

Each endpoint’s page lists the statuses and response bodies declared for it.

  • OpenAPI version: 3.0.3

Session cookie issued by POST /auth/login. It is named user for historical reasons; renaming it would sign every account out.

Security scheme type: apiKey

Cookie parameter name: user

Personal Access Token, format aa_pat_<32 chars>. Issued via POST /auth/tokens. Send as Authorization: Bearer aa_pat_....

Security scheme type: http

Bearer format: aa_pat