1. Create a token

Open Settings → Developers → Create API Token. You need account:api:access. Give the token a name and expiry, select programmes:read:programmes for this example, and copy it immediately after creation. You must hold that permission and have Programmes enabled in the workspace.

Copy the Tenant ID from Settings → User. Set TSB_TOKEN and TSB_TENANT_ID in your local environment without committing them to source control. For integrations acting with user consent, follow the OAuth authorisation-code guide.

2. Make your first request 

curl https://api.thirdsectorbee.com/v1/programmes/programmes \
  -H "Authorization: Bearer $TSB_TOKEN" \
  -H "X-Tenant-Id: $TSB_TENANT_ID"

Copy endpoint paths from the module reference, including their /v1/ prefixes.

3. Read the response

The Programmes list returns a data array and meta object. For a workspace with no programmes:

{
  "data": [],
  "meta": { "count": 0 }
}

If meta.nextCursor is present, use it as the next request’s cursor. Continue until it is absent, even if a filtered page is empty.

curl --get https://api.thirdsectorbee.com/v1/programmes/programmes \
  -H "Authorization: Bearer $TSB_TOKEN" \
  -H "X-Tenant-Id: $TSB_TENANT_ID" \
  --data-urlencode "cursor=$CURSOR" \
  --data-urlencode 'limit=50'

This endpoint defaults to 50 items and caps the page limit at 200. Other modules have different envelopes and paging rules; inspect the operation’s schema.

4. Handle errors

Many module endpoints return a nested error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "X-Tenant-Id header is required"
  }
}

Account endpoints can also return {"error":"message"}, and gateway failures can return {"message":"Forbidden"}. Check HTTP status and the actual body shape before reading error.code.

  • 400: correct the input, tenant header or pagination cursor before retrying.
  • 401 or 403: check credentials, membership and permissions using Authentication.
  • 404: check the ID and endpoint path; records may also be inaccessible to the caller.
  • 409: resolve the reported conflict or invalid state transition.
  • 500/503: inspect the error. TENANT_NOT_PROVISIONED needs administrator attention; retrying alone cannot enable a module.

Retry transient reads with a bounded delay. Before retrying a write, check the endpoint’s idempotency guarantees so you do not duplicate data.

Writes and reads

Success codes differ by operation. Some commands return 202 Accepted while other writes return 200 or 201. An accepted asynchronous command is not proof that downstream processing has finished. Retain the returned identifier and check the relevant read or status endpoint after a delay.

See API concepts for consistency and tenant scope, and the API modules for complete request and response schemas.