Formats

Dates

Dates are encoded as strings following the ISO 8601 standard 2021-08-01T12:00:00.000Z.

Pagination

A maximum of 100 objects can be returned per request and the limit can be specified by using the pageSize query parameter. By default, pageSize is set to 25.

Metadata

Some objects have a metadata parameter that you can use to store key-value data.

You may specify up to 20 keys, with key names up to 40 characters long and values up to 250 characters long.

IDs

All ID fields are case-sensitive. For example, abc123 and ABC123 are treated as different IDs.

Monetary Values

Throughout the API, monetary values are encoded as integers representing the amount in the smallest currency unit, for example 100 cents for a donation of $1.00. Currency is encoded as a string following the ISO 4217 standard (e.g. USD).

Errors

The API returns standard HTTP response codes to indicate success or failure of API requests. Errors may include a custom error message. Error objects have these attributes, an id, a message corresponding to the HTTP response phrase of the error, an optional invalid-params attribute detailing issues with the request.

An example error object returned from the API:

{
  error: {
    code: 'bad_request',
    title: 'Bad request',
    message: 'Something is wrong with your request, please check any parameters and try again',
    reasons: ['amount is a required field']
  }
}

A summary of the HTTP status codes returned from the api is listed in the table below.

Code	Title	Description
200	Success	Request successful
204	No Content	Request successful with no content returned
400	Bad Request	Request was invalid
401	Unauthorised	Authorization header is invalid
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
429	Too Many Requests	Rate Limited
500s	Internal Server Error	Something went wrong with the Goodstack API

Enum Values

Generally enum fields in our API are open-ended. New values may be added to an enum and this is not considered a breaking change.

If your code handles enum values exhaustively — for example, a switch without a default case, or deserialisation into a strict typed enum — an unrecognised value may cause errors.

We recommend adding a fallback handler for unknown enum values, so that any new value that does reach your integration degrades gracefully rather than failing.

Some endpoints that return enum fields support filtering by those values as query parameters, letting you restrict responses to the values your integration supports.