Developers

Everything you can build against a bitpull agent

Four extension points, one API key, and a set of honest limits. This page is the map - each card links to the reference that goes deep.

The mental model

An agent in bitpull is a configured conversational unit: a system prompt, a voice, a language set, a knowledge body, and optionally a set of declared tools. It is addressed by an API key. Every channel - phone, website widget, your own app - talks to the same agent, which is why the knowledge and the behaviour only have to be maintained once.

A session is one conversation with that agent. You create it over REST and receive a LiveKit room URL and a token; the audio or text then flows over that room, not over the REST API. That split is the single most important thing to understand before writing any code against the platform.

POST /api/sessionsBearer <agent key>
wsUrl + tokenLiveKit room
Conversationaudio or text streams
POST /:id/endclose it cleanly

The session lifecycle. Everything else on this site hangs off it.

The four extension points

There are exactly four seams where your code meets a bitpull agent. Everything on this domain is one of them, or a recipe built from them.

REST API

Available

Create and end sessions, read the configured languages, mint room tokens. The agent API key is the credential; the conversation itself runs over LiveKit.

POST /api/sessions · GET /api/sessions/languages

Website embedding

Available

The hosted widget runtime as a script tag with data attributes, or a headless integration where you render everything and only borrow the session.

script tag · livekit-client

Agent tools

Available

Function declarations on the agent - name, description, JSON Schema, timeout. The model decides when to call them from the description you write.

customTools[] · 1000–60000 ms

Outbound webhook

Beta · account flag

One HTTPS URL per agent receives the finished conversation: transcript, summary, outcome, sentiment, channel and timing.

per agent · account flag

Authentication in one table

Two credential types exist and they are not interchangeable. Nearly every integration problem that looks like a permissions bug is one of these used in the wrong place.

Credential	Header	Reaches	Where it belongs
Agent API key	`Authorization: Bearer <API_KEY>`	Session lifecycle, language list, token minting	Your backend. It is also what the website widget carries in the page, by design.
Agent API secret	-	Server-side use only	Never in frontend code, never in a repository, never in a script tag.
User token (JWT)	`Authorization: Bearer <JWT>`	Account, agents, numbers, prompts, conversation history	The dashboard. It is a logged-in user's session, not an integration credential.

The widget key is public on purpose

The embed snippet puts the agent API key into the page, because the browser has to create a session. That key can start conversations against your agent - which is why the secret is a separate value and why keys can be regenerated from the dashboard. Treat the key as a public identifier with a cost attached, not as a password.

What is not there

Stated plainly, so you can design around it instead of discovering it in week three:

No official SDK. No npm or PyPI package published by bitpull. REST plus livekit-client is the supported path - see SDKs.
No published OpenAPI document. The reference on this site was written by reading the platform, not generated from a spec - why that matters.
No public agent-management API. Creating agents, buying numbers and editing prompts happen with a logged-in user token, not with an integration credential.
No retrieval API for knowledge. Knowledge is compiled into the agent's instructions rather than queried at answer time - what that means in practice.
No MCP server. Neither as a client nor as a server today - the state of it.

A sensible first hour

Create an agent on bitpull.ai and copy its API key from Agent → Website/Deploy → API access.
curl https://api.bitpull.ai/health - no auth, confirms reachability.
GET /api/sessions/languages with the key - confirms the key works and shows what the agent is actually configured for.
Paste the widget snippet into a static page and talk to it. Five minutes, and it makes the rest concrete.
Point the outbound webhook at the tester on this site and press Test delivery. Now you know the real payload.