Management API
Beyond chatting, a scoped key can create and configure resources: agents, knowledge sets, models, tasks, swarms, webhooks and schedules. This is what you use to provision BasePeak.AI from code rather than clicking through the admin UI.
The OpenAPI spec is the reference
Every instance serves its own machine-readable spec, and it is generated from the same table that drives route registration — so it cannot drift from what the server actually exposes:
curl -sS https://your-instance.platform.basepeak.ai/api/openapi.json
curl -sS https://your-instance.platform.basepeak.ai/api/openapi.yaml
Both are reachable without authentication. Prefer them over any table in these docs when the two disagree on request or response shape: the spec is generated, the prose is written by hand.
The spec covers everything an API key can reach, not just the management
routes on this page. Operations are grouped by surface (tags):
| Tag | What it covers | Page |
|---|---|---|
Chat | Invoke API: send a turn to an agent | Invoke API |
OpenAI | OpenAI-compatible routes under /v1 | OpenAI-compatible API |
Threads | List and read conversations, replay events, cancel a run | Threads |
Files | Workspace files on an agent and on a conversation | Files |
Projects | Project-addressable chat, workspace, knowledge, environment, tasks | Projects |
Management | The catalogue: agents, knowledge sets, models, tools, tasks, swarms, triggers | this page |
Key creation (/api/account/apikeys) is deliberately absent: it is bound
to a signed-in session and rejects API keys, so including it would document a
guaranteed 403. Keys are created in the UI — see
API keys.
Each operation carries an x-required-scope extension naming the scope it
needs — admin means no key can reach it.
Two route spellings are intentionally not in the spec:
/api/invoke/{id}/thread/{thread} (singular) and the /file/ variants of the
file routes. They still work, but they are equivalent legacy forms of the
documented plural spelling; listing both would double every generated client
without adding a single capability.
Generating a typed client is the intended workflow:
# Python
openapi-python-client generate --url https://your-instance.platform.basepeak.ai/api/openapi.json
# TypeScript
npx openapi-typescript https://your-instance.platform.basepeak.ai/api/openapi.json -o bpai.d.ts
# Go
oapi-codegen -package bpai <(curl -sS https://your-instance.platform.basepeak.ai/api/openapi.yaml) > bpai.gen.go
Management scopes
Nine management permissions can be minted into a key. Each is a
resource:action pair used as the first two segments of a scope:
| Scope | Grants |
|---|---|
agent:create:* | Create, list, read, copy, export and import agents |
agent:update:* | Modify agents: manifest, default flag, knowledge-set attach/detach, authorizations |
agent:delete:* | Delete agents |
knowledgeset:manage:* | Full knowledge-set lifecycle, files, imports and exports |
tool-reference:manage:* | Register, update, delete and refresh tools and MCP servers |
model-provider:manage:* | Manage models, and configure or validate model providers |
trigger:manage:* | Webhooks, email receivers and cronjobs |
task:manage:* | Tasks and task runs |
team:manage:* | Agent swarms |
Management scopes must use * in the id segment — with one exception,
below. Minting a key still requires that you currently hold the
underlying permission, so a key can never grant more than its creator has.
Grounding a key to a single agent
agent:update is the only management permission that accepts a concrete id
instead of *:
| Scope | Reach |
|---|---|
agent:update:* | May update any agent its owner can |
agent:update:a17jlm7 | May update only agent a17jlm7 |
Every agent:update route carries the agent as its first path parameter,
so the grounded id is enforced per request — a grounded key gets 403 on
any other agent.
Either way the key acts with the rights its owner holds on the agent at
the time of the request: the global agent:update permission (on
unrestricted agents) or an editor or owner role. When the owner loses those
rights, so does the key.
This exists for the self-improving-agent case: an agent that rewrites its own instructions should hold a key that can modify itself and nothing else.
{
"name": "self-improve",
"scopes": ["agent:chat:a17jlm7", "agent:update:a17jlm7"]
}
A key may carry several scopes; there is no one-scope limit.
The route catalogue
The scoped-key management surface, grouped by resource. {…} are path
parameters.
Agents
| Method | Path | Scope |
|---|---|---|
POST | /api/agents | agent:create |
GET | /api/agents | agent:create |
GET | /api/agents/{id} | agent:create |
PUT | /api/agents/{id} | agent:update |
DELETE | /api/agents/{id} | agent:delete |
POST | /api/agents/{id}/copy | agent:create |
GET | /api/agents/{id}/export | agent:create |
POST | /api/agents/import | agent:create |
PUT | /api/agents/{id}/setdefault | agent:update |
POST | /api/agents/{id}/knowledge-sets/{knowledge_set_id}/attach | agent:update |
DELETE | /api/agents/{id}/knowledge-sets/{knowledge_set_id}/detach | agent:update |
GET | /api/agents/{id}/authorizations | agent:create |
POST | /api/agents/{id}/authorizations/add | agent:update |
POST | /api/agents/{id}/authorizations/remove | agent:update |
Export/import use a YAML-or-JSON agent envelope, so an agent can be moved between instances as a file.
Knowledge sets
| Method | Path | Scope |
|---|---|---|
POST GET | /api/knowledge-sets | knowledgeset:manage |
GET PUT DELETE | /api/knowledge-sets/{id} | knowledgeset:manage |
GET | /api/knowledge-sets/{id}/knowledge-files | knowledgeset:manage |
POST DELETE | /api/knowledge-sets/{id}/knowledge-files/{file...} | knowledgeset:manage |
POST GET | /api/knowledge-sets/{id}/exports | knowledgeset:manage |
GET DELETE | /api/knowledge-sets/{id}/exports/{export_id} | knowledgeset:manage |
POST GET | /api/knowledge-set-imports | knowledgeset:manage |
GET DELETE | /api/knowledge-set-imports/{import_id} | knowledgeset:manage |
Models and providers
| Method | Path | Scope |
|---|---|---|
POST | /api/models | model-provider:manage |
PUT DELETE | /api/models/{id} | model-provider:manage |
GET | /api/models | one of agent:create, agent:update, model-provider:manage (or a signed-in session) |
GET | /api/models/{id} | admin-only |
GET | /api/model-providers | model-provider:manage |
GET | /api/model-providers/{model_provider_id} | model-provider:manage |
POST | /api/model-providers/{id}/configure | model-provider:manage |
POST | /api/model-providers/{id}/validate | model-provider:manage |
configure and validate take a flat environment-variable map as their
body.
Tools and MCP servers
| Method | Path | Scope |
|---|---|---|
POST | /api/tool-references | tool-reference:manage |
PUT DELETE | /api/tool-references/{id} | tool-reference:manage |
POST | /api/tool-references/{id}/force-refresh | tool-reference:manage |
POST | /api/tool-references/test-mcp | tool-reference:manage |
GET | /api/tool-references | one of agent:create, agent:update, tool-reference:manage (or a signed-in session); MCP server URL reduced to scheme and host, header values omitted, unless the caller holds tool-reference:manage |
GET | /api/tool-references/{id} | as the list; MCP configuration redacted as above without tool-reference:manage |
Registering a remote MCP server is a tool-references create — MCP servers
are modelled as tools rather than as a separate resource.
POST /api/tool-references/test-mcp probes a candidate server before you
save it. Send {"url": "https://…"}; it replies with reachable,
authRequired, dcrSupported and a detail string, so a provisioning script
can fail fast on an unreachable endpoint.
Tasks
| Method | Path | Scope |
|---|---|---|
GET | /api/tasks | task:manage |
GET PUT DELETE | /api/tasks/{id} | task:manage |
POST | /api/tasks/{id}/run | task:manage |
GET | /api/tasks/{id}/runs | task:manage |
GET DELETE | /api/tasks/{id}/runs/{run_id} | task:manage |
A task:manage key sees only its owner's tasks; the all-tasks view is
an admin-session feature. POST /{id}/run takes free-form JSON as input
({} for none) and returns the run — useful for triggering an existing
task from CI.
Swarms
| Method | Path | Scope |
|---|---|---|
GET POST | /api/teams | team:manage |
GET PUT DELETE | /api/teams/{id} | team:manage |
Swarms are private: they belong to the person who created them, and the
routes return only the caller's own swarms by default. team:create is enough to
create, change and delete your own swarms; team:manage adds
GET /api/teams?all=true (list every swarm) and deleting other people's swarms,
but never reading or chatting in them. The hopCap and costCeiling fields
(0 = unlimited) limit a conversation turn. The swarm chat routes are a
separate end-user surface and are not part of the management API.
Teams
Premium featureThe routes of teams (groups of people with a shared
workspace; spaces in the code) serve the interface with a browser session. The
team routes are browser-session only and are refused for API keys; there is no
dedicated management scope for them. What an API key can reach otherwise is listed
in /api/openapi.json. All routes are feature-gated (enabled per instance) and check
membership in the handler: a non-member gets 404.
| Method | Path | Purpose |
|---|---|---|
GET POST | /api/spaces | List your teams (including the Personal team) or create one, depending on the "Who may create teams" setting |
GET | /api/spaces/can-create | May the caller create teams? |
GET | /api/spaces/principals | Users and groups for the admin console (space:manage) |
GET PUT DELETE | /api/spaces/{space_id} | Read, change, delete a team (deleting is admin-only) |
GET POST | /api/spaces/{space_id}/members | List, add members |
PUT DELETE | /api/spaces/{space_id}/members/{member_id} | Change a role, remove a member |
GET | /api/spaces/{space_id}/groups-available | Groups that can be added |
GET POST | /api/spaces/{space_id}/agents | List the agents granted to the team, grant an agent |
GET | /api/spaces/{space_id}/agents/grantable | Agents that can be granted |
DELETE | /api/spaces/{space_id}/agents/{agent_id} | Revoke an agent |
GET POST | /api/spaces/{space_id}/invitations | List invitations, create an invitation link |
DELETE | /api/spaces/{space_id}/invitations/{code} | Revoke an invitation |
GET | /api/space-invitations/{code} | Look up an invitation (the code is the credential) |
POST | /api/space-invitations/{code}/accept | Accept an invitation |
POST | /api/spaces/{space_id}/projects/{project_id}/move | Move a project into the team |
* | /api/spaces/{space_id}/projects/{project_id}/... | The project routes in the context of the team (404 when the project does not belong to the team) |
GET PUT | /api/settings/workspaces | Read and change "Who may create teams" (creationMode: off, everyone, groups; plus creationGroups) |
GET | /api/catalog/agents | Agents in the team catalog |
PUT | /api/agents/{id}/catalog | Make an agent available in the catalog (administrators only) |
Chats in a team stay private; neither these routes nor team admins give access to other members' chats.
Triggers
| Method | Path | Scope |
|---|---|---|
POST GET | /api/webhooks | trigger:manage |
GET PUT DELETE | /api/webhooks/{id} | trigger:manage |
POST GET | /api/email-receivers | trigger:manage |
GET PUT DELETE | /api/email-receivers/{id} | trigger:manage |
POST GET | /api/cronjobs | trigger:manage |
GET PUT DELETE | /api/cronjobs/{id} | trigger:manage |
Webhook create/update accept a write-only token field alongside the
manifest; it is never returned on read.
Example: provision an agent end to end
With a key holding agent:create:*, agent:update:*,
knowledgeset:manage:* and agent:chat:*:
import httpx, pathlib
api = httpx.Client(
base_url="https://your-instance.platform.basepeak.ai",
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=60,
)
# 1. Create the agent.
agent = api.post("/api/agents", json={
"name": "Support Assistant",
"description": "Answers questions from the support handbook",
"prompt": "You are a support assistant. Answer only from your knowledge.",
}).raise_for_status().json()
agent_id = agent["id"]
# 2. Create a knowledge set.
ks = api.post("/api/knowledge-sets", json={
"name": "Support handbook",
}).raise_for_status().json()
ks_id = ks["id"]
# 3. Upload documents — raw body, filename in the path.
for doc in pathlib.Path("handbook").glob("*.pdf"):
api.post(f"/api/knowledge-sets/{ks_id}/knowledge-files/{doc.name}",
content=doc.read_bytes(),
headers={"Content-Type": "application/pdf"}).raise_for_status()
# 4. Attach the set to the agent.
api.post(f"/api/agents/{agent_id}/knowledge-sets/{ks_id}/attach").raise_for_status()
# 5. Use it. Ingestion is async, so allow time before expecting retrieval.
answer = api.post(f"/api/invoke/{agent_id}",
headers={"Accept": "application/json",
"Content-Type": "text/plain"},
content="What is our refund window?").raise_for_status().json()
print("".join(e.get("content", "") for e in answer["items"]))
Field names for AgentManifest, KnowledgeSetManifest and the rest come
from the spec — check /api/openapi.json for your version rather than
copying them from here.
What stays admin-only
No API key reaches the following, regardless of scopes — they need an admin
browser session. (Those that are in the spec carry x-required-scope: admin;
several are not in the spec at all.)
- Reading a single model (
GET /api/models/{id}) - Listing, updating and deleting workflows (there is no workflow create route)
GET /api/settingsand all instance settings- User, group and auth-provider administration
- Minting API keys — a key cannot create more keys
A holder of settings:manage can write five operational tuning knobs via
PUT /api/settings/runtime (sync/ingestion timeouts, the ingestion limit and
the import max size). Seat limits (max_users) and feature gates stay
read-only and subscription-controlled: there is no route that lets an
instance raise its own limits.
Related docs
- API Keys — scope grammar and minting
- Files — knowledge uploads in detail
- Invoke API — running the agents you provision