Skip to main content

Management API

Premium feature

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):

TagWhat it coversPage
ChatInvoke API: send a turn to an agentInvoke API
OpenAIOpenAI-compatible routes under /v1OpenAI-compatible API
ThreadsList and read conversations, replay events, cancel a runThreads
FilesWorkspace files on an agent and on a conversationFiles
ProjectsProject-addressable chat, workspace, knowledge, environment, tasksProjects
ManagementThe catalogue: agents, knowledge sets, models, tools, tasks, swarms, triggersthis 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:

ScopeGrants
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 *:

ScopeReach
agent:update:*May update any agent its owner can
agent:update:a17jlm7May 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​

MethodPathScope
POST/api/agentsagent:create
GET/api/agentsagent:create
GET/api/agents/{id}agent:create
PUT/api/agents/{id}agent:update
DELETE/api/agents/{id}agent:delete
POST/api/agents/{id}/copyagent:create
GET/api/agents/{id}/exportagent:create
POST/api/agents/importagent:create
PUT/api/agents/{id}/setdefaultagent:update
POST/api/agents/{id}/knowledge-sets/{knowledge_set_id}/attachagent:update
DELETE/api/agents/{id}/knowledge-sets/{knowledge_set_id}/detachagent:update
GET/api/agents/{id}/authorizationsagent:create
POST/api/agents/{id}/authorizations/addagent:update
POST/api/agents/{id}/authorizations/removeagent:update

Export/import use a YAML-or-JSON agent envelope, so an agent can be moved between instances as a file.

Knowledge sets​

MethodPathScope
POST GET/api/knowledge-setsknowledgeset:manage
GET PUT DELETE/api/knowledge-sets/{id}knowledgeset:manage
GET/api/knowledge-sets/{id}/knowledge-filesknowledgeset:manage
POST DELETE/api/knowledge-sets/{id}/knowledge-files/{file...}knowledgeset:manage
POST GET/api/knowledge-sets/{id}/exportsknowledgeset:manage
GET DELETE/api/knowledge-sets/{id}/exports/{export_id}knowledgeset:manage
POST GET/api/knowledge-set-importsknowledgeset:manage
GET DELETE/api/knowledge-set-imports/{import_id}knowledgeset:manage

Models and providers​

MethodPathScope
POST/api/modelsmodel-provider:manage
PUT DELETE/api/models/{id}model-provider:manage
GET/api/modelsone of agent:create, agent:update, model-provider:manage (or a signed-in session)
GET/api/models/{id}admin-only
GET/api/model-providersmodel-provider:manage
GET/api/model-providers/{model_provider_id}model-provider:manage
POST/api/model-providers/{id}/configuremodel-provider:manage
POST/api/model-providers/{id}/validatemodel-provider:manage

configure and validate take a flat environment-variable map as their body.

Tools and MCP servers​

MethodPathScope
POST/api/tool-referencestool-reference:manage
PUT DELETE/api/tool-references/{id}tool-reference:manage
POST/api/tool-references/{id}/force-refreshtool-reference:manage
POST/api/tool-references/test-mcptool-reference:manage
GET/api/tool-referencesone 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​

MethodPathScope
GET/api/taskstask:manage
GET PUT DELETE/api/tasks/{id}task:manage
POST/api/tasks/{id}/runtask:manage
GET/api/tasks/{id}/runstask: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​

MethodPathScope
GET POST/api/teamsteam: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 feature

The 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.

MethodPathPurpose
GET POST/api/spacesList your teams (including the Personal team) or create one, depending on the "Who may create teams" setting
GET/api/spaces/can-createMay the caller create teams?
GET/api/spaces/principalsUsers 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}/membersList, add members
PUT DELETE/api/spaces/{space_id}/members/{member_id}Change a role, remove a member
GET/api/spaces/{space_id}/groups-availableGroups that can be added
GET POST/api/spaces/{space_id}/agentsList the agents granted to the team, grant an agent
GET/api/spaces/{space_id}/agents/grantableAgents that can be granted
DELETE/api/spaces/{space_id}/agents/{agent_id}Revoke an agent
GET POST/api/spaces/{space_id}/invitationsList 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}/acceptAccept an invitation
POST/api/spaces/{space_id}/projects/{project_id}/moveMove 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/workspacesRead and change "Who may create teams" (creationMode: off, everyone, groups; plus creationGroups)
GET/api/catalog/agentsAgents in the team catalog
PUT/api/agents/{id}/catalogMake 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​

MethodPathScope
POST GET/api/webhookstrigger:manage
GET PUT DELETE/api/webhooks/{id}trigger:manage
POST GET/api/email-receiverstrigger:manage
GET PUT DELETE/api/email-receivers/{id}trigger:manage
POST GET/api/cronjobstrigger: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/settings and 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.

  • API Keys — scope grammar and minting
  • Files — knowledge uploads in detail
  • Invoke API — running the agents you provision