HTTP API overview

The HTTP API is the API of the captionbob server in the folder captionbob_server.

Address

By default, the server listens on http://127.0.0.1:9400. The settings CAPTIONBOB_HOST and CAPTIONBOB_PORT in the .env file of captionbob_server change the host and the port.

Callers

A request names its caller in one of two ways:

• An API key in the header Authorization: Bearer <API key>.
• The session cookie captionbob_session of a dashboard login.

Access

Each route has one access value, which says who may call it.

Access	Who may call the route
none	A route that anyone may call, such as the login.
any	A route that a dashboard login or an API key may call.
session	A route that only a dashboard login may call, such as the key routes.

Errors

The fixed error codes of the API with the HTTP status of each. An error answer is the JSON object {"error": {"code", "message"}}.

Code	HTTP status
bad_json	400
bad_value	400
not_logged_in	401
bad_login	401
bad_api_key	401
bad_desktop_key	401
login_needed	403
not_found	404
method_not_allowed	405
nothing_to_undo	409
nothing_to_redo	409
no_version	409
render_in_progress	409
render_not_done	409
emoji_index_needed	409
too_large	413
wrong_content_type	415
bad_range	416
not_a_video	422
server_error	500
python_failed	502

Routes

Method	Path	Access	Page
POST	/api/login	none	Account routes
POST	/api/logout	none	Account routes
GET	/api/me	any	Account routes
GET	/api/keys	session	Account routes
POST	/api/keys	session	Account routes
DELETE	/api/keys/:keyId	session	Account routes
GET	/api/projects	any	Project routes
POST	/api/projects	any	Project routes
GET	/api/projects/:projectId	any	Project routes
PATCH	/api/projects/:projectId	any	Project routes
POST	/api/projects/:projectId/videos	any	Project routes
GET	/api/videos/:videoId	any	Video routes
DELETE	/api/videos/:videoId	any	Video routes
GET	/api/videos/:videoId/file	any	Video routes
GET	/api/videos/:videoId/versions	any	Video routes
POST	/api/videos/:videoId/versions	any	Video routes
GET	/api/videos/:videoId/versions/:number	any	Video routes
GET	/api/videos/:videoId/versions/:number/script	any	Video routes
POST	/api/videos/:videoId/undo	any	Video routes
POST	/api/videos/:videoId/redo	any	Video routes
POST	/api/videos/:videoId/renders	any	Render routes
GET	/api/videos/:videoId/renders	any	Render routes
GET	/api/renders/:renderId	any	Render routes
GET	/api/renders/:renderId/file	any	Render routes
GET	/api/styles	any	Catalog routes
GET	/api/plugins	any	Catalog routes
GET	/api/fonts	any	Font routes
GET	/api/fonts/:fontId	any	Font routes
POST	/api/font-fallback	any	Font routes
GET	/api/font-families	any	Font routes
GET	/api/emoji-image	any	Emoji routes