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/{type}      # generic CRUD: flow, environment, connection,
                                       # cache-policy, folio, skill, template, script,
                                       # var-set, team, mapping, annotation, ...
/api/v1/{branch}/flows/...             # bespoke verbs: invoke, validate, preview
/api/v1/{branch}/invocations/...
/api/v1/{branch}/environments/...
/api/v1/{branch}/connections/...
/api/v1/{branch}/cicd/...              # validation, packaging, sync invocation
/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/{type}      # user, api-key, secret, backup, branch,
                                       # share, invocation, config-section, ...
/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.

Invoking a flow

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

Tracing data ships in X-Zenvara-{Operator,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
`invoke-flow`	Run a flow with typed parameters.
`invoke-operator-action`	Invoke a single operator action directly.
`read-entity` / `list-entities`	Read and list any entity (with `filter` support, e.g. folio/skill/template `query` search).
`set-secret`	Write a secret.
`add-tag` / `set-annotation`	Manage governance annotations.
`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, invocations:///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, error-body hint conventions) are detailed in the platform’s api-url-rules reference.