API

A tenant-scoped REST API for reading resources, ingesting objects, triggering runs, and polling results. Use this when you have an existing system that should push data into Vocion and/or consume results — without running an agent conversation and without speaking MCP.

What's live today

Read endpoints are callable from any logged-in session or a tenant Bearer token. Tenant Bearer tokens (vcn_live_...) are now live, and the first write-API surface — the unified review queue — ships on them.

Status	Endpoint
✓ live	`GET /api/v1/agents` · `/api/v1/agents/:slug`
✓ live	`GET /api/v1/skills` · `/api/v1/skills/:slug`
✓ live	`GET /api/v1/workflows` · `/api/v1/workflows/:slug`
✓ live	`GET /api/v1/objects/types`
✓ live	`GET /api/v1/runs/:id`
✓ live	`GET /api/v1/reviews` — the pending-review queue
✓ live	`POST /api/v1/reviews/decide` — approve / reject a queued item
✓ live	`vcn_live_...` Bearer tokens → resolve to an authz principal
Phase 2.5	Remaining `POST` / `PATCH` / `DELETE` resource + run endpoints
Phase 2.5	Webhooks + SSE streaming

Authenticate with a tenant Bearer token (server-to-server) or your session cookie (browser) — issued by auth.js after signing in with email + password. Everything is scoped to your active organization. A token doesn't just authenticate: it resolves to a permission principal (role + grants + org scope), so any write it makes runs through the same authorization model and review queue as a human.

When to use the API vs MCP vs A2A

Interface	When	Transport
MCP	You're an LLM-driven agent (Claude, Cursor, Zed) authoring + running inside a developer IDE	stdio (today), HTTP+OAuth (Phase 2)
REST API (this)	You're an external system or backend service that wants typed CRUD + run control	HTTPS + Bearer token
A2A	You're an agent speaking the A2A protocol and want to hand off tasks to a Vocion agent	HTTPS + capability discovery

One workflow can be triggered from any of them; outputs land in the same skill_run / workflow_run tables and surface in the same review queue.

Quickstart

# 1. Create an API token in the dashboard (Admin → API tokens)
export VOCION_TOKEN=vcn_live_...

# 2. List your agents
curl -H "Authorization: Bearer $VOCION_TOKEN" \
  https://your-vocion-install/api/v1/agents

# 3. Push a new object (e.g. a field-notes upload from a mobile app)
curl -X POST -H "Authorization: Bearer $VOCION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Site 4821 inspection","metadata":{"siteId":"4821","inspector":"mtorres"},"content":"..."}' \
  https://your-vocion-install/api/v1/objects/inspection/instances

# 4. Trigger the workflow it feeds
curl -X POST -H "Authorization: Bearer $VOCION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":{"objectId":"obj_123"}}' \
  https://your-vocion-install/api/v1/workflows/inspection_review/runs
# → { "runId": 987, "status": "running" }

# 5. Poll for the result
curl -H "Authorization: Bearer $VOCION_TOKEN" \
  https://your-vocion-install/api/v1/runs/987
# → { "status": "paused", "pausedAt": "review", "reviewUrl": "..." }

Spec

Authentication — token issuing + rotation + scopes
Resources — CRUD on Agent, Skill, Workflow, Object, Source
Runs — triggering + polling + resume
Webhooks — register URL + filter, receive completion events

Principles

Tenant-scoped by default. Every token belongs to one org; every request implicitly scoped to that org. Cross-tenant read/write is not possible.
Same resources everywhere. The API surface mirrors the five concepts (Source, Object, Skill, Workflow, Agent). If you understand the concepts, the API is already familiar.
Idempotency keys on all POST endpoints. Replay-safe.
Versioned under /api/v1. Breaking changes land under /api/v2 with a deprecation window.
OpenAPI 3.1 spec published at /api/v1/openapi.json — generate client SDKs with any tool that speaks OpenAPI.