API Reference

Stib exposes a REST API that lets you build custom integrations, automate workflows, and interact with your boards, cards, and agents programmatically.

Base URL

By default, the API is available at:

http://localhost:37100/api/

The host and port depend on your Stib server configuration. All endpoint paths in this documentation are relative to /api/.

Response Format

All API responses follow a consistent envelope format.

Success response:

{
  "data": {
    "id": "abc123",
    "name": "My Project"
  }
}

Error response:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found"
  }
}

TIP

All JSON fields use camelCase naming (e.g., projectId, columnType, isAutoMode).

Authentication

Authentication is optional — it can be enabled or disabled in Stib settings. When enabled, include a Bearer token in the Authorization header:

GET /api/projects HTTP/1.1
Authorization: Bearer <token>

You can check whether authentication is active:

GET /api/settings/auth-status

When authentication is disabled, all endpoints are accessible without a token.

Server Roles

Role	Description
user	Standard access to own projects and organizations
admin	Can manage users via admin panel
super_admin	Full server admin — required for auth management, OIDC config, backups, user management

INFO

Server roles (user, admin, super_admin) are separate from organization/project member roles (admin, member). A user can be a server user but an admin within a specific organization.

Organization Context

For multi-organization setups, pass the organization ID in a request header:

GET /api/projects HTTP/1.1
X-Organization-Id: org_abc123

• Without auth: the X-Organization-Id is verified against the database.
• With auth: membership is checked (super admins bypass this check).

HTTP Status Codes

Code	Usage
200	Successful GET, PATCH, or PUT
201	Successful POST (resource created)
204	Successful DELETE or action with no response body
400	Validation error (missing or invalid fields)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Resource not found
409	Conflict (state conflict, e.g., duplicate)
500	Internal server error

Pagination

Some list endpoints support pagination via query parameters:

Parameter	Type	Description
limit	number	Maximum number of items to return
since	string	Return items after this timestamp (ISO 8601)
before	string	Return items before this timestamp (ISO 8601)

Example:

GET /api/projects/{projectId}/cards/{cardId}/agent/messages?limit=50&since=2025-01-01T00:00:00Z

WebSocket

Stib uses a WebSocket connection for real-time updates (card moves, agent progress, notifications).

ws://localhost:37100/api/ws?token=<token>

When authentication is enabled, pass the Bearer token as a token query parameter. Connect to this endpoint to receive server-sent events. All card and agent mutations emit WebSocket events, so connected clients stay in sync automatically.

Quick Example

Create a card via the external flat API:

curl

curl -X POST http://localhost:37100/api/cards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "projectId": "project_abc123",
    "title": "Fix login bug",
    "prompt": "The login form does not validate email format"
  }'

Response — 201

{
  "data": {
    "id": "card_xyz789",
    "title": "Fix login bug",
    "prompt": "The login form does not validate email format",
    "projectId": "project_abc123",
    "columnId": "col_001",
    "position": 0
  }
}

Check the card status:

curl http://localhost:37100/api/cards/card_xyz789/status \
  -H "Authorization: Bearer <token>"

{
  "data": {
    "id": "card_xyz789",
    "title": "Fix login bug",
    "columnName": "Backlog",
    "hasActiveAgent": false
  }
}

For the full list of available endpoints, see the Endpoints page.