Skip to main content

API v1 reference

Starter read-only API routes, authentication header, success envelope, and common errors.

SectionAPI and integrations / API reference
PurposeAPI reference
UpdatedJul 6, 2026
AuthorTemplate Maintainers
Versionv1.2.0
Reading time2 min

API v1 reference

The starter /api/v1 routes are public from the browser-session perspective but require a valid API key. Send the key in the x-api-key header.

curl -H "x-api-key: $API_KEY" http://localhost:3000/api/v1/me

Response envelope

Successful responses use a data envelope:

{
  "data": {}
}

Handled errors use an error envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "API key is required."
  }
}

Endpoints

Method and pathPurpose
GET /api/v1/meReturns the resolved API key principal.
GET /api/v1/organizationsLists organizations visible to the principal.
GET /api/v1/organizations/:organizationIdReturns one visible organization.
GET /api/v1/organizations/:organizationId/membersLists members in one organization.
GET /api/v1/organizations/:organizationId/teamsLists teams in one organization.
GET /api/v1/organizations/:organizationId/teams/:teamId/membersLists members in one team.

Principal rules

Personal keys resolve to a user principal. They can read organization data only while that user is a member of the organization.

Workspace keys resolve to an organization principal. They can read only the organization that owns the key.

Common errors

StatusMeaning
401The key is missing or invalid.
403The key is valid but lacks permission for the route or organization.
404The requested organization or team is not visible to the key.
429The key exceeded its rate limit.

Related pages