Skip to content

API#

Everything the console does in Iris goes through the same REST API as the rest of Astralyx, in JSON. Authentication, conventions and the error format are in the API Reference overview; this page lists Iris' endpoints.

Base URL#

$ export ASTRALYX_API=https://api.astralyx.cloud/v1
$ export ASTRALYX_TOKEN=ast_pat_…

Workflows are the Flow resource, at /anemoi/flows, and their executions at /anemoi/flow-executions. With a token scoped to your workspace, a call names nothing else; a token for all your workspaces names one with Astralyx-Workspace: <org>/<workspace>, and a workspace on several clusters names one with Astralyx-Cluster (see The workspace and the cluster). Names in paths and bodies are your workspace's own (card-spending), and every reference must name an object of the workspace.

Permissions#

Permission Allows
flows:read Read workflows, versions and triggers' state; list addresses and their calls.
flows:create Create a workflow; check a specification (flow-checks).
flows:update Write a version; make a version current.
flows:delete Delete a workflow.
flows:trigger Start executions, send events, delete executions that ended; make, renew and remove addresses.
flow-executions:read Read executions.
flow-executions:cancel Cancel an execution.
flow-executions:retry Retry a failed box.

The viewer role reads; editor and admin have them all. See Permission catalog.

Workflows#

Method and path Description
POST $ASTRALYX_API/anemoi/flows {metadata, spec} (Workflow specification): version 1, current. 201.
GET $ASTRALYX_API/anemoi/flows {items}, each with current, latest, created_by and the current spec.
GET, DELETE $ASTRALYX_API/anemoi/flows/{name} One; DELETE removes it, its versions and its triggers' state (its executions stay).
PUT $ASTRALYX_API/anemoi/flows/{name} A new version: {spec, current}.
GET $ASTRALYX_API/anemoi/flows/{name}/versions[/{n}] Versions.
PUT $ASTRALYX_API/anemoi/flows/{name}/current {version}.
POST $ASTRALYX_API/anemoi/flow-checks {name?, spec} → {ok, errors: [{path, message}], warnings}. Nothing stored.
GET $ASTRALYX_API/anemoi/flows/{name}/triggers {items: [{id, next_at, last_fired_at, last_execution, last_error}]}: each schedule's state — when it fires next, what it last started, why it last could not.

Executions#

Method and path Description
POST $ASTRALYX_API/anemoi/flows/{name}/executions Start one: {inputs?, version?, event?, wait_seconds?, trigger?}. Below.
GET $ASTRALYX_API/anemoi/flows/{name}/executions, GET $ASTRALYX_API/anemoi/flow-executions?flow=&state= Executions: {items: [{metadata, flow, version, started_by, status, step_counts}]}.
GET $ASTRALYX_API/anemoi/flow-executions/{name} One (the execution). ?wait=<s> (1 to 30) answers once it has ended, or after that long.
DELETE $ASTRALYX_API/anemoi/flow-executions/{name} An execution that ended, with its own drive.
POST $ASTRALYX_API/anemoi/flow-executions/{name}/cancel Cancel it: its boxes under way are stopped.
POST $ASTRALYX_API/anemoi/flow-executions/{name}/steps/{step}/retry One more attempt of a failed box.
POST $ASTRALYX_API/anemoi/flow-executions/{name}/events/{event} {data: {k: v}}, at most 4 KiB: what a wait_event box waits for. 202.

Starting an execution#

Field Description
inputs {name: value}: text, a number or a boolean, at most 64 KiB each. Defaults fill the rest; a required one missing is 400 INVALID_FLOW.
version A version other than the current one.
event What happened: any JSON, at most 128 KiB as text. Read as event.
wait_seconds Answer once the execution has ended (200), waiting at most this long (1 to 90); 202 when it has not ended by then. Without it, the answer is 201 at once.
trigger The id of an HTTP trigger of the current version: the execution names it, runs the current version whatever version says, and the trigger's dedupe applies — a key seen within its time answers the execution it started, with deduplicated: true.

The answer is the execution. A workflow whose concurrency drops what comes when its places are taken answers 429 FLOW_BUSY.

$ curl -sS -X POST "$ASTRALYX_API/anemoi/flows/card-spending/executions" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "Content-Type: application/json" \
    -d '{"event": {"id": "t1", "text": "COMPRA APROVADA R$ 250,00 PADARIA SAO JOAO"}, "wait_seconds": 60}' \
    | jq '{state: .status.state, outputs}'

Addresses#

An HTTP trigger's address is made through the console's API, for a workspace and one of its clusters, with an API token:

https://console.astralyx.cloud/api/v1/orgs/{org}/workspaces/{workspace}/clusters/{cluster}/flow-hooks
Method and path Description
GET …/flow-hooks?flow= The addresses made: {items: [{id, flow, trigger, runs_as, created_at, url, last_call_at, last_status}]} — url without its secret. flows:read.
POST …/flow-hooks {flow, trigger}: make the address of an HTTP trigger of the workflow's current version, or give it a new secret (the old one stops working). 201 with {id, flow, trigger, url, secret, auth, how, mode}: the secret is in this answer only; how names the header to send. Calls run as you. flows:trigger. Not an HTTP trigger of the current version: 404 FLOW_TRIGGER_NOT_FOUND.
DELETE …/flow-hooks/{id} The address stops working. 204. flows:trigger.
GET …/flow-hooks/{id}/calls Its last 100 calls, newest first: {items: [{at, status, execution, source, error, deduplicated}]}. Kept 30 days. flows:read.

The address itself takes no API token; the call proves itself as its trigger's auth says:

Method and path Description
POST https://console.astralyx.cloud/api/v1/hooks/{id}/{secret} auth: url.
POST https://console.astralyx.cloud/api/v1/hooks/{id} auth: bearer (Authorization: Bearer <secret>) or hmac (the signature in the trigger's header).
GET on either With the trigger's allow_get: the query is the event.

Answers: 202 {execution, state, deduplicated}; for mode: sync, 200 with the outputs, 502 WORKFLOW_FAILED or, past the wait, 202; the header Astralyx-Execution names the execution. Refusals are in Errors and limits. See Start a workflow with an HTTP call.