Jun 6 News: Commission Types Finished! hide

We have finished development of commission types! Please give it a spin and try creating one today! Note that actions do not yet work (with the exception of wishlisting), however, they can be fully shared! (read more at our blog).

API Documentation

API Documentation

Introduction

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: https://catalystapp.co/api/. 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_code: an error code specific to the endpoint. Zero on success.
  • 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

Generic error codes

  • 10001: Endpoint not found
  • 10002: Invalid method ("GET", "POST", etc)
  • We have many internal error codes which may mean different things, however 99999 is likely the only one you will see.

  • 99990: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99991: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99992: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99993: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99994: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99995: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99996: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99997: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99998: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.
  • 99999: An internal error occured. Please contact bugs@catalystapp.co with the timestamp, what you were doing, and an explaination of the issue.

API Keys

In order to use our API, contact us at api@catalystapp.co 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

Error codes

  • 11001: Client header not passed
  • 11002: User header not passed
  • 11003: Client header is invalid
  • 11004: User header is invalid
  • 11005: Client does not exist (was your API access revoked?)
  • 11006: User tokens are invalid (did the user revoke your API access to their account?)

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 bugs@catalystapp.co 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 bugs@catalystapp.co with the timestamp and an explaination of the issue.

User: get

https://catalystapp.co/api/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

Response

  • 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 https://catalystapp.co/.
  • 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