VOCION
Get a demo
docs/build/api.md

REST API

Every route is under https://<host>/api/v1, scoped to one workspace, and governed by the same permission model as a person. The full route list is in API routes; the machine-readable spec is GET /api/v1/openapi (OpenAPI 3.0.3), with Swagger UI at /api-docs.

Authentication

curl https://<host>/api/v1/workflows -H "Authorization: Bearer vcn_live_..."
  • Issue a token under Developers (admins), or npm run tokens:issue --workspace @vocion/core. The plaintext is shown once; an admin can reveal it again later.
  • A token belongs to one workspace and carries a role (admin or member) and an optional expiry. Revoke it under Developers or with tokens:revoke.
  • If an Authorization header is present, it is the credential: a bad token is a 401, never a fallback to a browser session.
  • Tokens issued through OAuth (Claude, ChatGPT) are ordinary vcn_live_ tokens with role member and a 30-day expiry.

Errors look like {"error": {"code", "message", "details"}}. Lists take limit (default 50, max 200) and offset.

Start a workflow and follow it

# start
curl -X POST https://<host>/api/v1/workflows/send-followup \
  -H "Authorization: Bearer $VOCION_TOKEN" -H 'Content-Type: application/json' \
  -d '{"input": {"dealId": "DL-42"}}'

# poll: status, step results, workspace commit, error
curl https://<host>/api/v1/runs/<runId> -H "Authorization: Bearer $VOCION_TOKEN"

For live updates, GET /api/v1/live streams change notices as Server-Sent Events.

Decide what waits on a person

curl https://<host>/api/v1/reviews -H "Authorization: Bearer $VOCION_TOKEN"

curl -X POST https://<host>/api/v1/reviews/decide \
  -H "Authorization: Bearer $VOCION_TOKEN" -H 'Content-Type: application/json' \
  -d '{"kind": "workflow", "id": "<runId>", "action": "approve"}'

kind is workflow, mission or action; action is approve, reject or done, with optional reason, learn and editedInput (becomes the resumed step's input). Asks use POST /api/v1/asks/{id}/decide. Deciding needs the approve capability.

Cancel a mission run with POST /api/v1/mission-runs/{id}/cancel. Workflow runs are cancelled over MCP (workflow_run_cancel).

Send events in

curl -X POST https://<host>/api/v1/events \
  -H "Authorization: Bearer $VOCION_TOKEN" -H 'Content-Type: application/json' \
  -d '{"type": "deal.stage_changed", "payload": {"dealId": "DL-42"}, "dedupeKey": "DL-42:proposal"}'

The response lists the automations it triggered: {eventId, deduped, triggered: [{slug, runId}]}. Vocion sends no outbound webhooks; poll, or use /live.

Push records and sources

  • POST /api/v1/objects — upsert a record by external key
  • POST /api/v1/sources — create or replace a source; POST /api/v1/sources/{slug}/sync — sync it now (both need manage_sources)