HTTP API surfaces and request conventions

HTTP API surfaces and request conventions

Viat has a management API for platform/project administration and a caller API for published application interfaces. They do not accept interchangeable identities. The CLI and console use management APIs; viat call without --console targets the caller API.

Paths below are relative to your instance base URL, including an operator-configured reverse-proxy/base-path prefix. Do not add /ui to the API base. Use HTTPS outside a trusted local fixture and keep credentials out of URLs, source files and shared transcripts.

Select the right surface

Surface	Representative path	Authentication and meaning
Process probes	/healthz, /readyz	Deliberately unauthenticated and activation-exempt. A healthy process is not proof of license validity or runnable scripts.
Platform login/session	/auth/login, /auth/refresh, /auth/sessions	Platform account and the operation’s session/MFA rules; not project end-user login.
Platform administration	/users, /license, /admin/...	Route-specific platform role/session rules.
Project management	/projects/{slug}/...	Platform authentication plus membership and the operation’s effective project role/PAT constraints.
Published application route	/p/{slug}/{path}	The published endpoint authorizers/gates, not an automatic management login.
Built-in project identity/file/run routes	/p/{slug}/auth/..., /_token, /_files/..., /_runs/... beneath the project prefix	Separate documented caller protocols and permissions; these names are reserved platform paths.
Overview reader	/projects/{slug}/overview	Normal management access or the narrowly scoped per-login vso_ reader. That token does not authorize adjacent management routes.

Management authentication, endpoint authentication, HTTP endpoints and error handling define the respective contracts. Do not infer a route’s role merely because its HTTP method is GET.

Make a management call without copying tokens

After completing platform login, use the CLI’s ordinary refresh-aware session:

viat call --console --method GET /version
viat call --console --method GET /projects

The command prints status then body, rather than only JSON. /version returns a JSON object such as {"version":"1.1.0"}; /projects returns the projects visible to the platform identity. These reads do not publish or execute scripts. A project-confined PAT cannot be assumed to authorize global /projects; use its known project and permitted routes instead.

An explicit project-create request, only when you intend to create a disposable project with an unused slug, is:

viat call --console --method POST /projects --body '{"slug":"api-docs-lab","name":"API Docs Lab"}'

Both slug and name are required strings. The response is the created project representation, including server-generated identity/state, not just the submitted object. Existing slugs conflict. Inspect the response and project rules before continuing. This example is source-derived; unlike the independently tested first-endpoint walkthrough, this exact invocation is not an executed response record.

For a direct HTTP client, provide the appropriate bearer in Authorization: Bearer ... and JSON Content-Type when the route expects JSON. The platform access/refresh pair has rotation semantics; do not replay a consumed refresh credential or silently replace a failed session with an unrelated account. The full lifecycle is in the authentication reference.

Names, folders, methods and payloads

Concern	Rule
Project identity	{slug} is the project slug, not its display name or UUID.
Asset identity	A script/resource/workflow in a folder uses its bare {name} plus ?folder=... on the relevant management route. CLI qualified names such as shared/lookup are a convenience, not necessarily literal path segments.
Encoding	Percent-encode each dynamic path segment and query value. Do not concatenate a resource name containing ?/# into an unescaped URL.
Endpoint identity	Management actions use the endpoint node UUID. Caller requests use the published method/path, not that UUID.
Create/update	POST, PUT and PATCH semantics vary by object. Do not assume PUT always means replace or PATCH always means JSON Merge Patch; use the feature’s field table.
Omitted/null/empty	These may mean preserve, inherit, clear or reject depending on the field. Empty arrays can be explicit policy choices.
Secrets	Ordinary resource representations return summaries/redaction, not secret recovery. Do not send returned mask placeholders back as new secrets.
Pagination	There is no universal envelope. Execution queries have items/next_before; other lists, capped results and cursors differ.
Tests	A test route may execute current code or contact a resource. The word test does not make it a dry-run.

For example, a qualified script read addresses the folder explicitly:

viat call --console --method GET '/projects/hello-lab/scripts/lookup?folder=shared'

It requires that project/script and the route’s read permission. The exact case-sensitive path spellings also matter: scripts use /{name}/test-run, while workflows use /{name}/test_run. Do not normalize hyphens/underscores by guesswork.

Feature-to-API index

These are route families, not a claim that every listed prefix supports every CRUD method. Follow the owning reference for complete bodies, responses, conditional fields, errors, permissions and side effects.

Capability	Management route family	Owning reference
Project settings/members	/projects/{slug}, /members, /members/{email}	Settings, collaboration
Resource configuration/Test/schema	/projects/{slug}/resources, /{name}, /{name}/test, /{name}/schema/refresh	20 resource references
Database migrations	.../resources/{name}/migrations	CLI database operations
Managed files and business audit	.../resources/{name}/files, .../audit, .../audit/export	Storage, audit
Scripts, environments, artifacts	/projects/{slug}/scripts, /{name}/env, /build, /artifact, /binary	Script context, runtime, CLI scripts
Workflows	/projects/{slug}/workflows, /{name}/validate, /{name}/test_run	Workflow reference
Endpoint/tree contracts	/projects/{slug}/endpoints, /trees	HTTP, CRUD, inbound WebSocket
Publication	.../endpoints/{id}/publish, /unpublish; /projects/{slug}/publish/plan, /apply, /rollback, /history	Snapshots, rollback
Schedules	/projects/{slug}/schedules, /{name}/pause, /resume, /trigger, /runs	Schedules
Filesystem, RabbitMQ, outbound WebSocket	/projects/{slug}/watches, /queue-triggers, /ws-triggers	Watches, queues, WS subscriptions
Chat accounts/identity/triggers	/projects/{slug}/im/accounts, /identities, /bind-links, /triggers	Personal WeChat and other provider pages
Authorization model	/projects/{slug}/authz, /types, /rules, /subject-attrs, /lint	Authorization
Observability	/projects/{slug}/overview, /executions, /async-runs, /audit	Runs, logs, audit
Published project OpenAPI	/projects/{slug}/openapi.json	Section below

Within a cell, a short suffix is relative to the family immediately preceding it, not a global route. An API capability does not imply a corresponding CLI command or MCP tool; the CLI and MCP inventories are explicit.

Export the published application’s OpenAPI

An authenticated project member can request:

viat call --console --method GET /projects/hello-lab/openapi.json

The document uses OpenAPI 3.1.0 and is built from active published snapshots, plus authorizer metadata. Its servers entry points to the instance base path plus /p/{slug}. Draft edits do not automatically change the public contract represented by active snapshots. The generated info.version is not the running server release identifier; use /version for that.

This export describes the project’s published caller interfaces, not a complete management API specification. It is intentionally a member-authenticated management route, not a public /p/{slug}/_openapi.json route. Do not invent the latter. A member can review and share a sanitized contract with an integrator; the document itself does not grant a caller credential or waive authz gates. Inspect descriptions for streaming, async, proxy/CRUD and schema limitations before assuming a client generator can encode every runtime rule.

Verification and safe cleanup

For integrations, start with reads, record actual object IDs, then perform only explicitly intended mutations in an isolated namespace. Verify both response status and operation-specific fields. Publication does not imply all builds are ready; async acceptance does not imply completion; resource Test can return HTTP 200 with ok: false. Errors and result boundaries provides the shared decision rules.

Remove only objects created by the integration after stopping their triggers and resolving dependencies. Exported API contracts/logs may expose private routes or data even without secrets; store them privately and remove disposable copies deliberately. This page does not execute its management examples or authorize production cleanup.

Verification basis

Pinned source 03751a67: API route assembly in crates/viat-api/src/lib.rs, dto.rs, owning handlers, handlers/openapi.rs/openapi.rs, and CLI commands/{endpoint,script}.rs. Resource/language/CLI/MCP contracts are pinned separately; they are not passed off as a full generated management OpenAPI.