Authentication

Every request to /api/v1/* and /api/mcp authenticates with an API key from /account/developers.

Header format

Authorization: Bearer im_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys act as your user: workspace reads and writes are scoped to the account that created the key. Revoking a key at /account/developers takes effect immediately.

Rate limits

Each key allows 100 requests per minute. Exceeding it returns 429 with a Retry-After header (seconds until the window resets):

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{"error": {"code": "rate_limited", "message": "Rate limit exceeded for this API key."}}

Error shape

All errors are JSON with a stable machine-readable code:

{"error": {"code": string, "message": string}}

Status	Code	When
400	`invalid_taxonomy`	An explicit `?taxonomy=` id is not a published activity taxonomy for the resolved landscape.
401	`missing_api_key` / `invalid_api_key`	No or bad `Authorization` header.
404	`unknown_landscape` / `unknown_group` / `unknown_org` / `unknown_target` / `not_found`	The referenced resource doesn't exist (an explicit `?landscape=` slug is never silently substituted).
403	`forbidden`	A workspace resource owned by a different user.
409	`duplicate_item`	The org/group is already on that list.
422	`validation_error`	Body or query failed validation — the message names the field.
429	`rate_limited`	Key over 100 req/min — respect `Retry-After`.

Pagination

List endpoints accept ?limit= (default 50, max 200) and ?offset=, and respond with an envelope:

{"data": [...], "total": 123, "limit": 50, "offset": 0, "meta": {...}}

Scope & reproducibility

Warehouse read endpoints accept ?landscape=<slug> (default: the default landscape) and ?taxonomy=<id> (default: that landscape's default published activity taxonomy). Pin both parameters to make repeated results reproducible:

curl "https://ny.northstartoolkit.com/api/v1/taxonomy?landscape=YOUR_LANDSCAPE&taxonomy=14" \
  -H "Authorization: Bearer YOUR_API_KEY"

{"data": [...], "meta": {"landscape": "YOUR_LANDSCAPE", "taxonomy_id": 14}}

meta.taxonomy_id echoes the resolved taxonomy version. Pass that id back as the taxonomy parameter to pin it — taxonomies are versioned artifacts and the default can change between data releases.