REST API

The hosted base origin is:

https://app.vibecms.dev

Self-hosted installations use their API and dashboard Worker origin.

All current integration routes are under /api/v1. MCP exposes 42 tools and REST exposes 41 operations for site settings and theme, voice and signup form, redirects, tags, analytics, posts and versions, private preview links, scheduling, formatting guidance, assets, activity, and the vibecms agent skills — posts.search shares the GET /api/v1/posts?search= list route rather than having its own endpoint. See scopes and tools for the required scope of each operation; the two skills operations need no scope.

Example

curl https://app.vibecms.dev/api/v1/site \
  -H "Authorization: Bearer vc_..."

Source of truth

• OpenAPI 3.1 JSON
• Interactive Scalar reference

Use this guide for authentication, concurrency, and workflow semantics. Use the generated reference for request and response fields.

MCP transport

The MCP endpoint is POST /mcp on the same origin — stateless JSON-RPC 2.0 over HTTP, no session handshake. Legacy clients can still send initialize; newer clients should use server/discover with protocol version 2026-07-28.

Authenticate every MCP request with an agent key or OAuth access token, including initialize, tools/list, server/discover and legacy notifications/initialized. Missing credentials return HTTP 401 / JSON-RPC -32001 with a bearer challenge pointing to public OAuth metadata, so OAuth-capable clients can offer sign-in up front. Invalid bearers retain the invalid_token challenge. API-key clients keep using their existing bearer key.

tools/list is scope-filtered and privately cached. server/discover also requires authentication, even though its successful response declares cacheScope: "public" because it is identical across principals; response caching is not an anonymous-access exemption. OAuth metadata, trusted CIMD/public-client registration, the static server card and HTTP agent skill files remain public.

Modern-protocol requests must mirror the request into headers or they fail even with a valid key:

• MCP-Protocol-Version: 2026-07-28 must match _meta["io.modelcontextprotocol/protocolVersion"]
• Mcp-Method must match the JSON-RPC method
• Mcp-Name must match the tool name for tools/call
• _meta["io.modelcontextprotocol/clientCapabilities"] must be present

Errors come in two shapes — a top-level JSON-RPC error for protocol and authentication failures, and a tool result with isError: true for operation failures. See conflicts and recovery.