Skip to content

v2-command-reference.md

Latest commit

 

History

History
121 lines (95 loc) · 5.72 KB

v2-command-reference.md

File metadata and controls

121 lines (95 loc) · 5.72 KB
Raw

Platform API v2 Command Reference

API v1 remains the default command surface. API v2 resources use the explicit v0 v2 namespace because chat IDs are not interchangeable between generations.

Diagnostics and schema

Command Trust Purpose
v0 v2 doctor T0 Verify API access, bundled schema coverage, chats, MCP, webhooks, and optional preview-host capability.
v0 v2 schema [operation-id] T0 List or inspect the 41 pinned v2 OpenAPI operations offline.

Chats and generation

Command Trust Purpose
v0 v2 chat list T0 List chats with cursor, author, Vercel project, and metadata filters.
v0 v2 chat show <chat-id> T0 Show one v2 chat.
v0 v2 chat create <message> T1 Create using sync, --async, or --stream.
v0 v2 chat init <source> T1 Import local text files, a ZIP URL, local ZIP with consent, or a GitHub repository.
v0 v2 chat update <chat-id> T1 Update title, privacy, or metadata.
v0 v2 chat duplicate <chat-id> T1 Duplicate a chat with explicit privacy.
v0 v2 chat delete <chat-id> T2 Delete a chat after confirmation.
v0 v2 chat restore <chat-id> <message-id> T2 Restore files associated with an assistant message.
v0 v2 chat watch <chat-id> T0 Resume and follow the active stream.
v0 v2 chat wait <chat-id> <message-id> T0 Poll an async generation until it finishes.
v0 v2 chat preview <chat-id> T0 Get preview URL, token, and expiry.
v0 v2 chat connect-status <chat-id> <request-id> T0 Read Vercel Connect setup status.
v0 v2 chat vercel-project <chat-id> T2 Create and attach a Vercel project.
v0 v2 chat deploy <chat-id> T2 Deploy the chat to Vercel.

Generation flags shared by chat creation and message sending:

--model v0-mini|v0-pro|v0-max|v0-max-fast
--image-generations
--system <prompt>
--attachment <url-or-path>
--mcp-server <id>
--skill remote:<id>
--skill memory:user:<name>
--skill memory:team:<name>
--skill project:<name>
--upload-public

Messages and tasks

Command Trust Purpose
v0 v2 msg list <chat-id> T0 List messages with pagination.
v0 v2 msg show <chat-id> <message-id> T0 Show ordered parts plus token and credit usage.
v0 v2 msg send <chat-id> <message> T1 Send using sync, --async, or --stream.
v0 v2 msg wait <chat-id> <message-id> T0 Poll an async message until it finishes.
v0 v2 msg stop <chat-id> <message-id> T1 Stop an in-flight message.
v0 v2 msg resolve <chat-id> --task <json> T2 or T3 Resolve questions, plans, integrations, Connect setup, or confirmed permissions.

Confirmed-permission tasks are T3. Mint an intent bound to the exact {chatId, task} payload and pass it through --confirm.

Current files and migration

Command Trust Purpose
v0 v2 files list <chat-id> T0 List current files without printing contents.
v0 v2 files show <chat-id> <path> T0 Print one text or binary file.
v0 v2 files download <chat-id> --out <zip> T0 Download current files as a ZIP archive.
v0 v2 files apply <chat-id> T2 Apply repeated --file project=local and --delete project changes.
v0 v2 migrate <v1-chat-id> <v1-version-id> T1 Create a new v2 chat from one selected v1 version and preserve source IDs in metadata.

Local attachments and ZIPs are never uploaded implicitly. Use --upload-public only when permanent Catbox publication is acceptable. Local source imports use at most 20 inline text files before requiring this consent.

Webhooks

Command Trust Purpose
v0 v2 hook list T0 List webhooks.
v0 v2 hook show <hook-id> T0 Show one webhook.
v0 v2 hook create --name <name> --url <url> --event <event> T1 Create a webhook, optionally scoped with --chat.
v0 v2 hook update <hook-id> T2 Update name, URL, or repeated events.
v0 v2 hook delete <hook-id> T3 Delete using an intent token bound to {hookId}.

Supported events are chat.created, chat.updated, chat.deleted, message.created, message.updated, message.deleted, and message.finished.

MCP servers

Command Trust Purpose
v0 v2 mcp list T0 List MCP server configurations.
v0 v2 mcp show <server-id> T0 Show one MCP server.
v0 v2 mcp create T1 Create a server with name, URL, scope, enabled state, description, and auth JSON.
v0 v2 mcp update <server-id> T2 Update configuration after confirmation.
v0 v2 mcp delete <server-id> T3 Delete using an intent token bound to {mcpServerId}.

Create example:

v0 v2 mcp create \
  --name Context7 \
  --url https://mcp.context7.com/mcp \
  --scope user \
  --auth '{"type":"none"}' \
  --json

Trusted preview hosts

Command Trust Purpose
v0 v2 settings preview-hosts get T0 Get trusted hosts or return a capability-unavailable result.
v0 v2 settings preview-hosts set --host <pattern> T2 Replace trusted host patterns after confirmation.

Preview-host settings require an eligible team or organization scope. A 403 capability response is reported as unavailable rather than making v0 v2 doctor unhealthy.

Environment and output

Variable Purpose
V0_API_KEY Authenticate both generations.
V0_BASE_URL Override the v1 base URL.
V0_V2_BASE_URL Override the v2 base URL.

Success uses { "data": ... }. Non-streaming failures use { "error": ... }. JSON streaming uses NDJSON frames and finishes with an envelope event.