REST API

The ServerChirp REST API exposes team-scoped resources at /api/v1/*. The dashboard and API tokens use the same endpoints, schemas, authorization rules, plan gates, and rate limits.

Create a token

Open the team's API settings, create a token, and select only the required scopes. The plaintext token is shown once. Store it in a secret manager and never commit it to a repository.

Send it as a Bearer token:

curl https://serverchirp.com/api/v1/servers \
  --header "Authorization: Bearer $SERVERCHIRP_TOKEN" \
  --header "Accept: application/json"

Scopes

Scopes use a resource and operation, such as servers:read or deployments:write. Read scopes inspect resources. Write scopes create or change state.

The same scope declared by an API route authorizes the corresponding assistant and MCP tool. A tool cannot be more permissive than its endpoint.

Responses

Wire shapes derive from the same public schemas used by the product. Lists are paginated and relationship counts are flattened. Optional related resources appear only when the endpoint includes them.

Secret values are absent from normal resource schemas. Create-once secrets appear only in the create response when the resource supports one.

Errors

Expected errors use a stable API error envelope and appropriate HTTP status. A missing resource and one outside the principal's scope both return not found.

Rate-limited responses use HTTP 429 and include Retry-After. Clients should wait for that duration and avoid automatically retrying other 4xx responses.

Streaming exceptions

SSE, multipart browser uploads, and signed backup byte streams remain dashboard-only because those browser flows cannot consistently carry a Bearer header. API consumers poll operation resources or receive webhooks instead.

When you are signed in, use the API Reference switch above to browse every generated endpoint and schema. The request runner uses your dashboard session, while its code samples show the scoped Bearer token your integrations should send.