API overview

The Vupt cloud API is a REST surface at /v1/.... It powers cloud sync (Pro+), team collaboration (Team+), and admin operations (Business+). The desktop app is the primary client; third-party clients can talk to it directly using the OpenAPI 3.1 specification.

Base URL

Deployment	Base URL
Vupt SaaS	https://api.vupt.dev/v1
Self-hosted	https://{your-host}/v1

Auth

Requests are authenticated via a Bearer token issued by Clerk:

Authorization: Bearer <token>

Tokens have a 1-hour TTL and refresh via the standard OAuth refresh flow. The desktop app handles refresh automatically.

Conventions

• Errors: RFC 9457 Problem Details (application/problem+json)
• Pagination: cursor-based via ?cursor=<opaque> and Link headers
• Idempotency: all writes accept Idempotency-Key: <ulid> headers
• Versioning: the /v1/ prefix is the contract; breaking changes ship under /v2/ only

Example: list Squads

curl -s https://api.vupt.dev/v1/squads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "data": [
    { "id": "01H...", "goal": "Add /healthz", "state": "merged", "created_at": "2026-05-15T10:00:00Z" }
  ],
  "next_cursor": null
}

OpenAPI specification

The full machine-readable spec lives at /v1/openapi.json on every deployment. Use it to generate typed clients for any language (the official TypeScript client is auto-generated from this spec).

Cloud MCP (Team+)

The Cloud MCP server is a separate surface — it speaks MCP over SSE, not REST. See Cloud MCP for details.