REST API

Available

Every endpoint group exposed by the Orkovia API, with conventions.

Base URL and versioning

All endpoints are versioned under /api/v1. Paths in the tables below are relative to that prefix — for a local install, http://localhost:8080/api/v1.

Authentication

Every endpoint requires an Authorization: Bearer <token> header, except login, the auth config check, the health check and the OpenAPI/Swagger endpoints. A token can come from POST /auth/login (username and password) or from your OIDC provider (Keycloak, Auth0, Okta).

Token claim	Meaning
sub	The calling user or service; recorded on audit and history events
tenantId	Tenant scope (a UUID). Data from another tenant is reported as 404, not 403
roles	One or more of ADMIN, PROCESS_OWNER, TASK_USER

As a rule, reads are open to any authenticated caller in the tenant, while deploying, operating on instances, recovering incidents and other design-time or operational writes need ADMIN or PROCESS_OWNER. User, group, authorization and audit-log endpoints are ADMIN only.

Response and error envelope

{
  "success": true,
  "message": "Success",
  "timestamp": "2026-07-25T10:15:30Z",
  "data": { }
}

{
  "success": false,
  "errorCode": "RESOURCE_NOT_FOUND",
  "message": "process instance not found: abc-123",
  "timestamp": "2026-07-25T10:15:30Z",
  "errors": [],
  "correlationId": "9f2c..."
}

errorCode	HTTP status
VALIDATION_ERROR, BAD_REQUEST	400
UNAUTHORIZED	401
FORBIDDEN	403
RESOURCE_NOT_FOUND	404
CONFLICT	409
BUSINESS_ERROR	422
INTERNAL_ERROR	500

Every response echoes an X-Correlation-Id header. Send your own value in a request header of the same name and it is returned unchanged; otherwise the server generates one.

Authentication and access

Endpoint	Purpose
GET /auth/config	Which sign-in methods are enabled (public)
POST /auth/login	Exchange a username and password for a bearer token (public)
GET, POST /auth/users	List or create users in your tenant
GET, POST /auth/groups	List or create groups
GET, POST /auth/groups/{id}/members	List or add group members
DELETE /auth/groups/{id}/members/{userId}	Remove a group member
GET, POST /auth/authorizations	List or grant resource-level permissions
DELETE /auth/authorizations/{id}	Revoke a permission
GET, POST /invitations	List outstanding invitations or invite someone to an organization
POST /invitations/accept	Accept an invitation
DELETE /invitations/{id}	Revoke an invitation

Deployments

Endpoint	Purpose
POST /deployments	Deploy a process — BPMN 2.0 XML (application/xml) or a JSON graph (application/json)
GET /deployments	List deployments; ?key= returns one process's version history
GET /deployments/{id}	Fetch a deployment, including its BPMN XML
DELETE /deployments/{id}	Undeploy a version; ?includeFinishedInstances=true also deletes its finished instances
POST /deployments/{id}/suspend, /resume	Block or allow new instance starts and timer fires for a definition
POST /deployments/{id}/simulate	Run in-memory simulated instances and report branch coverage and timings
GET /deployments/{id}/nodes	Node ids and types, for building a migration mapping

Process instances

Endpoint	Purpose
POST /process-instances	Start an instance of a deployment, with optional variables
GET /process-instances	List instances, newest first
GET /process-instances/{id}	Read one instance
DELETE /process-instances/{id}	Permanently delete a finished instance and its history
POST /process-instances/{id}/cancel	Terminate an instance and any call-activity children
POST /process-instances/{id}/suspend, /resume	Pause and resume a waiting instance
POST /process-instances/{id}/move-token	Move a waiting token from one node to another
POST /process-instances/migrate	Migrate instances to another version of the same process
GET /process-instances/{id}/history	Execution history and audit trail, oldest first
GET /process-instances/{id}/history/{eventSeq}/snapshot	Variables and active node as of one history event
GET /process-instances/{id}/tokens	Tokens currently parked at a join, job or task
GET /process-instances/{id}/event-subscriptions	Pending timer and message subscriptions

Variables

Endpoint	Purpose
GET, PUT /process-instances/{id}/variables	Read or edit an instance's variables, with optimistic locking via expectedVersion
GET /process-instances/{id}/node-variables	Variables attached to specific nodes of an instance
PUT /process-instances/{id}/nodes/{nodeId}/variables	Attach variables to one node
GET /scopes/{scopeId}/variables	Every variable visible from a scope, with the scope it was found in
GET, PUT, DELETE /scopes/{scopeId}/variables/{name}	Read, set or remove one variable in a scope (audited)

Messages, signals and conditional starts

Endpoint	Purpose
POST /messages	Correlate a message by name and correlation key to waiting instances
POST /signals	Broadcast a signal to every matching subscription and signal start event
POST /conditional-start-events/evaluate	Re-check conditional start events against supplied variables

All three respond 202 Accepted with a count of resumed or started instances. Zero matches is not an error.

Batch operations

Endpoint	Purpose
POST /batch-operations	Start a CANCEL, RETRY, RESOLVE_INCIDENT, MIGRATE or SET_VARIABLES batch over many targets
GET /batch-operations/{id}	Batch progress and per-item outcome

Jobs (workers)

Endpoint	Purpose
POST /jobs/activation	Poll for jobs of a type and lock them; supports long polling
GET /jobs/stream	Server-sent event stream that pushes jobs to a worker
POST /jobs/{id}/heartbeat	Extend a job lock
POST /jobs/{id}/complete	Report success and resume the instance
POST /jobs/{id}/fail	Report a technical failure; retries, then dead-letters into an incident
POST /jobs/{id}/error	Throw a business error for an error boundary event to catch
GET /jobs	List jobs, newest first
POST /jobs/{id}/retries	Reset a job's retry count and make it claimable again
GET, POST /jobs/{id}/retry	Read a job's retry state or replace its retry policy
POST /jobs/{id}/retry-now	Skip the remaining backoff of a waiting retry
POST /jobs/{id}/retry/cancel	Cancel a pending retry and raise an incident
GET /jobs/{id}/retry/history	Recorded retry attempts for a job

Human tasks

Endpoint	Purpose
GET /tasks	List tasks; filter by ?candidateGroup= and ?assignee=
POST /tasks/{id}/claim, /unclaim	Claim a task or release it
POST /tasks/{id}/assign	Assign a task to a user
POST /tasks/{id}/delegate	Delegate a claimed task to another user
POST /tasks/{id}/complete	Complete a task with variables and resume the instance
GET, POST /tasks/{id}/comments	Read or add to a task's comment thread
GET /tasks/{id}/form	The task's linked form schema
GET /tasks/{id}/form-definition	The task's linked Form Designer form
GET, POST /task-filters	List or save task list filters
DELETE /task-filters/{id}	Delete a saved filter

Incidents

Endpoint	Purpose
GET /incidents	List incidents
POST /incidents/{id}/retry	Re-run the failed node
POST /incidents/{id}/skip-node	Continue past the failed node without running it
POST /incidents/{id}/restart-from-node	Resume from a chosen node, keeping variables
POST /incidents/{id}/rollback	Restore variables to a history event, then retry
POST /incidents/{id}/edit-variables-and-retry	Patch variables and retry in one call

Decisions (DMN) and FEEL

Endpoint	Purpose
GET, POST /decisions	List decisions or deploy a decision table (JSON)
POST /decisions/import	Import a DMN XML file
GET /decisions/{id}	Fetch a decision
GET /decisions/{id}/xml	Export a decision as DMN XML
POST /decisions/{id}/evaluate	Evaluate a decision against variables
POST /decisions/{id}/evaluate-with-trace	Evaluate and return which rules matched
GET /decision-models	List imported DMN models
GET /decision-models/{id}	A model's decisions, decision services and required inputs
GET /decision-models/{id}/xml	The model's DMN XML
POST /decision-models/{id}/decisions/{decisionId}/evaluate	Evaluate one decision in a model, including its required decisions
POST /decision-models/{id}/services/{serviceId}/evaluate	Evaluate a decision service
POST /feel/evaluate	Evaluate a FEEL expression against a supplied context
GET /feel/functions	List the FEEL built-in functions

Forms

Endpoint	Purpose
GET, POST /form-definitions	List Form Designer forms or create a draft
GET, PUT, DELETE /form-definitions/{id}	Fetch, edit or delete a form (edit and delete while DRAFT)
POST /form-definitions/{id}/validate, /return-to-draft, /publish, /deploy, /retire	Lifecycle transitions: DRAFT → VALIDATED → PUBLISHED → DEPLOYED → RETIRED
POST /form-definitions/{id}/playground	Run a form against mock data
GET /form-definitions/{id}/versions	Change history
GET /form-definitions/{id}/versions/diff	Component diff between two versions (?from=&to=)
POST /form-definitions/{id}/versions/{version}/restore	Restore a version as a new draft
GET /form-definitions/{id}/lineage	Every form restored from, or into, this one
GET /form-definitions/{id}/audit	Governance audit trail
GET /form-definitions/{id}/locales	Locales that have translations
PUT, DELETE /form-definitions/{id}/locales/{locale}	Save or remove a locale's translated labels
GET /form-definitions/{id}/locales/{locale}/resolved	Labels resolved for a locale, with fallback applied
GET, POST /forms	List or deploy a simple form schema (legacy)
GET, PUT, DELETE /forms/{id}	Fetch a form, publish an edit as a new version, or remove a version (legacy)
POST /forms/{id}/migrate-to-v1	Import a legacy form as a new Form Designer draft

Connectors and connections

Endpoint	Purpose
GET /connectors	Connector types registered in this installation
GET, POST /connections	List or create connections
GET, PUT, DELETE /connections/{id}	Fetch, update or delete a connection
POST /connections/{id}/enable, /disable	Switch a connection on or off
POST /connections/{id}/test	Check that a connection is completely configured

Modeling and collaboration

Endpoint	Purpose
GET, POST /projects	List or create projects
GET, PATCH, DELETE /projects/{id}	Fetch, update or delete a project
GET, POST /projects/{id}/members	List or add project members
DELETE /projects/{id}/members/{userId}	Remove a project member
GET, POST /projects/{id}/folders	List or create folders
GET, POST /models	List or create models
GET, DELETE /models/{id}	Fetch or delete a model
PUT /models/{id}/content	Save model content as a new revision
GET /models/{id}/revisions	Revision history
POST /models/{id}/restore	Restore an earlier revision
GET, POST, DELETE /models/{modelId}/lock	Read, acquire or release a model's editing lock
POST /models/{modelId}/lock/renew, /takeover	Keep a lock alive or take it over
GET, POST /drafts	List or create your own drafts; filter by ?kind=
GET, PUT, DELETE /drafts/{id}	Fetch, save or delete a draft
POST /drafts/{id}/promote	Deploy a draft as a process, decision or form
GET, POST /templates	List or create process templates
GET, PUT, DELETE /templates/{id}	Fetch, update or delete a template

Testing and analysis

Endpoint	Purpose
POST /play/sessions	Start a Play session from BPMN XML, without deploying
POST /play/sessions/{id}/step	Advance one node; optionally choose a gateway branch or set variables
GET /play/sessions/{id}	Read a session's current state
POST /analysis/variables	Static variable analysis and warnings for BPMN XML

Insights, audit and administration

Endpoint	Purpose
GET /insights	Process duration, completion rate, job reliability and task-age metrics
GET /insights/report	Completion rate or duration, filtered by process and date range and grouped by a variable
GET /audit-events	Paged, filterable log of every state-changing API call
POST /admin/projections/instance-summary/rebuild	Rebuild the instance summary projection

OpenAPI and Swagger UI

Each installation serves its own machine-readable spec and interactive explorer. These two paths sit at the server root, not under /api/v1, and need no token.

Path	Purpose
GET /v3/api-docs	OpenAPI 3 specification as JSON
GET /swagger-ui.html	Interactive Swagger UI

This page lists what each endpoint is for. For exact request bodies, response schemas and role requirements, use the Swagger UI of your installed Orkovia release.

PreviousSecrets Next BPMN reference