API Surfaces

Zenvara exposes the same typed entities through three surfaces — REST, MCP, and GraphQL — plus the zen CLI, which forwards to REST. The equivalence is deliberate: a flow is callable identically from a human, a script, and an AI agent.

REST — two URL families

All REST lives under /api/v1/, split into two families.

Branch-scoped — `/api/v1/{branch}/...`

Operates within a versioning branch. Includes a generic entity CRUD surface plus bespoke verbs:

/api/v1/{branch}/entities/{op}/{entity}   # generic CRUD. {op} is "platform" for a platform
                                           # entity (flow, environment, connection,
                                           # cache-policy, folio, skill, template, script,
                                           # store, team, mapping, annotation, ...), or the
                                           # owning connector's name for a connector-backed
                                           # entity, e.g. entities/platform/flow.
/api/v1/{branch}/flows/...             # bespoke verbs: runs, serve, context
/api/v1/{branch}/runs/...
/api/v1/{branch}/environments/...
/api/v1/{branch}/connections/...
/api/v1/{branch}/cicd/...              # validation, packaging, sync run
/api/v1/{branch}/versions/...          # history, diff, revert

The branch segment is required. The live alias resolves to production on Git-disabled deployments. The local segment activates the filesystem overlay (/api/v1/local/...) when LocalOverlay.Enabled: true.

Platform-scoped — `/api/v1/platform/...`

Cross-branch, installation-level entities and verbs:

/api/v1/platform/entities/{op}/{entity}   # generic CRUD, {op} is "platform" for platform-
                                           # scoped entities: user, api-key, secret, backup,
                                           # branch, share, run, config-section, ...
                                           # e.g. entities/platform/secret.
/api/v1/platform/connectors/{provider}/{name}/invoke   # direct connector-action invoke
                                           # (the axis-2 `on=` binding — see below)
/api/v1/platform/auth/...
/api/v1/platform/users/...
/api/v1/platform/backups/...
/api/v1/platform/branches/...
/api/v1/platform/diagnostics
/api/v1/platform/logs
/api/v1/platform/git/sync             # HMAC-triggered config sync
/api/v1/platform/support              # support + feature requests

platform is a reserved prefix.

Running a flow

curl -X POST http://localhost:5000/api/v1/live/flows/hello/runs \
  -H "Content-Type: application/json" \
  -d '{"message":"Hi there"}'

Tracing data ships in X-Zenvara-{Connector,Entity,Duration-Ms} response headers.

MCP — for AI assistants

The Model Context Protocol server lets AI assistants (Claude Code, VS Code, any MCP host) discover and call tools against your installation. Key tools:

Tool	Does
`run-flow`	Run a flow with typed parameters.
`invoke-connector-action`	Invoke a single connector action directly.
`read-entity` / `list-entities`	Read and list any entity (with `filter` support, e.g. folio/skill/template `query` search).
`create-entity` / `update-entity`	Write any entity — including secrets (`entity: secret`) and governance annotations (`entity: annotation`).
`submit-support-request` / `submit-feature-request`	File to the Zenvara team.

Read-resource URIs provide search and history: folios:///search/{q}, skills:///search/{q}, versions:///{type}/{name}/history, runs:///introspection[/{id}], docs:///bindings/<provider>/<name>.

GraphQL

A resolver surface for typed queries against the same entities, mapping the same error codes to GraphQL error codes (see Error Catalog).

Connector/entity binding — `on=`

Invoking a connector directly, or reading/writing an entity, over MCP, REST, or GraphQL, binds to an environment with an on parameter. This is the connector/entity invoke on — one of four things spelled on; see that page for how it differs from a flow-YAML step’s on:, the run-level environment= parameter, and a trigger’s on:.

on=<env> resolves the environment’s single connection of the connector’s type. on=<env>/<alias> pins a specific connection alias — the split is on the first / — and is required when the environment binds more than one connection of that type.

Surface	Carriers	Where `on` goes
MCP	`invoke-connector-action`, `read-connector-action`, `read-entity`, `list-entities`, `create-entity`, `create-entities`, `update-entity`, `update-entities`, `delete-entity`, `delete-entities`, `invoke-command`, `sync-entities`	Tool argument `on` — optional
MCP	`me`	Tool argument `on` — required
REST — connector invoke	`POST /api/v1/platform/connectors/{provider}/{name}/invoke`	JSON body field `on`
REST — entity CRUD	the `entities/{op}/{entity}` routes	Query string `?on=`
GraphQL	`InvokeConnectorInput.on` and its sibling entity input types	Input field `on`

sync-entities is the one carrier that narrows what on= accepts: it takes on=<env> but not the qualified on=<env>/<alias> form. The sync engine binds by the target connector’s type within the environment, so an alias has nothing to bind to — a qualified value is rejected with a validation error rather than being silently narrowed to its environment half.

on= is not always required. A Pure-kind connector, or one with no required config, can invoke bare; so can any connector when a config= override (which itself requires environment:write) covers every required field.

To discover candidates, call read-resource(uri="docs:///bindings/<provider>/<name>") — it lists environment names only, never aliases. For the full picture, list environments with list-entities using=platform entity=environment, then read a specific environment’s aliases with list-entities entity=environment.

on= never names a connection directly — that’s unrepresentable by design (ZEN-1446). If a system needs a fixed target, give it its own environment instead of reaching for a connection name.

Choosing a surface

Caller	Surface
Human at a terminal	`zen` CLI
Script / CI pipeline	REST (`X-API-Key`)
AI assistant / agent	MCP
Typed app integration	GraphQL or REST

URL family rules (/{branch}/ vs /platform/, the live alias) are covered above; response conventions (error shapes, hint fields) follow the same pattern across both families.