# API reference

URL: https://docs.bithuman.ai/api/reference

> Every endpoint in the bitHuman OpenAPI spec, grouped by resource.

The OpenAPI 3 spec (https://docs.bithuman.ai/api/openapi.yaml) covers the /v1 endpoints. The account endpoints under /v2 and knowledge have their own pages: [Organizations](https://docs.bithuman.ai/api/organizations.md) · [Providers](https://docs.bithuman.ai/api/providers.md) · [Runtime sessions](https://docs.bithuman.ai/api/runtime-sessions.md) · [API secrets](https://docs.bithuman.ai/api/api-keys.md) · [Knowledge](https://docs.bithuman.ai/api/knowledge.md). Authenticate with the `api-secret` header ([Authentication](https://docs.bithuman.ai/api/authentication.md)).

## Authentication

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/validate` | [Validate API secret](https://docs.bithuman.ai/api/authentication#post-v1validate) |
| POST | `/v1/runtime-tokens/mint` | [Mint a scoped runtime token for one agent](https://docs.bithuman.ai/api/authentication#post-v1runtime-tokensmint) |
| POST | `/v1/runtime-tokens/request` | [Request a runtime token, or start a cloud avatar](https://docs.bithuman.ai/api/authentication#post-v1runtime-tokensrequest) |

## Agent Generation

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/agent/generate` | [Generate a new agent](https://docs.bithuman.ai/api/agents#generate-an-agent) |
| GET | `/v1/agent/status/{agent_id}` | [Get agent generation status](https://docs.bithuman.ai/api/agents#poll-status) |

## Agent Management

| Method | Path | What it does |
|---|---|---|
| GET | `/v1/agent/{code}` | [Get agent details](https://docs.bithuman.ai/api/agents#get-an-agent) |
| POST | `/v1/agent/{code}` | [Update an agent's prompt or providers](https://docs.bithuman.ai/api/agents#update-an-agent) |
| DELETE | `/v1/agent/{code}` | [Delete an agent](https://docs.bithuman.ai/api/agents#delete-an-agent) |
| POST | `/v1/agent/{code}/models` | [Add a model to an existing agent](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent) |
| GET | `/v1/agent/{code}/model/download` | [Download an agent's model artifact](https://docs.bithuman.ai/api/agents#download-an-agents-model) |
| GET | `/v1/models/showcase` | [List the freely downloadable showcase models](https://docs.bithuman.ai/api/agents#list-the-freely-downloadable-showcase-models) |
| GET | `/v1/agents` | [List agents](https://docs.bithuman.ai/api/agents#list-your-agents) |

## Agent Context

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/agent/{code}/speak` | [Make agent speak](https://docs.bithuman.ai/api/agents#make-an-agent-speak) |
| GET | `/v1/agent/{code}/sessions` | [List an agent's live sessions](https://docs.bithuman.ai/api/agents#list-an-agents-live-sessions) |
| POST | `/v1/agent/{code}/add-context` | [Add context to agent](https://docs.bithuman.ai/api/knowledge#inject-knowledge) |

## Files

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/files/upload` | [Upload a file](https://docs.bithuman.ai/api/files#upload-a-file) |

## Dynamics

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/dynamics/generate` | [Generate gesture animations](https://docs.bithuman.ai/api/dynamics#generate-dynamics) |
| GET | `/v1/dynamics/{agent_id}` | [Get available gestures](https://docs.bithuman.ai/api/dynamics#get-dynamics) |
| PUT | `/v1/dynamics/{agent_id}` | [Update dynamics configuration](https://docs.bithuman.ai/api/dynamics#update-dynamics) |

## Embedding

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/embed-tokens/request` | [Generate embed token](https://docs.bithuman.ai/api/embedding#production-mint-a-token) |

## Video

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/video/generate` | [Generate a talking video](https://docs.bithuman.ai/api/video#generate-a-talking-video) |
| GET | `/v1/video/{job_id}` | [Get talking-video status](https://docs.bithuman.ai/api/video#get-talking-video-status) |

## Billing

| Method | Path | What it does |
|---|---|---|
| GET | `/v2/credit-summaries` | [Check credit balance](https://docs.bithuman.ai/api/billing#check-credit-balance) |
| GET | `/v1/usage` | [Usage history](https://docs.bithuman.ai/api/billing#usage-history) |

## Account

| Method | Path | What it does |
|---|---|---|
| GET | `/v1/me` | [Get current account](https://docs.bithuman.ai/api/billing#account-status) |
| GET | `/v1/pricing` | [Get credit pricing](https://docs.bithuman.ai/api/billing#get-the-pricing-schedule) |

## Self-hosting

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/auth/validate` | [Live key check for a self-hosted runtime](https://docs.bithuman.ai/api/runtime-sessions#live-key-check-for-a-self-hosted-runtime) |
| POST | `/v1/meter/beats` | [Report usage from a self-hosted session](https://docs.bithuman.ai/api/runtime-sessions#report-usage-from-a-self-hosted-session) |

## API secrets

| Method | Path | What it does |
|---|---|---|
| GET | `/v2/{user_id}/api-secrets` | [List API secrets](https://docs.bithuman.ai/api/api-keys#list-api-secrets) |
| POST | `/v2/{user_id}/api-secrets` | [Create an API secret](https://docs.bithuman.ai/api/api-keys#create-an-api-secret) |
| GET | `/v2/{user_id}/api-secrets/{alias}/get-value` | [Reveal an API secret (console only)](https://docs.bithuman.ai/api/api-keys#reveal-an-api-secret) |
| DELETE | `/v2/{user_id}/api-secrets/{alias}` | [Delete an API secret](https://docs.bithuman.ai/api/api-keys#delete-an-api-secret) |

## Providers

| Method | Path | What it does |
|---|---|---|
| GET | `/v2/{user_id}/providers` | [Get provider config](https://docs.bithuman.ai/api/providers#get-provider-config) |
| PUT | `/v2/{user_id}/providers` | [Update provider config](https://docs.bithuman.ai/api/providers#update-provider-config) |

## Runtime sessions

| Method | Path | What it does |
|---|---|---|
| GET | `/v2/{user_id}/runtime-sessions` | [List sessions](https://docs.bithuman.ai/api/runtime-sessions#list-sessions) |
| GET | `/v2/{user_id}/runtime-sessions/{session_id}/messages` | [Read a transcript](https://docs.bithuman.ai/api/runtime-sessions#read-a-transcript) |
| POST | `/v2/{user_id}/runtime-sessions/{session_id}/terminate` | [Terminate a session](https://docs.bithuman.ai/api/runtime-sessions#terminate-a-session) |
| POST | `/v2/{user_id}/runtime/revoke-all` | [Revoke all runtime keys](https://docs.bithuman.ai/api/runtime-sessions#revoke-all-keys) |
| GET | `/v1/runtime-sessions/{session_id}` | [Read a cloud avatar session](https://docs.bithuman.ai/api/runtime-sessions#read-a-cloud-avatar-session) |
| POST | `/v1/runtime-sessions/{session_id}/end` | [End a cloud avatar session](https://docs.bithuman.ai/api/runtime-sessions#end-a-cloud-avatar-session) |

## Knowledge

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/knowledge/files` | [Ingest a file or URL](https://docs.bithuman.ai/api/knowledge#ingest-a-file-or-url) |
| GET | `/v1/knowledge/kbs` | [List knowledge bases](https://docs.bithuman.ai/api/knowledge#list-knowledge-bases) |
| POST | `/v1/knowledge/kbs` | [Create a knowledge base](https://docs.bithuman.ai/api/knowledge#create-a-knowledge-base) |
| POST | `/v1/knowledge/kbs/{kb_id}/rebuild` | [Rebuild a knowledge base](https://docs.bithuman.ai/api/knowledge#rebuild-a-knowledge-base) |

## Realtime

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/realtime/connect` | [Start or end a WebRTC Realtime call](https://docs.bithuman.ai/api/realtime#webrtc) |

## Status

| Method | Path | What it does |
|---|---|---|
| GET | `/readyz` | [API readiness](https://docs.bithuman.ai/api/errors#api-readiness) |

## Webhooks

| Method | Path | What it does |
|---|---|---|
| GET | `/v1/webhooks` | [List webhooks](https://docs.bithuman.ai/api/webhooks#list-webhooks) |
| POST | `/v1/webhooks` | [Create a webhook](https://docs.bithuman.ai/api/webhooks#register-an-endpoint) |
| GET | `/v1/webhooks/{webhook_id}` | [Get a webhook](https://docs.bithuman.ai/api/webhooks#get-a-webhook) |
| DELETE | `/v1/webhooks/{webhook_id}` | [Delete a webhook](https://docs.bithuman.ai/api/webhooks#delete-a-webhook) |
| POST | `/v1/webhooks/{webhook_id}/test` | [Send a test event](https://docs.bithuman.ai/api/webhooks#send-a-test-event) |
| GET | `/v1/webhooks/{webhook_id}/deliveries` | [List delivery attempts](https://docs.bithuman.ai/api/webhooks#list-delivery-attempts) |