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:
HTTPCopyGET /.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
pageandpageSizequery parameters. See Pagination and errors. - Errors use problem details (
application/problem+json) with a machine-readablecode, and every response carries anX-Correlation-IDheader you can quote to an administrator. - Every
POST,PUT,PATCHandDELETEin a tenant accepts anIdempotency-Keyheader (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 Forbiddenwith the codepermission_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#
- Authentication: create a personal access token and call the API.
- Pagination and errors: read lists and handle failures.
- Key endpoints: start jobs, add queue items and manage triggers.
- Webhooks: receive signed events when jobs change state.
The API surfaces
How URLs are structured
Discovery document
Requests and responses
Interactive reference
Permissions apply to every call
Rate limits
Next steps