bithuman-ai Agent Context API
Control live avatar sessions — make them speak or inject knowledge.
Control live avatar sessions — make them speak or inject knowledge.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bithuman-ai:bithuman-ai-agent-context-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Bithuman Ai Agent Context API
version: '1.0'
contact:
name: bitHuman Support
url: https://www.bithuman.ai/discord
x-logo:
url: https://docs.bithuman.ai/bithuman-mark.png
description: 'Operations tagged Agent Context across 2 of this provider''s published API definitions: openapi.yaml, bithuman-ai-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bithuman.ai
description: Production
security:
- apiSecret: []
tags:
- name: Agent Context
description: Control live avatar sessions — make them speak or inject knowledge.
paths:
/v1/agent/{code}/speak:
post:
operationId: agentSpeak
x-codeSamples:
- lang: shell
label: cURL
source: "curl -X POST https://api.bithuman.ai/v1/agent/A95SXN5716/speak \\\n -H \"api-secret: $BITHUMAN_API_SECRET\" \\\n -H \"content-type: application/json\" \\\n -d '{\"message\": \"Hello! Welcome to our demo.\"}'\n"
summary: Make agent speak
description: 'Send text for the avatar to speak aloud. With `room_id` it goes to that
one session; without it, to every deliverable session of the agent.
The agent must be in at least one active LiveKit room.'
tags:
- Agent Context
parameters:
- name: code
in: path
required: true
schema:
type: string
example: A95SXN5716
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
description: Text for the avatar to speak.
example: Hello! Welcome to our demo.
room_id:
type: string
description: Target a specific room (optional, defaults to all active rooms).
responses:
'200':
description: Speech triggered
content:
application/json:
schema:
type: object
properties:
agent_code:
type: string
example: A95SXN5716
context_type:
type: string
example: speak
delivered_to_rooms:
type: integer
example: 1
description: Number of active rooms that received the message.
rooms:
type: array
items:
type: string
description: Room ids that received the message.
example:
- room-A95SXN5716-x1y2-z3w4
rooms_skipped:
type: array
items:
type: string
description: Live rooms with no agent worker attached, so not delivered to.
rooms_failed:
type: array
items:
type: string
description: Rooms the publish was attempted on and failed.
rooms_skipped_no_worker:
type: integer
description: Length of rooms_skipped.
example: 0
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.bithuman.ai
description: Production
/v1/agent/{code}/sessions:
get:
operationId: listAgentSessions
x-codeSamples:
- lang: shell
label: cURL
source: "curl https://api.bithuman.ai/v1/agent/A95SXN5716/sessions \\\n -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
summary: List an agent's live sessions
description: 'The sessions this agent has open now. Pass a returned `room_id` to
/speak or /add-context to address ONE session instead of broadcasting.
`deliverable` is false when the room is live but no agent worker is
attached — /speak on such a room returns 404.'
tags:
- Agent Context
parameters:
- name: code
in: path
required: true
schema:
type: string
example: A95SXN5716
responses:
'200':
description: Live sessions (possibly an empty list)
content:
application/json:
schema:
type: object
properties:
agent_code:
type: string
example: A95SXN5716
sessions:
type: array
items:
type: object
properties:
room_id:
type: string
example: room-A95SXN5716-x1y2-z3w4
num_participants:
type: integer
example: 3
created_at:
type: integer
description: LiveKit room creation time, Unix seconds.
example: 1788480000
deliverable:
type: boolean
description: Whether an agent worker is attached and /speak would reach it.
example: true
matched_by:
type: string
enum:
- name
- ledger
- name+ledger
- loose
description: How the room was bound to this agent.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.bithuman.ai
description: Production
/v1/agent/{code}/add-context:
post:
operationId: addContext
x-codeSamples:
- lang: shell
label: cURL
source: "curl -X POST https://api.bithuman.ai/v1/agent/A95SXN5716/add-context \\\n -H \"api-secret: $BITHUMAN_API_SECRET\" \\\n -H \"content-type: application/json\" \\\n -d '{\"context\": \"The customer just purchased a premium plan.\"}'\n"
summary: Add context to agent
description: 'Inject background knowledge into the agent''s context. The avatar
won''t say this aloud, but will use the information in future responses.'
tags:
- Agent Context
parameters:
- name: code
in: path
required: true
schema:
type: string
example: A95SXN5716
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- context
properties:
context:
type: string
description: Knowledge to inject.
example: The customer just purchased a premium plan.
type:
type: string
enum:
- add_context
- speak
default: add_context
description: '`add_context` for silent knowledge (default), `speak` to trigger verbal response.'
room_id:
type: string
description: Target a specific room (optional).
responses:
'200':
description: Context added
content:
application/json:
schema:
type: object
properties:
agent_code:
type: string
example: A95SXN5716
context_type:
type: string
example: add_context
delivered_to_rooms:
type: integer
example: 1
description: Number of active rooms that received the context.
rooms:
type: array
items:
type: string
description: Room ids that received the context.
example:
- room-A95SXN5716-x1y2-z3w4
rooms_skipped:
type: array
items:
type: string
description: Live rooms with no agent worker attached, so not delivered to.
rooms_failed:
type: array
items:
type: string
description: Rooms the publish was attempted on and failed.
rooms_skipped_no_worker:
type: integer
description: Length of `rooms_skipped`.
example: 0
example:
agent_code: A95SXN5716
context_type: add_context
delivered_to_rooms: 1
rooms_skipped_no_worker: 0
rooms:
- room-A95SXN5716-x1y2-z3w4
rooms_skipped: []
rooms_failed: []
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.bithuman.ai
description: Production
components:
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Agent not found
httpStatus: 404
status: error
status_code: 404
Unauthorized:
description: 'Authentication failed. `UNAUTHORIZED` when the `api-secret` header is
present but invalid; `MISSING_AUTH` when it is absent. The HTTP status
equals `status_code` (401).
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Invalid API secret
httpStatus: 401
status: error
status_code: 401
RateLimited:
description: 'Too many requests. The limiter is **per account** — every API secret on
the account draws from one bucket — and **per cost tier**, so a burst of
reads never uses up your generate budget. Your plan sets the number for
each tier; the matrix, the tier each route belongs to and a retry
recipe are on
[Rate limits](https://docs.bithuman.ai/api/rate-limits).
Wait `Retry-After` seconds and retry. The `X-RateLimit-*` headers let a
client slow down *before* it gets here, but header coverage is uneven
across routes — read them defensively and fall back to exponential
backoff when they are absent.
On a route that can also be called without an API secret, an anonymous
call is metered per network address instead: same body, same
`Retry-After`, no `X-RateLimit-*`.
'
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
example: 1
X-RateLimit-Limit:
schema:
type: integer
description: Requests per minute your plan allows on this request's cost tier.
example: 30
X-RateLimit-Remaining:
schema:
type: integer
description: Whole requests left in the bucket right now.
example: 0
X-RateLimit-Reset:
schema:
type: integer
description: Unix time at which the bucket is fully refilled.
example: 1758380460
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMITED
message: Too many generate requests for this api-secret. Retry in ~1s.
httpStatus: 429
status: error
status_code: 429
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: UNAUTHORIZED
message:
type: string
example: Invalid API secret
httpStatus:
type: integer
example: 401
upgrade_url:
type: string
description: 'On `PLAN_REQUIRED`, `AGENT_LIMIT_REACHED` and `CONCURRENCY_LIMIT_REACHED` (403): where to choose a plan. Send the user there instead of retrying. See [Plan and credit refusals](https://docs.bithuman.ai/api/errors#plan-and-credit-refusals).'
example: https://www.bithuman.ai/pricing
topup_url:
type: string
description: 'On `INSUFFICIENT_BALANCE` (402): where to top up credits.'
example: https://www.bithuman.ai/billing#credits
details:
type: object
description: Code-specific fields. `CONCURRENCY_LIMIT_REACHED` sends `tier`, `cap`, `active` and `upgrade_url`.
additionalProperties: true
status:
type: string
example: error
status_code:
type: integer
example: 401
securitySchemes:
apiSecret:
type: apiKey
name: api-secret
in: header
description: 'Your bitHuman API secret. Get one at
[www.bithuman.ai/developer/api-keys](https://www.bithuman.ai/developer/api-keys).
'
bearerApiSecret:
type: http
scheme: bearer
description: 'The same API secret, sent as `Authorization: Bearer <api-secret>`. Self-
hosted runtimes send it this way; the classic `api-secret` header works
on the same routes.
'
x-refined-from:
- openapi.yaml
- bithuman-ai-openapi.yaml
x-tagGroups:
- name: Get started
tags:
- overview
- quickstart
- auth-guide
- models
- pricing
- name: Core concepts
tags:
- avatars-imx
- audio-streaming
- agent-lifecycle
- name: SDKs
tags:
- sdk-python
- sdk-swift
- cli
- name: Guides
tags:
- local-mode
- building-avatars
- name: Deployment
tags:
- deploy-livekit
- deploy-self-hosted
- deploy-embed
- name: API reference
tags:
- Authentication
- Agent Generation
- Agent Management
- Agent Context
- Files
- Dynamics
- Embedding
- Video
- Billing
- Account
- Self-hosting
- API secrets
- Providers
- Runtime sessions
- Knowledge
- Realtime
- Status
- Webhooks
- name: Resources
tags:
- community
- changelog
- support