REST API overview - Akapulu Labs

The API starts an avatar in a Daily room you create, manages hosted-link rows, and reads the mark on a recording. A browser UI is your page plus your Pipecat bot. The API key stays on your server. See Your bot.

Authentication

Authorization: Bearer <YOUR_AKAPULU_API_KEY>

Create a key from the dashboard after you sign in: API keys.

Base URL

https://akapulu.com/api

Live session

curl -X POST "https://akapulu.com/api/live-sessions/" \
  -H "Authorization: Bearer <YOUR_AKAPULU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "<avatar uuid>",
    "show_ai_label": true,
    "room_url": "https://<your-domain>.daily.co/<room>",
    "avatar_token": "<avatar meeting token>"
  }'

The response is {"session_id": "<uuid>"}. Field rules are on Create a live session.

Hosted links

curl -X POST "https://akapulu.com/api/hosted-links/" \
  -H "Authorization: Bearer <YOUR_AKAPULU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Desk",
    "avatar_id": "<avatar uuid>",
    "system_prompt": "Be brief.",
    "show_ai_label": true
  }'

The response includes id, url, and token. Share url. Full CRUD is under Hosted links.

Error responses

Failed calls return JSON with error and error_code. Branch on error_code.

`error_code`	Typical status	When
`AUTH_MISSING`	401	No Bearer API key
`AUTH_INVALID`	401	API key not recognized
`VALIDATION`	400	Missing or invalid fields
`AVATAR_NOT_FOUND`	404	`avatar_id` is not an avatar you can use
`NOT_FOUND`	404	Hosted link or video-mark check is missing, or the mp4 was not uploaded
`ALREADY_READ`	409	That video-mark check was already read
`QUOTA_EXCEEDED`	403	No minutes remaining
`CONCURRENCY_LIMIT`	403	Too many concurrent calls for the plan
`INTERNAL`	500	The server could not finish the call

Next