Key endpoints
The management API routes you use most, with request bodies for starting jobs, loading queues and scheduling triggers.
This page lists the management API routes that integrations use most often, grouped by resource. All paths are relative to your Orchestrator origin, and every call needs a personal access token with the permission shown. For the full picture of how URLs are built, see API overview.
In the paths below, {t} is the tenant id and {w} is the workspace id.
Processes (automations)#
A process is a published package version pinned in a workspace, with an entry point and a retry policy. The API calls it an automation.
| Method | Route | Permission |
|---|---|---|
GET |
/api/v1/tenants/{t}/workspaces/{w}/automations |
processes.view |
POST |
/api/v1/tenants/{t}/workspaces/{w}/automations |
processes.edit |
GET |
/api/v1/tenants/{t}/workspaces/{w}/automations/{id} |
processes.view |
PUT |
/api/v1/tenants/{t}/workspaces/{w}/automations/{id} |
processes.edit |
PUT |
.../automations/{id}/package-version |
processes.edit |
POST |
.../automations/{id}/upgrade |
processes.edit |
DELETE |
.../automations/{id} |
processes.delete |
{
"name": "Invoice intake",
"description": "Reads supplier invoices and posts them to the ERP.",
"packageId": "b7a1...",
"packageVersionId": null,
"entryPointId": "main",
"retryPolicy": {
"maxRetries": 3,
"strategy": "Exponential",
"baseDelaySeconds": 30,
"maxDelaySeconds": 600,
"retryOnApplicationError": true,
"retryOnTimeout": true,
"retryOnLeaseExpiry": true
},
"executionTimeoutSeconds": 3600
}
Omit packageVersionId to pin the package's latest version, and omit entryPointId to use the version's default entry point. Without a retryPolicy there are no retries. Business faults are never retried. The response includes runtime (velophex-workflow or python) and requiredRuntimes.
Jobs#
| Method | Route | Permission |
|---|---|---|
POST |
/api/v1/tenants/{t}/workspaces/{w}/jobs |
jobs.create |
GET |
/api/v1/tenants/{t}/workspaces/{w}/jobs |
jobs.view |
GET |
.../jobs/{jobId} |
jobs.view |
POST |
.../jobs/{jobId}/cancel |
jobs.cancel |
POST |
.../jobs/{jobId}/replay |
jobs.create |
GET |
.../jobs/{jobId}/logs |
logs.view |
GET |
/api/v1/tenants/{t}/workspaces/{w}/logs |
logs.view |
Start a job#
Start a jobHTTPCopyPOST /api/v1/tenants/{t}/workspaces/{w}/jobs HTTP/1.1
Authorization: Bearer vpx_pat_...
Idempotency-Key: invoice-2026-00042
Content-Type: application/json
{
"automationId": "5c0e9d1a-...",
"inputs": { "invoiceNumber": "00042", "pages": 2 },
"priority": 50
}
inputsis validated against the entry point's input JSON Schema. A mismatch returns422with the failing properties.runnerId(optional) pins the job to one Robot. The field name is a protocol identifier.- If no Robot serving the workspace reports the runtime the package needs, the start is refused with
409(no_capable_runner). - The response is
201 Createdwith the job, or200 OKwith the existing job when theIdempotency-Keywas already used for the same request.
You should see the job with status set to Pending. It moves to Running when a Robot claims it and ends as Succeeded, Failed, Canceled or DeadLettered.
Cancel a job#
POST .../jobs/{jobId}/cancelJSONCopy{ "force": false }
A pending job is canceled at once. For a running job, force: false asks the Robot to stop and the job shows CancelRequested until it does; force: true ends the job immediately. The jobs.cancel permission is held by every role that has jobs.edit.
Queues and queue items#
| Method | Route | Permission |
|---|---|---|
GET, POST |
/api/v1/tenants/{t}/workspaces/{w}/queues |
queues.view, queues.edit |
GET, PUT |
.../queues/{queueId} |
queues.view, queues.edit |
DELETE |
.../queues/{queueId} |
queues.delete |
GET |
.../queues/{queueId}/stats |
queues.view |
GET |
.../queues/{queueId}/items |
queue_items.view |
POST |
.../queues/{queueId}/items |
queue_items.create |
GET, PUT |
.../queue-items/{itemId} |
queue_items.view, queue_items.edit |
DELETE |
.../queue-items/{itemId} |
queue_items.delete |
POST |
.../queue-items/{itemId}/requeue |
queue_items.edit |
POST |
.../queue-items/{itemId}/postpone |
queue_items.edit |
{
"name": "Invoices",
"description": "Supplier invoices waiting to be posted.",
"maxRetries": 3,
"enforceUniqueReference": true,
"slaMinutes": 240,
"riskSlaMinutes": 180
}
POST .../queues/{queueId}/itemsJSONCopy{
"items": [
{
"reference": "INV-00042",
"priority": 70,
"payload": { "supplier": "Contoso", "amount": 1250.00 },
"deadline": "2026-10-01T17:00:00Z",
"deferUntil": null
}
]
}
The route adds up to 1,000 items at once, atomically, and answers 201 Created with the created items. If one item's reference already exists in a queue that enforces unique references, the whole batch is refused with 409 (duplicate_reference). priority runs from 0 to 100 (default 50); new items are taken by earliest deadline (items without one last), then higher priority, then age. deferUntil keeps an item out of processing until that time. To postpone an existing item, send { "deferUntil": "...", "deadline": null } to the postpone route. See Queues and SLAs.
Triggers#
| Method | Route | Permission |
|---|---|---|
GET, POST |
/api/v1/tenants/{t}/workspaces/{w}/triggers |
triggers.view, triggers.edit |
GET |
.../triggers/preview |
triggers.view |
GET, PUT |
.../triggers/{triggerId} |
triggers.view, triggers.edit |
DELETE |
.../triggers/{triggerId} |
triggers.delete |
GET |
.../triggers/{triggerId}/next-occurrences |
triggers.view |
POST |
.../triggers/{triggerId}/enable, .../disable |
triggers.edit |
{
"name": "Weekday 7:00",
"automationId": "5c0e9d1a-...",
"inputs": {},
"priority": 50,
"schedule": {
"cronExpression": "0 7 * * 1-5",
"timeZone": "Europe/Berlin",
"misfirePolicy": "FireOnce"
}
}
A queue triggerJSONCopy{
"name": "Work the invoice queue",
"automationId": "5c0e9d1a-...",
"queue": {
"queueId": "9e2c...",
"minPendingItems": 1,
"itemsPerJob": 10,
"maxConcurrentJobs": 4,
"pollingIntervalSeconds": 30
}
}
A trigger has exactly one of schedule (time trigger) or queue (queue trigger). Cron expressions have five fields (minute, hour, day of month, month, day of week). The time zone is an IANA id; Windows ids are converted. misfirePolicy is FireOnce (default) or Skip for occurrences missed while the Orchestrator was down. An optional calendarId skips occurrences on a tenant calendar's non-working dates. For queue triggers, maxConcurrentJobs is 1 to 64 and pollingIntervalSeconds is 10 to 3600. See Triggers and schedules.
Assets#
| Method | Route | Permission |
|---|---|---|
GET, POST |
/api/v1/tenants/{t}/workspaces/{w}/assets |
assets.view, assets.edit |
GET, PUT |
.../assets/{assetId} |
assets.view, assets.edit |
DELETE |
.../assets/{assetId} |
assets.delete |
{
"name": "ErpApiKey",
"description": "API key for the ERP integration user.",
"type": "Secret",
"value": { "secret": "..." }
}
type is Text, Integer, Boolean, Secret or Credential. Set only the value field that matches the type (text, integer, boolean, secret, or userName and password). Secrets and passwords are write only: responses show whether a value is set, never the value. See Credentials and assets.
Machines and enrollment keys#
| Method | Route | Permission |
|---|---|---|
GET, POST |
/api/v1/tenants/{t}/machines |
machines.view, machines.edit |
DELETE |
/api/v1/tenants/{t}/machines/{machineId} |
machines.delete |
GET |
/api/v1/tenants/{t}/machines/summary |
machines.view |
PUT |
.../machines/{machineId}/workspaces/{w} |
machines.edit |
GET, POST |
.../machines/{machineId}/enrollment-keys |
machines.view, machines.edit |
POST |
.../machines/{machineId}/enrollment-keys/{keyId}/revoke |
machines.edit |
Create a machine with name, description, maxConcurrentJobs and bindSingleHost, assign it to workspaces, then create an enrollment key. See Enroll a Robot.
Packages and the feed#
| Method | Route | Permission |
|---|---|---|
GET |
/api/v1/tenants/{t}/packages |
packages.view |
POST |
/api/v1/tenants/{t}/packages (upload) |
packages.create |
GET |
.../packages/{packageId}/versions |
packages.view |
PUT |
.../packages/{packageId}/versions/{versionId} |
packages.edit |
DELETE |
.../packages/{packageId}/versions/{versionId} |
packages.delete |
PUT |
/api/v1/tenants/{t}/feed/v3/package |
packages.create |
Publishing through the NuGet v3 feed is the recommended path for CI:
PowerShellCopydotnet nuget push .\Invoices.1.2.0.nupkg `
--source "https://orchestrator.example.com/api/v1/tenants/<tenantId>/feed/v3/index.json" `
--api-key $env:VELOPHEX_API_KEY
A push answers 201 when the package is new, 400 when it fails inspection, and 409 when the version already exists: package_binary_duplicate (the same bytes, which you can treat as success) or package_version_exists (different bytes; publish a new version). The default upload limit is 100 MB per package (Packages:MaxPackageSizeBytes). To deactivate a version, PUT the version with isActive: false; a deactivated version stays downloadable by exact version so pinned processes keep working. Deleting through NuGet is not supported. See Packages and processes.
Settings, audit and access#
| Method | Route | Permission |
|---|---|---|
GET |
/api/v1/tenants/{t}/settings/groups |
settings.view |
GET, PUT |
/api/v1/tenants/{t}/settings/{group} |
settings.view, settings.edit |
GET |
/api/v1/tenants/{t}/audit |
audit.view |
GET, POST |
/api/v1/tenants/{t}/roles, /role-assignments |
roles.view, roles.edit |
GET |
/api/v1/permissions |
signed in |
Tenant setting groups are general, security, email, retention, robots, uiAutomation, expressions and packages. See Settings.
Next steps#
- Webhooks
- Pagination and errors
- Python SDK API reference for the runtime API used inside automations
Processes (automations)
Jobs
Start a job
Cancel a job
Queues and queue items
Triggers
Assets
Machines and enrollment keys
Packages and the feed
Settings, audit and access
Next steps