API overview

The HTTP surfaces the Orchestrator exposes, who each one is for, and how the URLs are shaped.

Everything you can do in the Orchestrator web app goes through the same REST API that the web app itself calls. You can use that API to start jobs from another system, load work into queues, manage machines and packages from a pipeline, or build reports. This page explains the different API surfaces, how the URLs are structured and where to go next.

The API surfaces#

The Orchestrator serves several APIs from one origin (the address in VELOPHEX_PUBLIC_BASE_URL, for example https://orchestrator.example.com). Each one has its own audience and its own credential.

Surface Base path Who calls it Credential
Management API /api/v1/... People, scripts, CI pipelines, integrations Web session cookie, personal access token (vpx_pat_…), or an external application's token
Package feed /api/v1/tenants/{tenantId}/feed/v3/index.json Studio, the Python CLI, dotnet nuget, Robots Personal access token, or the Robot's feed token (read only)
Runtime API /api/v1/runtime/... A running automation (workflow activities or the Python SDK) Per-job execution token (vpx_rt_…), issued automatically
Robot API /api/v1/robot/... and /api/v1/oauth/token The Robot service Machine access token, obtained with the machine's key pair (private_key_jwt)
Webhooks Outbound from the Orchestrator Your HTTPS endpoint HMAC signature you verify
Health /health/live, /health/ready Load balancers, container orchestrators, monitoring None

As an integrator you normally use only the management API, the package feed and webhooks. The runtime API and the Robot API are used by VeloPhex components on your behalf; they are listed here so that you recognize them in logs and firewall rules.

How URLs are structured#

Most resources belong to a tenant, and many belong to a workspace inside that tenant. The URL says so explicitly:

TextCopy
/api/v1/tenants/{tenantId}/...                              tenant-level resources
/api/v1/tenants/{tenantId}/workspaces/{workspaceId}/...     workspace-level resources
/api/v1/platform/...                                        platform administration
/api/v1/me/...                                              the signed-in user

Tenant-level resources include machines, packages, roles, role assignments, credential stores, settings, webhooks and the audit log. Workspace-level resources include automations (the API name for processes), jobs, queues, queue items, triggers and assets.

Identifiers are GUIDs. Many resources also carry a read-only integer number for display, and a few have by-number/{number} lookup routes, but you should store and send the GUID.

Find your tenant id

The tenant id is shown on the tenant's settings page. You can also resolve it from a tenant name or slug without signing in, using the discovery document described below.

Discovery document#

Clients that need to configure themselves (the Python CLI, Studio, scripts) can read an anonymous discovery document:

HTTPCopy
GET /.well-known/velophex-orchestrator?tenant=acme HTTP/1.1
Host: orchestrator.example.com

It returns the public base URL, the API base URL, the browser sign-in endpoints (/oauth/authorize, /api/v1/oauth/token, /api/v1/oauth/revoke), the device sign-in endpoints (/api/v1/device/code and /api/v1/device/token), the runtime API base, the protocol versions the server supports and the permission preset used for SDK tokens. When you pass ?tenant=, it also returns that tenant's id, number and name, or null if the name does not resolve.

Requests and responses#

  • Request and response bodies are JSON with camelCase property names, for example automationId, pageSize.
  • Timestamps are ISO 8601 with an offset, and are UTC unless stated otherwise.
  • Lists are paged with page and pageSize query parameters. See Pagination and errors.
  • Errors use problem details (application/problem+json) with a machine-readable code, and every response carries an X-Correlation-ID header you can quote to an administrator.
  • Every POST, PUT, PATCH and DELETE in a tenant accepts an Idempotency-Key header (up to 100 characters), so you can retry safely. Starting a job is the most important case; see Pagination and errors.

Interactive reference#

The API is described with OpenAPI, and an interactive reference (Scalar) is mapped at /scalar when the Orchestrator runs in the Development environment. Production deployments do not serve it. To explore the API, run an evaluation stack or a development instance and open /scalar there, or read the endpoint summaries in Key endpoints.

Permissions apply to every call#

Every endpoint requires an authenticated caller unless it is explicitly anonymous (sign-in, discovery, health). Each call is then checked against the caller's permissions in that tenant and workspace. A personal access token never carries more permissions than the person who created it, and you can create one with a smaller set.

  • If you have no access to the tenant or workspace in the URL at all, the API answers 404 Not Found, so it does not confirm that the tenant or workspace exists.
  • If you can see it but lack the permission for this call, the API answers 403 Forbidden with the code permission_required, the permission you need (requiredPermission) and where you need it (scope).

See RBAC and permissions.

Rate limits#

A per-IP limit (3,000 requests per minute by default) runs before authentication, and named policies apply to sign-in, device sign-in, Robot traffic, package uploads and feed reads. When you exceed a limit you receive 429 Too Many Requests, usually with a Retry-After header. Back off and retry. Limits are counted in memory per Orchestrator process, so with several API replicas each replica keeps its own count.

Policy Default limit
Per client IP, all requests 3,000 per minute
Sign-in and token polling, per IP 10 per minute
Starting a device sign-in, per IP 5 per minute
Package uploads and pushes, per user 20 per minute
Feed reads, per caller 300 per minute

An operator can change these under the RateLimiting configuration section.

Next steps#

The API surfaces

How URLs are structured

Discovery document

Requests and responses

Interactive reference

Permissions apply to every call

Rate limits

Next steps