API Quickstart

This is the path for code — scripts, backends, automations. If you want an AI assistant to use Vocal Video for you, connect it over MCP instead: Connect Claude, Connect ChatGPT, or Other MCP clients. Unsure? MCP or API key?

The Vocal Video API is tool-shaped: every endpoint is a single POST /api/v2/tools/{name} whose JSON body is the tool's input. The same tools power the in-app AI assistant and the MCP server, so behavior is identical across all three surfaces. This guide gets you from zero to your first read and write call.

1. Get an API key

In the app, go to Settings → API keys and create a key. Keys carry a scope:

• read — may call read-only tools (anything prefixed get_ / list_).
• write — may call any tool, read or write.

Copy the key somewhere safe; it's shown once. API access must be enabled for your account.

2. Make your first call (read)

Pass the key as a bearer token. Here's a read call that lists your storyboards:

curl https://vocalvideo.com/api/v2/tools/list_storyboards \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 5 }'

Every response wraps the tool's output in a consistent envelope:

{
  "tool": "list_storyboards",
  "result": { "storyboards": [] }
}

The exact input each tool accepts — required fields, types — is in the API Reference. The request body is the tool's input_schema.

3. Make a write call

With a write-scoped key, create a storyboard:

curl https://vocalvideo.com/api/v2/tools/create_storyboard \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer stories — Q3" }'

A read-scoped key calling a write tool gets back 403 forbidden_scope — see Authentication for the scope rules.

What's next

• Authentication — keys, scopes, and errors in depth.
• API Reference — every tool, with its input schema and a live request console.
• MCP reference — the same tools over MCP, for clients you configure yourself.