Automation Endpoints

All paths below are relative to the Stib Server origin and require an allowed stib_ak_… Bearer token.

Endpoint summary

Method	Path	Permission
GET	/api/external/projects/{projectId}/boards	cards.read
GET	/api/external/projects/{projectId}/cards	cards.read
POST	/api/external/projects/{projectId}/cards	cards.create or pipelines.trigger
GET	/api/external/projects/{projectId}/cards/{cardId}	cards.read
GET	/api/external/projects/{projectId}/stats	cards.read
PATCH	/api/external/projects/{projectId}/cards/{cardId}/move	cards.move
POST	/api/external/projects/{projectId}/cards/{cardId}/archive	agents.archive
POST	/api/external/projects/{projectId}/cards/{cardId}/agent/cancel	agents.cancel

List boards and columns

GET /api/external/projects/{projectId}/boards

Returns each board with its id, name, and ordered columns. A column includes id, name, columnType, and position. Use this endpoint to resolve a destination columnId instead of hard-coding IDs from another server.

Each board also carries isPrivate. Private boards are listed only to their owner (a key sees what its owner sees) and to the agents of their own cards; another member's private board never appears, and its cards answer 404 like missing ones. Moving a card from another board into a private board is refused with PRIVATE_BOARD_MOVE_IN_FORBIDDEN.

List cards

GET /api/external/projects/{projectId}/cards

Optional query parameters:

Parameter	Meaning
columnId	Filter by column ID
status	Filter by exact runtime status
label	Filter cards whose serialized labels contain the value
limit	Page size; default 50, maximum 100
cursor	Return cards with an ID greater than this cursor

The response data contains items and nextCursor. nextCursor is null when no later page exists. Deleted, archived, and non-Kanban cards are excluded.

Create a card

POST /api/external/projects/{projectId}/cards
Content-Type: application/json

{
  "title": "Add search filters",
  "prompt": "Add status and agent filters to global search and cover them with tests.",
  "columnId": 17,
  "useWorktree": true
}

title is required. prompt, columnId, and useWorktree are optional. Without columnId, Stib uses the first column of the default board. The chosen column must belong to that default board. useWorktree defaults to true. A project whose worktree policy is Required or Forbidden decides instead, whatever the request says; the returned card carries the value applied.

Returns 201 Created and the created card in data. Creation initializes its default pipeline configuration but leaves the card inactive; activate it through an explicit supported workflow when execution is desired.

Get a card

GET /api/external/projects/{projectId}/cards/{cardId}

Returns card identity, project/column/group, title and prompt, runtime status, position, unread state, Git branch, worktree preference, last agent action, timestamps, locks, and session summaries. The external response deliberately omits the server filesystem worktree path.

Project statistics

GET /api/external/projects/{projectId}/stats

Returns active Kanban-card totals by runtime status and column plus the available token snapshot total. Archived, deleted, and non-Kanban cards are excluded.

Move a card

PATCH /api/external/projects/{projectId}/cards/{cardId}/move
Content-Type: application/json

{
  "targetColumnId": 18,
  "position": 0
}

Moving a card triggers the configured move webhooks and revokes callback tokens when leaving active execution. This endpoint does not start the target column's agent behavior. Resolve the target column from the same project before calling.

Archive a card

POST /api/external/projects/{projectId}/cards/{cardId}/archive

Archives the card and revokes its assistant callback tokens. The response data is { "ok": true }.

Cancel an agent

POST /api/external/projects/{projectId}/cards/{cardId}/agent/cancel

Requests cancellation of the card's active agent. The response data is { "ok": true } when the manager accepted the operation. Inspect card state and Git changes afterward; cancellation does not roll back files.

Compatibility note

Legacy /api/cards endpoints still exist for backward compatibility, but new integrations should use the project-scoped /api/external/projects/... routes so scope and permissions are explicit.

Card monitors

These daemon-side endpoints are reserved for short-lived agent tokens scoped to their own card. Long-lived external API keys cannot access them.

Create a monitor

POST /api/projects/{projectId}/cards/{cardId}/monitors
Content-Type: application/json

{
  "command": "./check-ci",
  "intervalSecs": 45,
  "description": "CI status",
  "cwd": "/absolute/card/worktree",
  "allowUnsandboxed": true
}

Creates a persistent monitor and returns it with 201 Created. allowUnsandboxed must be true: commands run outside the agent sandbox with the Stib server's operating-system permissions. The interval must be between 10 and 86,400 seconds, and cwd must resolve inside the card repository, managed worktree, or attached worktree. A card can have at most eight monitors.

List monitors

GET /api/projects/{projectId}/cards/{cardId}/monitors

Returns the card's monitors in creation order with their latest status, timestamps, exit code, and diagnostic error.

Delete a monitor

DELETE /api/projects/{projectId}/cards/{cardId}/monitors/{monitorId}

Deletes the scoped monitor and returns 204 No Content. A running command and its descendants are terminated by the daemon reconciliation loop.

Stable errors include MONITOR_UNSANDBOXED_ACK_REQUIRED, MONITOR_COMMAND_INVALID, MONITOR_INTERVAL_INVALID, MONITOR_DESCRIPTION_INVALID, MONITOR_CWD_INVALID, MONITOR_CWD_OUTSIDE_CARD, MONITOR_LIMIT_REACHED, MONITOR_CARD_INACTIVE, MONITOR_TERMINAL_CARD_UNSUPPORTED, and MONITOR_NOT_FOUND.