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
| Situation | Path |
|---|---|
| Ruby, PHP, or any language without an official SDK | This HTTP API |
| A custom gateway, BFF, or ESB | This HTTP API |
| Node.js, .NET, or Java | The full SDKs |
| Python or Go workers | Python and Go, jobs only |
| People designing or operating processes | The console, not raw HTTP |
Base URL
| Environment | Command writes | Query reads |
|---|---|---|
| Local Compose | http://localhost:9100/api/v1 | http://localhost:9100/api/v1/query |
| Production example | https://app.example.com/api/v1 | https://app.example.com/api/v1/query |
| Direct service, debugging only | http://localhost:8080/v1 | http://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.
- Swagger UI for the checked-in contract.
- OpenAPI document (
artificialflow-v1.2.0.yaml). Upstream copy: docs/openapi.yaml. - Postman collection and the local environment.
baseUrlishttp://localhost:9100/api/v1. SetbearerTokenwhen IAM is on.
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.
| Role | Typical use |
|---|---|
artificialflowadmin | Every API, including deletes, incidents, retries, and instance migration. |
artificialflowbusiness | Deploy and read workflows and decisions. |
artificialflowclient | Start instances, publish events, run jobs, search, and operate user tasks. |
artificialflowanalytics | Reserved. 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/meQuickstart
$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.
| Method | Path | Notes |
|---|---|---|
| GET | /tasks | Search. assignee, candidateUser, and candidateGroup are OR-combined. state is active, completed, or all. |
| GET | /instances/{id}/tasks | Tasks of one instance. |
| POST | /instances/{id}/tasks/{executionId}/claim | Body { "assignee": "…" }. Client tokens must send the assignee. |
| POST | /instances/{id}/tasks/{executionId}/complete | The 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.