API Reference

This reference covers Stib's project-scoped automation API under /api/external/projects/.... The web and desktop clients also call many /api/... routes, but those are internal client/server contracts and are not documented as a stable third-party API.

Base URL

Use the server origin, without the desktop/web-client origin unless they are the same:

https://stib.example.com

For a local native server, the preferred origin is http://localhost:50505; use the actual bound port if it changed.

API keys

Create a dedicated key from the appropriate API Keys settings scope: server, organization, or project. Choose its expiration and only the permissions required by the integration. Use a separate owner/key for each trust boundary rather than reusing an administrator's key.

The full key starts with stib_ak_ and is displayed only once. Send it as a Bearer token:

Authorization: Bearer stib_ak_…

Do not put the key in a URL or commit it to a repository. API keys are rate-limited to 100 requests per minute per key, can expire, and are checked against route permissions and the access of their owning account.

Permissions

The external endpoints use these permissions:

Permission	Allows
cards.read	List/read cards, boards, and project statistics
cards.create or pipelines.trigger	Create a card and initialize its pipeline configuration; creation does not activate the agent
cards.move	Move a card to another column
agents.cancel	Cancel the active agent on a card
agents.archive	Archive a card

Other permissions exist for project-scoped client routes, but granting one does not make an undocumented internal route a stable integration contract.

Response format

Successful responses are wrapped in data:

{
  "data": {
    "id": 42,
    "status": "idle"
  }
}

Errors use a stable envelope with a machine-readable code:

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key does not have the required permission"
  }
}

Common status codes are 400, 401, 403, 404, 409, 429, 500, and 503. Back off and honor Retry-After when it is returned for rate limiting or database contention.

Quick example

export STIB_ORIGIN='https://stib.example.com'
export STIB_API_KEY='stib_ak_…'
export STIB_PROJECT_ID='12'

curl --fail-with-body \
  -H "Authorization: Bearer $STIB_API_KEY" \
  "$STIB_ORIGIN/api/external/projects/$STIB_PROJECT_ID/cards?limit=20"

Use a secret manager for real automation instead of an interactive shell variable.

Next: Endpoints.