Skip to main content

HTTP API

versionx-web exposes a small axum HTTP surface on loopback. The same capability set as the JSON-RPC daemon, but HTTP-shaped for browser-based tooling and language-agnostic automation.

Status​

  • Loopback only in 1.0. Binds 127.0.0.1:<port>.
  • No auth. Trust is the OS user + loopback.
  • Remote + bearer auth is a 1.2+ roadmap item.

Starting​

Automatic when the daemon runs:

versionx daemon start      # also starts the HTTP server on a random port
versionx daemon status     # prints the URL (e.g., http://127.0.0.1:47821)

Manual:

versionx web --port 7777

Endpoints​

MethodPathPurpose
GET/api/v1/reposList workspaces known to the daemon.
GET/api/v1/repos/{id}Workspace detail.
POST/api/v1/repos/{id}/syncRun a sync (returns plan + apply result).
GET/api/v1/plansList plans (recent, active).
GET/api/v1/plans/{id}One plan's detail.
POST/api/v1/plans/{id}/applyApply a plan.
GET/api/v1/eventsSSE stream of daemon events.
GET/api/v1/policiesActive policy set.
GET/api/v1/openapi.jsonOpenAPI 3 spec (via aide).
GET/docsScalar UI against the OpenAPI spec.

SSE event stream​

curl http://127.0.0.1:47821/api/v1/events

Emits events matching the event taxonomy. One data: line per event, JSON body.

OpenAPI​

The spec is auto-generated from the axum routes and their types via aide. View the interactive reference at /docs (served by the daemon), or fetch JSON:

curl http://127.0.0.1:47821/api/v1/openapi.json | jq

Using the spec​

Generate a typed client in your language of choice:

# TypeScript
npx openapi-typescript http://127.0.0.1:47821/api/v1/openapi.json --output versionx.ts

# Python
datamodel-codegen --url http://127.0.0.1:47821/api/v1/openapi.json --output versionx_client.py

Example: drive a sync from Node​

const res = await fetch(`http://127.0.0.1:${port}/api/v1/repos/${id}/sync`, {
  method: "POST",
});
const result = await res.json();
console.log(result.plan_id, result.outcome);

See also​