# BOLD Video API

> BOLD is a video management platform for hosting, transcribing, and surfacing video libraries through branded portals, playlists, AI chat, recommendations, viewer profiles, progress, and community integrations.

All documented endpoints live under `https://app.boldvideo.io/api/v1` and require `Authorization: Bearer YOUR_API_TOKEN` unless a specific endpoint says otherwise. Runtime session-management endpoints under `/api/v1/auth/*` use the customer's upstream IdP JWT plus `X-Bold-Tenant-Slug`. Server-side session-management endpoints under `/api/v1/session-management/*` use the normal tenant API token and do not require an admin key. Viewer, progress, and community endpoints are customer integration APIs intended for tenant-scoped browser integrations. The OpenAPI spec is the canonical machine-readable contract.

## API reference

- [OpenAPI spec (JSON)](https://app.boldvideo.io/api/openapi)
- [OpenAPI spec (YAML)](https://app.boldvideo.io/openapi.yaml)
- [Swagger UI](https://app.boldvideo.io/api/docs)

## Endpoint groups

### AI Chat

- `GET /api/v1/ai/chat` - List library chat conversations
- `POST /api/v1/ai/chat` - Chat with your video library
- `DELETE /api/v1/ai/chat/{id}` - Delete a library chat conversation
- `GET /api/v1/ai/chat/{id}` - Get conversation history
- `POST /api/v1/ai/chat/{id}` - Continue a library chat
- `GET /api/v1/ai/videos/{id}/chat` - List video chat conversations
- `POST /api/v1/ai/videos/{id}/chat` - Chat about a video
- `DELETE /api/v1/ai/videos/{id}/chat/{conversation_id}` - Delete a video chat conversation
- `GET /api/v1/ai/videos/{id}/chat/{conversation_id}` - Get a video chat conversation
- `POST /api/v1/ai/videos/{id}/chat/{conversation_id}` - Continue a video chat conversation

### AI Conversations

- `GET /api/v1/ai/conversations` - List all conversations for a viewer

### AI Recommendations

- `POST /api/v1/ai/recommendations` - Get video recommendations

### AI Search

- `POST /api/v1/ai/search` - Search with AI synthesis

### Admin Auth Policy

- `GET /api/v1/admin/auth/policy` - Get the tenant's user-tunable auth policy
- `PUT /api/v1/admin/auth/policy` - Update the tenant's user-tunable auth policy

### Admin Auth Sessions

- `GET /api/v1/admin/viewers/{viewer_id}/sessions` - List active + last-30-days revoked sessions for a viewer
- `POST /api/v1/admin/viewers/{viewer_id}/sessions/revoke-all` - Admin-revoke every active session for a viewer
- `POST /api/v1/admin/viewers/{viewer_id}/sessions/{id}/revoke` - Admin-revoke a single session

### Admin Viewers

- `GET /api/v1/admin/viewers/by-external-id/{external_id}` - Resolve an upstream IdP user ID to a Bold viewer_id
- `PUT /api/v1/admin/viewers/{viewer_id}/device-limit` - Set or clear a viewer's device-limit override
- `PUT /api/v1/admin/viewers/{viewer_id}/session-management-exemption` - Set or clear a viewer's session-management exemption

### Auth Challenges

- `POST /api/v1/auth/challenges/{id}/resend` - Resend an auth challenge code
- `POST /api/v1/auth/challenges/{id}/verify` - Verify an auth challenge code

### Auth Sessions

- `GET /api/v1/auth/sessions` - List active sessions for the authenticated viewer
- `POST /api/v1/auth/sessions` - Create a session for the authenticated viewer's device
- `POST /api/v1/auth/sessions/revoke-others` - Revoke all of the authenticated viewer's sessions except the current one
- `POST /api/v1/auth/sessions/{id}/revoke` - Self-revoke one of the authenticated viewer's sessions
- `GET /api/v1/auth/sessions/{id}/verify` - Verify a session is still valid

### Collections

- `GET /api/v1/collections` - List collections
- `GET /api/v1/collections/{collection_id}/videos` - List videos in a collection
- `GET /api/v1/collections/{id}` - Get a collection

### Community

- `DELETE /api/v1/community/comments/{id}` - Delete a comment
- `POST /api/v1/community/comments/{id}/react` - Toggle reaction on a comment
- `GET /api/v1/community/posts` - List community posts
- `POST /api/v1/community/posts` - Create a community post
- `DELETE /api/v1/community/posts/{id}` - Delete a community post
- `GET /api/v1/community/posts/{id}` - Get a community post
- `PATCH /api/v1/community/posts/{id}` - Update a community post
- `PUT /api/v1/community/posts/{id}` - Update a community post
- `POST /api/v1/community/posts/{id}/react` - Toggle reaction on a post
- `POST /api/v1/community/posts/{post_id}/comments` - Create a comment on a post

### Playlists

- `GET /api/v1/playlists` - List playlists
- `GET /api/v1/playlists/{id}` - Get a playlist

### Progress

- `GET /api/v1/viewers/{viewer_id}/progress` - List viewer progress
- `DELETE /api/v1/viewers/{viewer_id}/progress/{video_id}` - Reset progress
- `GET /api/v1/viewers/{viewer_id}/progress/{video_id}` - Get progress for a video
- `POST /api/v1/viewers/{viewer_id}/progress/{video_id}` - Create or update progress
- `POST /api/v1/viewers/{viewer_id}/progress/{video_id}/complete` - Mark video as complete

### Search

- `GET /api/v1/search` - Search public video content

### Session Management

- `GET /api/v1/session-management/viewers/by-external-id/{external_id}` - Resolve an upstream user ID to a BOLD viewer
- `PUT /api/v1/session-management/viewers/by-external-id/{external_id}/device-limit` - Set or clear a viewer's device-limit override by upstream user ID
- `PUT /api/v1/session-management/viewers/by-external-id/{external_id}/session-management-exemption` - Set or clear a viewer's session-management exemption by upstream user ID
- `GET /api/v1/session-management/viewers/by-external-id/{external_id}/sessions` - List sessions for a viewer by upstream user ID
- `POST /api/v1/session-management/viewers/by-external-id/{external_id}/sessions/revoke-all` - Revoke every active session for a viewer by upstream user ID
- `POST /api/v1/session-management/viewers/by-external-id/{external_id}/sessions/{id}/revoke` - Revoke a viewer session by upstream user ID

### Settings

- `GET /api/v1/settings` - Get portal settings

### Videos

- `GET /api/v1/videos` - List public videos
- `POST /api/v1/videos` - Create a video from URL
- `GET /api/v1/videos/latest` - Get latest videos
- `GET /api/v1/videos/{id}` - Get a video

### Viewers

- `GET /api/v1/viewers` - List viewers (paginated)
- `POST /api/v1/viewers` - Create a viewer
- `GET /api/v1/viewers/lookup` - Look up a viewer
- `DELETE /api/v1/viewers/{id}` - Delete a viewer
- `GET /api/v1/viewers/{id}` - Get a viewer
- `PATCH /api/v1/viewers/{id}` - Update a viewer
- `PUT /api/v1/viewers/{id}` - Update a viewer
- `DELETE /api/v1/viewers/{viewer_id}/memory` - Clear a viewer's memory
- `GET /api/v1/viewers/{viewer_id}/memory` - Get a viewer's memory
- `PATCH /api/v1/viewers/{viewer_id}/memory` - Update a viewer's memory settings


## Hidden from public docs

Legacy aliases, debug endpoints, analytics beacons, portal-runtime authentication, internal `/i/v1/*` routes, webhook routes, and dangerous bulk/private-content routes are intentionally excluded from this public contract.