API Overview
BasePeak.AI exposes two ways to talk to an agent over HTTP, plus a management surface for creating and configuring resources. All three authenticate with the same scoped bearer token (see API Keys).
Which surface should I use?
| You want to… | Use | Page |
|---|---|---|
| Drop BasePeak.AI into code that already speaks OpenAI | POST /v1/chat/completions | OpenAI-compatible API |
| Stream tool calls, steps and prompts — not just text | POST /api/invoke/{id} | Invoke API |
| Fire off a long job and not hold the connection open | POST /api/invoke/{id}?async=true | Invoke API |
| Keep several independent conversations going | thread targeting on either surface | Threads |
| Give an agent documents to work with | knowledge-set upload | Files |
| Create or reconfigure agents, knowledge sets, tasks | the management API | Management API |
| Run the same conversation the browser runs in a project — shared workspace, tasks, credentials and model settings included | POST /api/projects/{project_id}/invoke | Projects |
The short version: use /v1/chat/completions if you have an existing
OpenAI client, and use /api/invoke/{id} if you want the agent's full
event stream — tool calls, step transitions and OAuth prompts are visible
there but deliberately hidden from the OpenAI surface.
Both surfaces run the same agent. They differ only in wire format.
Base URL
Each instance runs at its own hostname:
https://your-instance.platform.basepeak.ai
The OpenAI-compatible routes live under /v1/…; everything else lives
under /api/….
Authentication in one minute
curl -sS https://your-instance.platform.basepeak.ai/api/invoke/a17jlm7 \
-H "Authorization: Bearer sk-bpai-1-42-…" \
-H "Content-Type: text/plain" \
--data 'Summarise our refund policy.'
Create the token in the UI under Profile → API Keys, scoped to the agent you want to call. Full token model, scope grammar and audit trail: API Keys.
A key holding only agent:chat:… silently loses every tool that depends on a
stored credential. Add credential:use:* when your integration relies on them
— see
Credential scopes.
Prerequisite: API access is a premium feature
Programmatic API access is a premium feature, gated by the apiAccess
feature on your instance. Everything on these pages requires it. When it is off:
- creating a key returns
403— API access is disabled for this instance - using an existing key returns
403 auth/api-access-disabled
The flag follows your subscription and there is no self-service switch for it — a tenant admin cannot turn it on from the settings UI. If you get that error, contact your BasePeak.AI representative.
What an API key can and cannot reach
An sk-bpai-… key is confined to an explicit route allowlist, regardless
of what its owner could do in the browser. Anything outside the allowlist
returns 403 even if the key's scopes would otherwise suggest access.
Reachable with a key:
| Surface | Routes |
|---|---|
| Chat / invoke | POST /api/invoke/{id}, POST /api/invoke/{id}/thread/{thread} (also /threads/), POST /v1/chat/completions |
| Chat / invoke inside a project | POST /api/projects/{project_id}/invoke, POST /api/projects/{project_id}/invoke/thread/{thread} (also /threads/) — see Projects |
| Model / embedding proxies | GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings, POST /v1/audio/transcriptions |
| Agent and thread files | GET /api/agents/{id}/files, GET/POST/DELETE /api/agents/{id}/files/{path}, GET /api/threads/{id}/files, GET/POST/DELETE /api/threads/{id}/files/{path} — see Files |
| A project's files, knowledge, tasks and environment variables | /api/projects/{project_id}/files…, /api/projects/{project_id}/knowledge…, /api/projects/{project_id}/tasks…, /api/projects/{project_id}/env — see Projects |
| Threads | GET /api/threads, GET /api/threads/{id}, GET /api/threads/{id}/events, POST /api/threads/{id}/abort — see Threads |
| Management | the routes listed in Management API |
Not reachable with a key — browser session only:
| Not available | Consequence |
|---|---|
PUT /api/threads/{id}, DELETE /api/threads/{id} | You cannot rename or delete threads over the API. Reading, replaying history and aborting are available — see above. |
| Project members, invitations, credentials (management) | These three change who reaches a project, or hand out stored secrets — see Projects. |
These limits are current behavior, not permanent design.
Machine-readable: the OpenAPI spec
Every instance serves an OpenAPI 3.1 spec describing every operation a key
can reach — chat, /v1, conversations, files, projects and the management
routes:
curl -sS https://your-instance.platform.basepeak.ai/api/openapi.json
Reachable without authentication, generated from the same table that registers the routes. If you would rather generate a client than hand-write calls, start there: Management API → The OpenAPI spec is the reference.
Related docs
- API Keys — tokens, scopes, audit trail
- OpenAI-compatible API —
/v1/chat/completions - Invoke API — the native event stream
- Threads — multi-turn and multi-conversation
- Files — getting documents to an agent
- Management API — resource CRUD
- Projects — the conversation the browser runs, over the API too