Verception API docs

What can the Verception API do?

The Verception REST API does each action of the dashboard: projects, deployments, environment variables, domains, stores, Git, the project chat, sandboxes, and AI models. The dashboard uses the same endpoints.

• Base URL: https://vercel-on.vercel.app/api/v1
• Request and response bodies are JSON. Timestamps are ISO 8601 strings in UTC
• OpenAPI 3.1 document: /openapi.json, with an operation ID, a description, and a scope for each operation
• MCP server: https://vercel-on.vercel.app/mcp, with one tool for each operation
• Agent index: /llms.txt. Each public page also has a Markdown copy, such as /docs.md

When should an agent use Verception?

Use Verception when a task needs one of these jobs:

• Put a folder, generated code, or a GitHub repository on a public HTTPS URL
• Get a preview URL for a change, then promote it to production or roll it back
• Run code that you do not trust in an isolated Linux sandbox, and open its ports on a public URL
• Call AI models from many providers in the OpenAI format with one API key
• Serve an app on a custom subdomain with automatic HTTPS

Verception is a free experiment with small limits: 5 projects and 50 deployments a day for each account. Use a different platform for large production traffic, apex domains, or data that must stay in one region.

How do I start?

• Free tier: every account is free while the experiment runs. No credit card
• Self-serve sign-up: create an account at /signup with an email, a username, and a password
• Self-serve keys: create an API key in the account settings, or with POST /v1/user/api-keys. An agent can also get a key with the OAuth sign-in
• Test environment: each preview deployment is a test copy of an app, and each sandbox is an isolated machine that you can delete at any time

How do I authenticate?

Send an API key or an OAuth access token in the Authorization header. A request with no valid token gets 401 with a WWW-Authenticate header that names the OAuth metadata.

curl https://vercel-on.vercel.app/api/v1/user \
  -H "Authorization: Bearer $VERCEPTION_API_KEY"

Each key and each token has scopes. A request without the scope that it needs gets 403 insufficient_scope.

OAuth 2.0: Verception is an authorization server for the authorization code flow with PKCE (S256). A client registers itself with dynamic client registration, so it needs no client secret. An access token works for 30 days, and the user can revoke it in the account settings.

How do I deploy a static site?

Create a project, upload each file by its SHA-1, then create a deployment from a manifest. The API answers 400 missing_files with the SHA-1 of each file that it does not have yet.

API=https://vercel-on.vercel.app/api/v1
AUTH="Authorization: Bearer $VERCEPTION_API_KEY"

curl -X POST $API/projects -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"name":"hello"}'

echo "<h1>Hello</h1>" > index.html
SHA=$(shasum index.html | cut -d" " -f1)
curl -X POST $API/files -H "$AUTH" -H "x-sha: $SHA" \
  -H "Content-Type: application/octet-stream" --data-binary @index.html

curl -X POST $API/deployments -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"projectId\":\"proj_...\",\"target\":\"production\",\"files\":[{\"file\":\"index.html\",\"sha\":\"$SHA\",\"size\":15}]}"

Poll GET /v1/deployments/:id until readyState is READY or ERROR. Read the build log with GET /v1/deployments/:id/events.

What does an error look like?

Every error is JSON with a stable code and a message that tells what to do next. A 500 or a 502 also has a reference for a support request. An unknown path under /api also returns a JSON 404.

{ "error": { "code": "not_found", "message": "Project not found." } }

Which limits apply?

Lists return the resource name as the key, such as { "projects": [...] }. The limits keep each list short, so lists have no pages.

How do I connect an MCP client?

Add https://vercel-on.vercel.app/mcp as a remote MCP server with the Streamable HTTP transport. The client lists the tools with no token. A tool call needs a token: the client gets one with the OAuth sign-in, or you send an API key as Authorization: Bearer <key>. Each tool is one operation of the API, with the same name as its operation ID.

{
  "mcpServers": {
    "verception": {
      "url": "https://vercel-on.vercel.app/mcp"
    }
  }
}

How does the API change?

Every path starts with /v1. Verception is an experiment, so a change can also change /v1. The OpenAPI document always shows the current API.

Which endpoints does the API have?

Each path follows the base URL. The scope column shows the scope that a key or a token needs.