Goodstack Categories API
Categories represent collections of Organisations, which can be used to group and filter Organisations.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/goodstack:goodstack-categories-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Goodstack Services Categories API
version: v1
x-logo:
url: https://docs.goodstack.io/img/logo.png
altText: Goodstack logo
x-dark-logo:
url: https://docs.goodstack.io/img/icons/Logo-white.svg
altText: Goodstack logo
contact:
email: engineering-support@goodstack.io
name: Api support
description: '# Introduction
Goodstack API allows you to build good into your product by facilitating charitable donations. We achieve this through the API''s listed and specified in this documentation. For all donations using the Goodstack API, Goodstack handles the vetting and validation of the good causes and onward the disbursement of the donation. The Goodstack API is organised around REST. All API responses, including errors, return JSON and use standard HTTP response codes. In all API requests you must specify the content-type HTTP header as application/json. All API requests must be made over HTTPS. # Authentication
Authenticate your API requests by setting your live secret API key in the Authorization header. Two keys are provided to you, a publishable key prefixed with `pk_` and a secret key prefixed with `sk_`. Publishable API keys are meant solely to identify your goodstack account. These can safely be published in places like your JavaScript code, or in an Android or iPhone app and are meant for usage with our SDKs. Secret API keys should be kept confidential and only used in secure server environments. Anywhere that accepts a Publishable key will also accept a Secret key, but routes marked to accept a Secret key will not accept a Publishable key. # Formats
## IDs
All ID fields are case-sensitive. For example, `abc123` and `ABC123` are treated as different IDs. ## Dates
Dates are encoded as strings following the ISO 8601 standard `2025-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, the pageSize is set to 25. A `_links` object is included in paginated responses, which contains `next` and `prev` URLs to retrieve the next or previous pages of results. ## 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`). ## Metadata
Some objects have a metadata parameter that you can use to store key-value data. You can specify up to 20 keys, with key names up to 40 characters long and values up to 250 characters long. ## 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:
```json
{
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. ## Integrating safely
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.'
servers:
- url: https://api.goodstack.io
description: Production server
- url: https://sandbox-api.goodstack.io
description: Sandbox server
tags:
- name: Categories
description: Categories represent collections of Organisations, which can be used to group and filter Organisations.
paths:
/v1/categories:
get:
security:
- PublishableApiKey: []
summary: List Categories
tags:
- Categories
responses:
'200':
description: Successfully retrieved a list of Categories
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Category'
totalResults:
type: integer
example: 33
pageSize:
type: integer
example: 25
_links:
$ref: '#/components/schemas/CursorLinks'
object:
type: string
example: Category
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
IncorrectParams:
$ref: '#/components/examples/IncorrectParams'
CursorError:
$ref: '#/components/examples/Pagination.CursorError'
'401':
$ref: '#/components/responses/Unauthorized'
operationId: getV1Categories
x-operation-id-source: derived
post:
summary: Create a Category
tags:
- Categories
security:
- SecretApiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: New Category name
attributes:
type:
- object
- 'null'
additionalProperties:
oneOf:
- type: string
- type: boolean
- type: number
description: A user-defined record of key-value pairs where the value can be a string, boolean, number, or null.
responses:
'200':
description: Successfully created a Category
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Category'
object:
type: string
example: Category
'400':
$ref: '#/components/responses/IncorrectParams'
'401':
$ref: '#/components/responses/Unauthorized'
operationId: postV1Categories
x-operation-id-source: derived
/v1/categories/{id}:
parameters:
- in: path
name: id
schema:
type: string
required: true
description: Id of the Category
patch:
summary: Edit a Category
tags:
- Categories
security:
- SecretApiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: New Category name
attributes:
type:
- object
- 'null'
additionalProperties:
oneOf:
- type: string
- type: boolean
- type: number
description: A user-defined record of key-value pairs where the value can be a string, boolean, number, or null.
responses:
'200':
description: Successfully edited a Category
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Category'
object:
type: string
example: Category
'400':
$ref: '#/components/responses/IncorrectParams'
'401':
$ref: '#/components/responses/Unauthorized'
operationId: patchV1CategoriesById
x-operation-id-source: derived
delete:
security:
- SecretApiKey: []
summary: Delete a Category
tags:
- Categories
responses:
'204':
description: Successfully deleted a Category
'400':
$ref: '#/components/responses/IncorrectParams'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: deleteV1CategoriesById
x-operation-id-source: derived
get:
security:
- PublishableApiKey: []
summary: Retrieve a Category
tags:
- Categories
responses:
'200':
description: Successfully retrieved a Category
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Category'
object:
type: string
example: Category
'400':
$ref: '#/components/responses/IncorrectParams'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
operationId: getV1CategoriesById
x-operation-id-source: derived
/v1/categories/{categoryId}/{organisationId}:
parameters:
- in: path
name: categoryId
schema:
type: string
required: true
description: Id of the Category
- in: path
name: organisationId
schema:
type: string
required: true
description: Id of the organisation
put:
security:
- SecretApiKey: []
summary: Add a Organisation to a Category
tags:
- Categories
responses:
'200':
description: Successfully add an Organisation to a Category
'400':
$ref: '#/components/responses/IncorrectParams'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
operationId: putV1CategoriesByCategoryIdByOrganisationId
x-operation-id-source: derived
delete:
security:
- SecretApiKey: []
summary: Remove a Organisation from a Category
tags:
- Categories
responses:
'204':
description: Successfully remove a Organisation from a Category
'400':
$ref: '#/components/responses/IncorrectParams'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
operationId: deleteV1CategoriesByCategoryIdByOrganisationId
x-operation-id-source: derived
/v1/categories/{categoryId}/image:
parameters:
- in: path
name: categoryId
schema:
type: string
required: true
description: Id of the Category
post:
security:
- SecretApiKey: []
summary: Set an Image for a Category
tags:
- Categories
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
responses:
'200':
description: Successfully add an image to a Category
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
TooManyAttachments:
$ref: '#/components/examples/Upload.TooManyAttachments'
ContentTypeError:
$ref: '#/components/examples/Upload.ContentTypeError'
MaxFileSize:
$ref: '#/components/examples/Upload.MaxFileSize'
FiletypeNotSupported:
$ref: '#/components/examples/Upload.FiletypeNotSupported'
BadRequest:
$ref: '#/components/examples/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: postV1CategoriesByCategoryIdImage
x-operation-id-source: derived
components:
examples:
Upload.TooManyAttachments:
summary: Upload - Too many attachments
description: Too many files attached
value:
error:
code: upload/too_many_files
title: Bad request
message: 'Too many files attached (max: 1)'
Upload.MaxFileSize:
summary: Upload - File exceeded max size
description: File exceeded max size for this endpoint
value:
error:
code: upload/max_file_size
title: Bad request
message: Request size exceeded maximum for this endpoint (5242880 bytes)
IncorrectParams:
summary: 400 Incorrect Parameters
description: Bad Request - Incorrect parameters
value:
error:
code: bad_request
title: Bad request
message: One or more of the inputs were invalid
reasons:
- pageSize must be greater than or equal to 0
Upload.ContentTypeError:
summary: Upload - Content type error
description: Unsupported content type
value:
error:
code: upload/content_type_error
title: Bad request
message: 'Unsupported content type: xls'
BadRequest:
summary: 400 Bad Request
description: Bad Request
value:
error:
code: bad_request
title: Bad request
message: Something is wrong with your request, please check any parameters and try again
Pagination.CursorError:
summary: Error in cursor parameter
description: We were unable to decode the cursor
value:
error:
code: pagination/cursor_error
title: Bad request
message: Unable to find the next page
Upload.FiletypeNotSupported:
summary: Upload - Filetype not supported
description: Filetype not supported
value:
error:
code: upload/filetype_not_supported
title: Bad request
message: 'Filetype not supported. Supported types include: pdf, png, jpg'
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
title:
type: string
message:
type: string
reasons:
type:
- array
- 'null'
items:
type: string
CursorLinks:
type: object
properties:
current:
type: string
example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
next:
type: string
example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
prev:
type: string
example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
Category:
type: object
properties:
id:
type: string
example: category_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
name:
type: string
example: Environmental
imageUrl:
type:
- string
- 'null'
example: categories/3.png
attributes:
type:
- object
- 'null'
additionalProperties:
oneOf:
- type: string
- type: boolean
- type: number
description: A user-defined record of key-value pairs where the value can be a string, boolean, number, or null.
createdAt:
type: string
format: date-time
example: '2020-10-13T17:46:54.000Z'
responses:
Forbidden:
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: forbidden
title:
type: string
example: Forbidden
message:
type: string
example: Access is denied due to insufficient privileges
IncorrectParams:
description: Error validating inputs
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: bad_request
title:
type: string
example: Bad request
message:
type: string
example: One or more of the inputs were invalid
reasons:
type: array
items:
type: string
example: pageSize must be greater than or equal to 0
NotFound:
description: The specified resource was not found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: not_found
title:
type: string
example: Resource not found
message:
type: string
example: This endpoint is unavailable or can not be found
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: unauthorized
title:
type: string
example: Unauthorized
message:
type: string
example: Access is denied due to invalid credentials
securitySchemes:
PublishableApiKey:
type: apiKey
in: header
name: Authorization
description: API key starting with 'pk_' that can be made public
SecretApiKey:
type: apiKey
in: header
description: API key starting with 'sk_' that must be kept secure
name: Authorization
DonationSessionToken:
type: apiKey
in: header
name: donation-session-token
description: Donation session token
SCIMBearer:
type: http
scheme: bearer
description: 'SCIM API key issued for the partner, presented as a bearer token in the
`Authorization` header. The key is bound to a single partner and the
partner must have the `scim_api` scope enabled. A missing or invalid key
returns `401`; a valid key for a partner without the scope also returns
`401` (`detail: "scim feature not enabled for this partner"`).
'
x-tagGroups:
- name: NONPROFIT DATA
tags:
- Organisations
- Countries
- Registries
- Categories
- Organisation Branding
- name: NONPROFIT VALIDATIONS
tags:
- Validation Requests
- Validation Request Documents
- Validation Invites
- Validation Submissions
- Validation Submission Documents
- Validation Submission Configuration
- Monitoring Subscriptions
- Eligibility Subscriptions
- Activities
- Agent Verifications
- name: MONETARY DONATIONS
tags:
- Donations
- Donation Sessions
- Users
- Gift Aid
- Monetary Donation Verifications
- name: WORKPLACE GIVING
tags:
- Employees
- Giving Donations
- Donation Match Request
- Fundraising
- Volunteering
- Gamification
- Campaigns
- Budgets
- Donation Wallets
- name: WEBHOOK SUBSCRIPTIONS
tags:
- Webhook Subscriptions
- name: WEBHOOK EVENTS
tags:
- Agent Verification Events
- Country Compliance Check Events
- Donation Events
- Eligibility Subscription Events
- Monitoring Subscription Events
- Validation Request Events
- Validation Submission Events
- Monetary Donation Verification Events
x-provenance:
method: harvested
publisher: Goodstack
source: https://reference.poweredbypercent.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)