May 14 News: New Terms of Service! hide

Our Terms of Service have been written! By using or accessing Catalyst, you agree to be bound by these terms. You may read the full document here.

API Documentation

API Documentation


This page tells you how to use Catalyst's API to do awesome things!

Catalyst's API is based around a HTTPS/REST API, and operates through GET and POST operations. Your client must support both of these methods as well as TLS v1.2.

All API endpoints are based off of our base URL: From there, endpoints are separated by scope (user, artist, commission, etc.) then method (create, delete, reorder, etc.), then further parameters if required.

All requests should contain your authorization headers (see below), as well as a JSON payload which contains parameters

A ? before a parameter name means that it is optional, and a ? before a reponse parameter name means that it may be omitted from the response. The ? is NOT part of the parameter.

A ? before a type indicates that it may be null.

All proper endpoints (not 301, 404, or similar) will return a JSON object. This object will contain the following keys:

  • error: a boolean which states whether or not the request succeeded.
  • http_code: the HTTP code returned (see Response Codes)
  • error_location: the component of the request where the issue occured or _global if the issue applies to the request as a whole (or a server error occured).
  • error_type: the type of error, generally specific to the datatype and context. Common examples include requiredButMissing and doesNotExist
  • message: a message containing more information ("Success", "Invalid Password")
  • data: an object which contains any applicable return data
  • ?_debug: debug information which we use to squish bugs

API Keys

In order to use our API, contact us at for credentials. Please include your Catalyst username, name of your app, and a description of what you intend to do.

Requests may take up to one week to be processed.

Upon creation of your app, you will be assigned a set of four tokens: a client ID which identifies your app, a client secret which verifies ownership of the app, an access token which authenticates a user (the one we provide will be your own), and an access secret (additional verification)

All requests to our API must contain the following headers:

  • Client: A string which contains your client ID and secret, separated by a comma.
  • Example: Client: v8ayeztxskdm8x0sm,xm0xzvm3jncdjsm1iejasjkfv8mkktbyrmzakegcwnc9pmw107fbmy3zbwls

  • User: A string which contains your user's access token and secret, separated by a comma.
  • Example: User: 4yt43e1wbgzt1397wcbpv249v51vroh2doc8uhte,2s9wc0nr9d7z17hh6943d66e5br06pnrpt6f3noz42mc9vsep43rg7nf7xai

Response Codes

Our API can return a lot of different response codes, depending on what happened.

  • 200 (OK): The request was successfully completed.
  • 201 (CREATED): The request was successfully completed, and something was created as a result.
  • 202 (DEFERRED): The request was recognized, but will be completed later (sending emails for example).
  • 301 (MOVED): Send the request to the location provided in the Location header. Only used if you did not include a trailing slash.
  • 304 (NOT_MODIFIED): The request was recieved, but nothing changed.
  • 400 (BAD_REQUEST): The request was recieved, but it was invalid.
  • 401 (UNAUTHORIZED): The Client or User headers are missing or invalid.
  • 403 (FORBIDDEN): The provided tokens do not have access to the specified resource.
  • 404 (NOT_FOUND): You tried to access something which does not exist.
  • 405 (BAD_METHOD): The HTTP method was invalid for this location.
  • 418 (TEAPOT): I'm a teapot? Background
  • 429 (RATE_LIMITED): You've made too many requests. Chill out for a bit. If this error persists, contact support.
  • 500 (ERROR): We broke something. If you recieve this error, please email with the timestamp and an explaination of the issue.
  • 501 (UNIMPLEMENTED): We haven't made this yet.
  • 503 (MAINTENANCE): Catalyst is down, likely for upgrades.
  • 5xx (???): Something is very broken. Please contact with the timestamp and an explaination of the issue.

User: get

Gets either the current user or one specified by their username

GET Parameters

  • ?name string Username to get data for. Omit for current user


  • username string The User's username.
  • ?email ?string The User's email; only provided for logged-in user.
  • ?email_verified bool If the user has verified their email; only provided for logged-in user. Always returns true if the user's email is not set
  • artist_page_url ?string If the user has an artist page, this field will contain their URL
  • picture_loc string This contains the path for the user's profile picture, or profile_pictures/default.png if none is set. Append this path to
  • picture_nsfw bool If the profile picture is NSFW. Always false for default image.
  • ?nsfw bool If the user has NSFW access; only provided for logged-in user.
  • color string(6) The user's color of preference, as a 6-character hex.

Error codes

  • 20001: User account does not exist, has been suspended, or is deactivated