Skip to content

API Reference

Everything you can do in the Bonsai app is also available over a REST API, so you can script it or connect other tools.

https://<your-bonsai-host>/api

For example https://eu101-bonsai.agenticfte.ai/api/organizations. Most endpoints are scoped to an organisation: /organizations/:orgId/…. Your organisation id is shown on the Organizations page.

Send a token in the Authorization header:

Authorization: Bearer <token>
Token Prefix Where to create it Scope
Personal access token pat_ Profile → Personal access tokens Acts as you, in every organisation you belong to, with your roles. Valid until you revoke it.
API key ak_ Settings → API keys (organisation owners) One organisation only; acts with the MEMBER role. Suited to CI/CD and integrations.

Both are shown once at creation — copy them immediately. The web app itself uses secure session cookies; you don’t need a token in the browser.

Signing in with a password always requires a second factor (MFA), so scripts should use a personal access token or an API key rather than logging in.

Organisation endpoints check your role in that organisation — VIEWER < MEMBER < OWNER. The Min. role column below shows the lowest role that may call each endpoint.

Status Meaning
400 The request is invalid — the response message says what to fix.
401 Missing, expired or revoked token.
402 Your plan doesn’t allow it (see below).
403 Your role, or your account’s status, doesn’t allow it.
404 Not found — or not in this organisation.
409 Conflict with the current state (e.g. deleting a run that is still running).

When an action would go beyond your plan, the API answers 402 with a machine-readable body, for example:

{
"statusCode": 402,
"code": "TIER_LIMIT_REACHED",
"plan": "starter",
"limit": "goals per organization",
"used": 1,
"max": 1,
"message": "Your Starter plan allows 1 goals per organization (1 used). Contact your administrator to upgrade or add a license."
}

Choosing a model above your plan’s level answers 402 with "code": "TIER_MODEL_NOT_ALLOWED". See Your organisation › Plan and limits.

232 endpoints. Min. role is the lowest organisation role that may call the endpoint (org-scoped routes only).

Method Path Min. role Description
POST /auth/forgot-password — Request a password reset email
GET /auth/invitation-preview — Preview invitation details by token (public)
POST /auth/login — Login
POST /auth/logout — Logout — clears session cookies and invalidates refresh token
GET /auth/me — Get current user
PATCH /auth/me/password — Change own password (requires current password)
POST /auth/mfa/enable — Confirm a TOTP code to enable MFA (returns recovery codes)
POST /auth/mfa/re-enroll — Replace authenticator: verify current code, return new QR
POST /auth/mfa/setup — Begin MFA enrollment (returns secret + QR)
POST /auth/mfa/setup-complete — Confirm enrollment and issue session cookies
POST /auth/mfa/setup-initiate — Begin forced MFA enrollment during first login (no session yet)
GET /auth/mfa/status — Whether MFA is enabled for the current user
POST /auth/mfa/verify — Complete an MFA login challenge
POST /auth/refresh — Refresh session using the refresh-token cookie
POST /auth/register-with-invitation — Create account and accept invitation in one step
POST /auth/reset-password — Set a new password using a reset token
GET /auth/sso/callback — OIDC SSO callback — signs in an existing user and returns to the app
GET /auth/sso/login — Begin OIDC SSO login (redirects to the IdP)
GET /auth/sso/status — Whether OIDC SSO is configured (for login UI)
GET /auth/sso/token — Exchange a one-time SSO code for session cookies
Method Path Min. role Description
GET /organizations/:orgId/agents VIEWER List agents
POST /organizations/:orgId/agents MEMBER Create agent
DELETE /organizations/:orgId/agents/:agentId MEMBER Soft-delete an agent
GET /organizations/:orgId/agents/:agentId VIEWER Get agent
PATCH /organizations/:orgId/agents/:agentId OWNER Update agent (change is revisioned for rollback)
POST /organizations/:orgId/agents/:agentId/clone OWNER Clone agent (copies config, resets runtime state)
POST /organizations/:orgId/agents/:agentId/command MEMBER Dispatch a slash command to the agent
GET /organizations/:orgId/agents/:agentId/context VIEWER List project context documents for an agent
POST /organizations/:orgId/agents/:agentId/context VIEWER Create a project context document
DELETE /organizations/:orgId/agents/:agentId/context/:docId VIEWER Delete a project context document
GET /organizations/:orgId/agents/:agentId/context/:docId VIEWER Get a context document
PATCH /organizations/:orgId/agents/:agentId/context/:docId VIEWER Update a project context document
GET /organizations/:orgId/agents/:agentId/cost-forecast VIEWER F7: Projected monthly cost based on last-30-day run rate
GET /organizations/:orgId/agents/:agentId/desired-skills VIEWER Get adapter skill-sync snapshot for an agent
POST /organizations/:orgId/agents/:agentId/desired-skills/sync MEMBER Sync desired company skills into adapterConfig.paperclipSkillSync
POST /organizations/:orgId/agents/:agentId/docgen VIEWER Generate markdown documentation from agent instructions and skills
GET /organizations/:orgId/agents/:agentId/evidence VIEWER Gather evidence bundle for an agent (readiness, runs, tests, docs, journal)
GET /organizations/:orgId/agents/:agentId/harness VIEWER Live status of one agent in the harness
POST /organizations/:orgId/agents/:agentId/harness/force-run MEMBER Force an immediate agent run
POST /organizations/:orgId/agents/:agentId/harness/reset-session MEMBER Reset agent session state
GET /organizations/:orgId/agents/:agentId/hooks VIEWER List hooks for an agent
POST /organizations/:orgId/agents/:agentId/hooks MEMBER Create a hook
DELETE /organizations/:orgId/agents/:agentId/hooks/:hookId MEMBER Delete a hook
PATCH /organizations/:orgId/agents/:agentId/hooks/:hookId MEMBER Update a hook
POST /organizations/:orgId/agents/:agentId/hooks/:hookId/run MEMBER Manually trigger a hook
GET /organizations/:orgId/agents/:agentId/hooks/:hookId/runs VIEWER List execution history for a hook
POST /organizations/:orgId/agents/:agentId/invoke MEMBER Manually invoke agent heartbeat
GET /organizations/:orgId/agents/:agentId/journal VIEWER List journal entries for an agent
POST /organizations/:orgId/agents/:agentId/journal VIEWER Add a journal entry
DELETE /organizations/:orgId/agents/:agentId/journal/:entryId VIEWER Delete a journal entry
DELETE /organizations/:orgId/agents/:agentId/memory MEMBER Clear all memory for an agent (optionally by namespace)
GET /organizations/:orgId/agents/:agentId/memory VIEWER List agent memory entries
DELETE /organizations/:orgId/agents/:agentId/memory/*key MEMBER Delete a memory entry
GET /organizations/:orgId/agents/:agentId/memory/*key VIEWER Get a memory entry
PUT /organizations/:orgId/agents/:agentId/memory/*key MEMBER Upsert a memory entry
GET /organizations/:orgId/agents/:agentId/memory/namespaces VIEWER List distinct memory namespaces for an agent
POST /organizations/:orgId/agents/:agentId/pause MEMBER Pause agent
DELETE /organizations/:orgId/agents/:agentId/permanent OWNER Permanently delete a soft-deleted agent
GET /organizations/:orgId/agents/:agentId/readiness VIEWER Get AI readiness score for an agent
POST /organizations/:orgId/agents/:agentId/reset-budget OWNER Reset an agent monthly spend counter to zero
POST /organizations/:orgId/agents/:agentId/restore MEMBER Restore a soft-deleted agent
POST /organizations/:orgId/agents/:agentId/resume MEMBER Resume agent
GET /organizations/:orgId/agents/:agentId/revisions VIEWER List config revisions for an agent
POST /organizations/:orgId/agents/:agentId/revisions/:revisionId/rollback OWNER Roll back agent config to a previous revision
GET /organizations/:orgId/agents/:agentId/runs VIEWER List agent runs (cursor-paginated)
GET /organizations/:orgId/agents/:agentId/runtime-state VIEWER Get aggregated runtime state for an agent
GET /organizations/:orgId/agents/:agentId/skills VIEWER List skills for an agent
POST /organizations/:orgId/agents/:agentId/skills MEMBER Create a skill for an agent
DELETE /organizations/:orgId/agents/:agentId/skills/:skillId MEMBER Delete a skill
PATCH /organizations/:orgId/agents/:agentId/skills/:skillId MEMBER Update a skill
POST /organizations/:orgId/agents/:agentId/skills/:skillId/push-down MEMBER Push a skill down to subagents
GET /organizations/:orgId/agents/:agentId/skills/:skillId/versions VIEWER List versions of a skill
GET /organizations/:orgId/agents/:agentId/skills/:skillId/versions/:version VIEWER Get a specific skill version
POST /organizations/:orgId/agents/:agentId/skills/:skillId/versions/:version/rollback MEMBER Roll back a skill to a previous version
POST /organizations/:orgId/agents/:agentId/skills/copy MEMBER Copy a skill to other agents
GET /organizations/:orgId/agents/:agentId/skills/diff-with-parent VIEWER Diff this agent skills vs parent agent skills
GET /organizations/:orgId/agents/:agentId/subagents VIEWER Get the recursive subagent tree under an agent
POST /organizations/:orgId/agents/:agentId/terminate MEMBER Terminate agent
GET /organizations/:orgId/agents/:agentId/test-cases VIEWER
POST /organizations/:orgId/agents/:agentId/test-cases VIEWER
DELETE /organizations/:orgId/agents/:agentId/test-cases/:tcId VIEWER
PATCH /organizations/:orgId/agents/:agentId/test-cases/:tcId VIEWER
POST /organizations/:orgId/agents/:agentId/test-cases/:tcId/run VIEWER
POST /organizations/:orgId/agents/:agentId/test-environment MEMBER Test adapter environment for this agent
GET /organizations/:orgId/agents/:agentId/tools VIEWER List tools assigned to an agent
DELETE /organizations/:orgId/agents/:agentId/tools/:pluginId MEMBER Remove a tool (plugin) from an agent
POST /organizations/:orgId/agents/:agentId/tools/:pluginId MEMBER Assign a tool (plugin) to an agent
POST /organizations/:orgId/agents/:agentId/validate VIEWER Run all test cases (closed-loop validation)
GET /organizations/:orgId/agents/adapter-types VIEWER List all supported adapter types with their config schemas and detection status
GET /organizations/:orgId/agents/adapters/:adapterType/account-info VIEWER Probe adapter CLI for connected account and usage information
POST /organizations/:orgId/agents/adapters/:adapterType/set-model OWNER Set the model on all agents of a given adapter type
GET /organizations/:orgId/agents/adapters/available VIEWER Detect which adapter CLIs are installed and available
GET /organizations/:orgId/agents/adapters/stats VIEWER Per-adapter usage stats for 24h / 7d / 30d windows
GET /organizations/:orgId/agents/costs OWNER Get organization cost breakdown by adapter and project
GET /organizations/:orgId/agents/deleted MEMBER List soft-deleted agents
GET /organizations/:orgId/agents/harness VIEWER Live status of all agents in the harness
POST /organizations/:orgId/agents/harness/queue/drain OWNER Drain all waiting jobs from the queue
POST /organizations/:orgId/agents/harness/queue/pause OWNER Pause the agent run queue
POST /organizations/:orgId/agents/harness/queue/resume OWNER Resume the agent run queue
GET /organizations/:orgId/agents/live-runs VIEWER List live organization runs (PENDING/RUNNING)
GET /organizations/:orgId/agents/org-chart VIEWER Agent hierarchy for org chart
DELETE /organizations/:orgId/agents/runs/:runId MEMBER Delete a run and its chat chain + log files
GET /organizations/:orgId/agents/runs/:runId VIEWER Get run detail
POST /organizations/:orgId/agents/runs/:runId/cancel MEMBER Cancel a queued/running run
GET /organizations/:orgId/agents/runs/:runId/children VIEWER List child (sub-agent) runs spawned by a parent run
GET /organizations/:orgId/agents/runs/:runId/events VIEWER Get run events since sequence number
GET /organizations/:orgId/agents/runs/:runId/log VIEWER Read paged NDJSON log for a run
POST /organizations/:orgId/agents/runs/:runId/resume MEMBER Resume run by creating a follow-up retry
POST /organizations/:orgId/agents/runs/:runId/retry MEMBER Retry a previous run
POST /organizations/:orgId/agents/runs/:runId/stop MEMBER Stop a queued run
GET /organizations/:orgId/agents/runs/recent VIEWER List recent org runs with queue state
GET /organizations/:orgId/agents/runs/timeseries VIEWER Daily run counts over the last N days (max 90) for trend charts
Method Path Min. role Description
GET /organizations/:orgId/tasks VIEWER List tasks
POST /organizations/:orgId/tasks MEMBER Create task
DELETE /organizations/:orgId/tasks/:taskId MEMBER Soft-delete task
GET /organizations/:orgId/tasks/:taskId VIEWER Get task
PATCH /organizations/:orgId/tasks/:taskId MEMBER Update task
GET /organizations/:orgId/tasks/:taskId/active-run VIEWER Get active run for task
POST /organizations/:orgId/tasks/:taskId/checkout MEMBER Checkout task (atomic task claim)
POST /organizations/:orgId/tasks/:taskId/clone MEMBER Clone task (copies fields, resets to TODO)
GET /organizations/:orgId/tasks/:taskId/comments VIEWER List comments for a task (cursor-paginated)
POST /organizations/:orgId/tasks/:taskId/comments MEMBER Add comment
DELETE /organizations/:orgId/tasks/:taskId/labels/:labelId MEMBER Remove label from task
POST /organizations/:orgId/tasks/:taskId/labels/:labelId MEMBER Add label to task
DELETE /organizations/:orgId/tasks/:taskId/permanent MEMBER Permanently delete a soft-deleted task
POST /organizations/:orgId/tasks/:taskId/release MEMBER Release task checkout lock
PATCH /organizations/:orgId/tasks/:taskId/reorder MEMBER Update task position for drag-and-drop reordering
POST /organizations/:orgId/tasks/:taskId/restore MEMBER Restore a soft-deleted task
GET /organizations/:orgId/tasks/:taskId/runs VIEWER List runs for task
GET /organizations/:orgId/tasks/deleted MEMBER List soft-deleted tasks
Method Path Min. role Description
GET /organizations/:orgId/projects VIEWER List projects
POST /organizations/:orgId/projects MEMBER Create project
DELETE /organizations/:orgId/projects/:projectId MEMBER Soft-delete project
GET /organizations/:orgId/projects/:projectId VIEWER Get project
PATCH /organizations/:orgId/projects/:projectId MEMBER Update project
POST /organizations/:orgId/projects/:projectId/configure-pipeline MEMBER Create inter-agent hooks for the Salesforce migration pipeline
GET /organizations/:orgId/projects/:projectId/files VIEWER List files in the cloned repository
POST /organizations/:orgId/projects/:projectId/initialize-repo MEMBER Connect a git repository and start the ingestion pipeline
DELETE /organizations/:orgId/projects/:projectId/permanent MEMBER Permanently delete a soft-deleted project
PATCH /organizations/:orgId/projects/:projectId/pipeline-phase MEMBER Update the current pipeline phase
POST /organizations/:orgId/projects/:projectId/restore MEMBER Restore a soft-deleted project
POST /organizations/:orgId/projects/:projectId/working-folder MEMBER Provision the managed working folder for a project
DELETE /organizations/:orgId/projects/:projectId/workspace-files MEMBER Delete a file or folder from the project working folder
GET /organizations/:orgId/projects/:projectId/workspace-files VIEWER List documents in the project working folder
GET /organizations/:orgId/projects/:projectId/workspace-files/content VIEWER Read a document from the project working folder
PUT /organizations/:orgId/projects/:projectId/workspace-files/content MEMBER Write a document in the project working folder
POST /organizations/:orgId/projects/:projectId/workspace-files/copy MEMBER Copy a file/folder to a destination folder in the project working folder
POST /organizations/:orgId/projects/:projectId/workspace-files/folder MEMBER Create a folder in the project working folder
GET /organizations/:orgId/projects/:projectId/workspace-files/raw VIEWER Stream a file from the project working folder as raw bytes
POST /organizations/:orgId/projects/:projectId/workspace-files/rename MEMBER Rename or move a file/folder in the project working folder
GET /organizations/:orgId/projects/:projectId/workspace-files/search VIEWER Search files and folders in the project working folder by name
POST /organizations/:orgId/projects/:projectId/workspace-files/upload MEMBER Upload files into a folder of the project working folder
GET /organizations/:orgId/projects/deleted MEMBER List soft-deleted projects
Method Path Min. role Description
GET /organizations/:orgId/approvals VIEWER List approvals
POST /organizations/:orgId/approvals MEMBER Create approval request
GET /organizations/:orgId/approvals/:approvalId VIEWER Get approval
GET /organizations/:orgId/approvals/:approvalId/comments VIEWER List approval discussion comments
POST /organizations/:orgId/approvals/:approvalId/comments MEMBER Add a comment to an approval
PATCH /organizations/:orgId/approvals/:approvalId/resolve MEMBER Approve or reject (org members; people only)
Method Path Min. role Description
GET /organizations/:orgId/goals VIEWER List goals
POST /organizations/:orgId/goals MEMBER Create goal
DELETE /organizations/:orgId/goals/:goalId MEMBER Delete goal
GET /organizations/:orgId/goals/:goalId VIEWER Get goal
PATCH /organizations/:orgId/goals/:goalId MEMBER Update goal
Method Path Min. role Description
GET /organizations/:orgId/routines VIEWER List routines
POST /organizations/:orgId/routines MEMBER Create routine
DELETE /organizations/:orgId/routines/:routineId MEMBER Delete routine
GET /organizations/:orgId/routines/:routineId VIEWER Get routine
PATCH /organizations/:orgId/routines/:routineId MEMBER Update routine
Method Path Min. role Description
GET /organizations/:orgId/sprints VIEWER
POST /organizations/:orgId/sprints VIEWER
DELETE /organizations/:orgId/sprints/:id VIEWER
PATCH /organizations/:orgId/sprints/:id VIEWER
POST /organizations/:orgId/sprints/:id/complete VIEWER
POST /organizations/:orgId/sprints/:id/start VIEWER
Method Path Min. role Description
GET /organizations/:orgId/teams VIEWER List teams
POST /organizations/:orgId/teams OWNER Create team
DELETE /organizations/:orgId/teams/:teamId OWNER Delete team
GET /organizations/:orgId/teams/:teamId VIEWER Get team
PATCH /organizations/:orgId/teams/:teamId OWNER Update team
POST /organizations/:orgId/teams/:teamId/members OWNER Add agent to team
DELETE /organizations/:orgId/teams/:teamId/members/:agentId OWNER Remove agent from team
Method Path Min. role Description
GET /organizations/:orgId/inbox VIEWER List inbox items
PATCH /organizations/:orgId/inbox/:itemId/dismiss VIEWER Dismiss a single inbox item
DELETE /organizations/:orgId/inbox/dismiss-all VIEWER Dismiss all inbox items
GET /organizations/:orgId/inbox/unread-count VIEWER Count unread inbox items
Method Path Min. role Description
GET /organizations/:orgId/personal-access-tokens VIEWER List personal access tokens
POST /organizations/:orgId/personal-access-tokens VIEWER Create personal access token (raw token returned once)
DELETE /organizations/:orgId/personal-access-tokens/:tokenId VIEWER Revoke personal access token
PATCH /organizations/:orgId/personal-access-tokens/:tokenId VIEWER Update virtual-key options on a token
Method Path Min. role Description
GET /organizations/:orgId/task-labels VIEWER List task labels
POST /organizations/:orgId/task-labels OWNER Create task label
DELETE /organizations/:orgId/task-labels/:labelId OWNER Delete task label
Method Path Min. role Description
GET /organizations/:orgId/issues VIEWER
POST /organizations/:orgId/issues VIEWER
DELETE /organizations/:orgId/issues/:idOrIdentifier VIEWER
GET /organizations/:orgId/issues/:idOrIdentifier VIEWER
PUT /organizations/:orgId/issues/:idOrIdentifier VIEWER
POST /organizations/:orgId/issues/:sourceId/relations VIEWER
DELETE /organizations/:orgId/issues/relations/:relationId VIEWER
Method Path Min. role Description
GET /organizations/:orgId/skills VIEWER List all company skills
POST /organizations/:orgId/skills OWNER Create a local company skill
DELETE /organizations/:orgId/skills/:skillId OWNER Delete a company skill if unused by agents
GET /organizations/:orgId/skills/:skillId VIEWER Get company skill detail
GET /organizations/:orgId/skills/:skillId/files VIEWER Read a skill file (default SKILL.md)
PATCH /organizations/:orgId/skills/:skillId/files OWNER Update a skill file (local skills only)
POST /organizations/:orgId/skills/:skillId/install-to-agent MEMBER Copy a company skill into an agent as an AgentSkill
POST /organizations/:orgId/skills/:skillId/install-update OWNER Re-import latest tracked source for a skill
GET /organizations/:orgId/skills/:skillId/update-status VIEWER Check update status for a source-backed skill
GET /organizations/:orgId/skills/:skillId/versions VIEWER List file version snapshots for a company skill
GET /organizations/:orgId/skills/:skillId/versions/:version VIEWER Get a specific version snapshot
POST /organizations/:orgId/skills/:skillId/versions/:version/restore MEMBER Restore a skill file to a previous version
POST /organizations/:orgId/skills/import OWNER Import a skill from local path, URL, GitHub, or skills_sh
POST /organizations/:orgId/skills/scan-projects OWNER Scan project roots for SKILL.md files and import them
Method Path Min. role Description
GET /templates/agents — List available agent templates
GET /templates/agents/:templateId — Get a single agent template
GET /templates/orgs — List available org templates
GET /templates/orgs/:templateId — Get a single org template
GET /templates/resolve-skill — Resolve a skills.sh / GitHub locator to SKILL.md content
GET /templates/skills — List the built-in agent skill library
GET /templates/skills/:skillId — Get a single skill library entry with full SKILL.md content
Method Path Min. role Description
POST /organizations/:orgId/apply-template OWNER Apply an org template — creates agents and goals in the org
Method Path Min. role Description
POST /organizations/:orgId/apply-agent-template MEMBER Apply an agent template — creates one agent in the org
Method Path Min. role Description
GET /adapter-types — List adapter types enabled by the server admin
Method Path Min. role Description
POST /v1/chat/completions — Create a chat completion
POST /v1/completions — Create a text completion (legacy)
POST /v1/messages — Create a message (Anthropic-compatible)
GET /v1/models — List available models (agents)
POST /v1/responses — Create a Codex response
Method Path Min. role Description
POST /webhooks/github/:orgId/:pluginId —
POST /webhooks/gitlab/:orgId/:pluginId —
Method Path Min. role Description
GET /health —