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
POST .../automationsJSONCopy
{
  "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 jobHTTPCopy
POST /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
}
  • inputs is validated against the entry point's input JSON Schema. A mismatch returns 422 with 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 Created with the job, or 200 OK with the existing job when the Idempotency-Key was 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
POST .../queuesJSONCopy
{
  "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
A time triggerJSONCopy
{
  "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
POST .../assetsJSONCopy
{
  "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:

PowerShellCopy
dotnet 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#

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