Skip to content
ArtificialFlow

HTTP API

Call the gateway when you are not using the Node.js, .NET, or Java SDK. The recommended base is /api/v1. Unversioned /api remains a compatibility alias with the older plain-text errors.

When to use HTTP

SituationPath
Ruby, PHP, or any language without an official SDKThis HTTP API
A custom gateway, BFF, or ESBThis HTTP API
Node.js, .NET, or JavaThe full SDKs
Python or Go workersPython and Go, jobs only
People designing or operating processesThe console, not raw HTTP

Base URL

EnvironmentCommand writesQuery reads
Local Composehttp://localhost:9100/api/v1http://localhost:9100/api/v1/query
Production examplehttps://app.example.com/api/v1https://app.example.com/api/v1/query
Direct service, debugging onlyhttp://localhost:8080/v1http://localhost:8081/v1

/api/v1/... returns RFC 9457 problem details. /api/... hits the same handlers and keeps 1.x plain-text errors. Public health is GET /api/health and GET /api/query/health. The gateway also serves the contract at /api/openapi.yaml.

OpenAPI, Swagger, and Postman

The machine-readable contract is OpenAPI 3.0.3, version 1.2.0. It covers command, query, workers, and user tasks. It does not include an identity-administration API. Generate clients from this file. The legacy Swaggo page at /api/swagger/index.html is incomplete and is scheduled for removal in v1.3.0.

The narrative source is docs/API.md. Worker calls send X-Workflow-Worker-Protocol-Version: v1. Job mutations send a distinct Idempotency-Key of at most 128 characters.

Authentication

With IAM_DEPLOYMENT_MODE=true, every route except health and /identity/login needs Authorization: Bearer. Integrations use a machine identity that holds only artificialflowclient. With false, no token is needed and every call runs as artificialflowadmin. Do not expose that mode beyond a private machine.

RoleTypical use
artificialflowadminEvery API, including deletes, incidents, retries, and instance migration.
artificialflowbusinessDeploy and read workflows and decisions.
artificialflowclientStart instances, publish events, run jobs, search, and operate user tasks.
artificialflowanalyticsReserved. No API access yet.
TOKEN=$(curl -sS -X POST "$TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "audience=workflow-backend" \
  | jq -r .access_token)

curl -fsS -H "Authorization: Bearer $TOKEN" \
  http://localhost:9100/api/identity/me

Quickstart

$API below is http://localhost:9100/api/v1. Add the bearer header when IAM is on.

curl -fsS -X POST "$API/workflows" \
  -H "Content-Type: application/xml" \
  --data-binary @process.bpmn

curl -fsS -X POST "$API/instances" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"order_approval","context":{"orderId":"ord-1"}}'

Command

POST /workflows deploys BPMN XML. workflow_id on POST /instances may be a numeric key or a BPMN process id. Optional version pins a version. A running instance reports ACTIVE. Deletes are admin only.

Administrators can dry-run and apply a bounded move of a running instance with POST /instances/{id}/migration/dry-run and POST /instances/{id}/migration. The body carries sourceDefinitionKey, targetDefinitionKey, and elementMapping. Nested scopes, compensation, event subprocesses, multi-instance state, executing external work, and unresolved incidents are rejected.

Messages, signals, and escalations accept roles admin and client:

curl -fsS -X POST "$API/messages" \
  -H "Content-Type: application/json" \
  -d '{"message_name":"PaymentReceived","correlation_key":"ord-1","payload":{"amount":1500}}'

POST /decisions stores a JSON decision table in the resource string. POST /decisions/{id}/evaluate dry-runs inputs. See Decisions.

GET /incidents and POST /incidents/{key}/resolve are admin operations, as is POST /jobs/{key}/retry. The gateway returns 404 for /api/internal/metrics.

Workers

Activate with POST /jobs/activate, then complete, fail, or extend the lock. Protocol header v1. Roles are admin and client. Details are on Workers. gRPC JobWorkerService listens on the command process at :50051 and is not on the gateway.

User tasks

ArtificialFlow does not authenticate the end users of your application. Your backend holds an artificialflowclient token and passes the person as a filter or as assignee. Do not put that token in the browser.

MethodPathNotes
GET/tasksSearch. assignee, candidateUser, and candidateGroup are OR-combined. state is active, completed, or all.
GET/instances/{id}/tasksTasks of one instance.
POST/instances/{id}/tasks/{executionId}/claimBody { "assignee": "…" }. Client tokens must send the assignee.
POST/instances/{id}/tasks/{executionId}/completeThe same assignee that claimed the task, unless the caller is an admin. Returns 204.

Query

Base {gateway}/api/v1/query. GET /query/instances and GET /query/workflows are eventually consistent. workflowId filters must be numeric strings. GET /query/health is public.

Most resource ids are JSON strings even when they are numeric internally. Query instance ids are numeric strings.