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/auth/...
/api/v1/platform/users/...
/api/v1/platform/secrets/...
/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}].

GraphQL

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

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.