API overview

The AkôFlow Desktop uses the same API available to automation. Paths in the tables below are relative to AKOFLOW_API_URL, which includes /akoflow-api.

Connect and authenticate

Set the API base URL (including /akoflow-api) and token in your shell:

export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api"
export AKOFLOW_API_TOKEN="replace-with-the-configured-token"

curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  "$AKOFLOW_API_URL/environments/"

The listen address is configuration-dependent; do not assume the example port in production. When an API token is configured, send Authorization: Bearer <token>. GET or HEAD requests for /akoflow-api/instance/ and GET /akoflow-api/preflight/ are public bootstrap operations. All other operations require the token. A daemon without a token is restricted to loopback access.

Browser origins are controlled by the daemon's allowed-origin configuration. Authentication failures return 401; non-loopback requests to a loopback-only service return 403.

Conventions

• JSON requests use Content-Type: application/json; most responses are JSON.
• Simple collection responses are normally JSON arrays. Some catalog and query endpoints use { "items": [...] } or a richer pagination envelope; preserve the shape returned by each endpoint.
• IDs in {braces} are URL path parameters. Encode user-provided path segments.
• Many collection paths retain a trailing slash; use the route exactly as shown.
• Successful creates generally return 201 Created; queued work commonly returns 202 Accepted; deletes commonly return 204 No Content.
• Errors from kernel-wrapped routes use a JSON error message. Validation failures commonly return 400 or 422; missing records return 404; unavailable capabilities return 503.
• An activated archive snapshot is read-only. Mutating requests return 423 Locked, except instance activation itself.
• Export, download, build output, and console stream routes return non-JSON content.

Check daemon and local build capabilities:

curl --fail-with-body "${AKOFLOW_API_URL%/akoflow-api}/"
curl --fail-with-body "$AKOFLOW_API_URL/preflight/"

The root health check returns ok. Preflight reports server, Docker, and BuildKit availability.

Instance, search, and operations

Method	Path	Purpose
GET, PUT	/instance/	Read or save installation identity/configuration
GET	/preflight/	Report daemon, Docker, and BuildKit readiness
GET	/search/	Global search
GET	/audit-events/	Filter operational audit events
GET	/instances/	List archived instances
GET	/instances/default/export/	Export the default instance
POST	/instances/import/	Import an instance archive
POST	/instance-activations/{instanceId}/	Activate an archived instance
POST	/factory-reset/	Reset the active instance
GET, PUT	/user-preferences/{clientId}/	Read or save client preferences

Environments, connections, and credentials

Method	Path	Purpose
GET, POST	/environments/	List or create environments
GET, PUT, DELETE	/environments/{environmentId}/	Read, replace, or delete an environment
POST	/connection-tests/	Test an unpersisted connection definition
PUT	/environment-connections/{connectionId}/	Update a connection
POST	/environment-connections/{connectionId}/health/	Check persisted connection health
POST	/environment-connections/{connectionId}/discover/	Discover environment infrastructure
GET	/environment-connections/{connectionId}/history/	List connection health/discovery history
GET, POST	/ssh-keys/	List or generate SSH keys
POST	/ssh-keys/import/	Import an SSH key
POST	/kubernetes-tokens/	Store a Kubernetes token
POST	/cloud-credentials/	Store a cloud credential
POST	/cloud-credentials/validate/	Validate a cloud credential

Cloud capacity and machine configuration

Method	Path	Purpose
GET, POST	/environments/{environmentId}/cloud-capacity-targets/	List or create capacity targets
DELETE	/cloud-capacity-targets/{targetId}/	Delete a target
GET, POST	/environments/{environmentId}/cloud-instances/	List or provision instances
POST	/environments/{environmentId}/cloud-provisioning/	Start a provisioning workflow
GET	/cloud-instances/{instanceId}/provisioning-log/	Read provisioning log
POST	/cloud-instances/{instanceId}/{configure,destroy,start,stop,validate}/	Perform an instance lifecycle action
GET	/cloud-operations/	List cloud operations
GET	/cloud-operations/{operationId}/	Read an operation
GET	/cloud-operations/{operationId}/events/	Read operation events
GET, POST	/machine-configurations/	List or create configurations
GET	/machine-configurations/{configurationId}/	Read a configuration
POST	/machine-configurations/{configurationId}/versions/	Add a configuration version
POST	/machine-configuration-validations/	Validate playbook YAML
GET	/environments/{environmentId}/cloud-catalog/	Read cached provider catalog
POST	/environments/{environmentId}/cloud-catalog/refresh/	Refresh provider catalog

Resources, topology, and execution scopes

Method	Path	Purpose
GET, POST	/resources/	List or create resources
GET	/resources/{resourceId}/	Read a resource
GET	/resources/{resourceId}/snapshot/	Read its observed snapshot
GET, POST	/network-topologies/	List or create topologies
GET	/network-topologies/{topologyId}/	Read a topology
GET, POST	/execution-scopes/	List or create scopes
GET, DELETE	/execution-scopes/{scopeId}/	Read or delete a scope

Storage

Method	Path	Purpose
GET	/environments/{environmentId}/storages/	List environment storages
GET	/storages/{storageId}/roots/	List allowed browse roots
GET, DELETE	/storages/{storageId}/entries/	Browse or delete an entry (path query)
GET	/storages/{storageId}/entry/	Stat an entry (compatibility route)
GET	/storages/{storageId}/stat/	Stat an entry
POST	/storages/{storageId}/downloads/	Prepare a file download
POST	/storages/{storageId}/checksum/	Calculate an entry checksum
POST	/storages/{storageId}/copies/	Queue a cross-storage copy
POST	/storages/{storageId}/archives/	Queue a directory archive
POST	/storages/{storageId}/promote-data/	Promote an entry to scientific data
POST	/storages/{storageId}/promote-artifact/	Promote an executable artifact
GET, POST	/storages/{storageId}/index-runs/	List or start indexing
GET	/storage-downloads/{downloadId}/	Read download/archive status
GET	/storage-downloads/{downloadId}/content/	Stream prepared content

Workflows and planning

Method	Path	Purpose
GET, POST	/workflow-definitions/	List or create workflows
POST	/workflow-definitions/import/	Import workflow JSON or YAML
GET	/workflow-definitions/{workflowId}/	Read a workflow
GET	/workflow-definitions/{workflowId}/export/	Export workflow YAML
POST	/workflow-definition-actions/duplicate/{workflowId}/	Duplicate a workflow
GET, POST	/schedule-plans/	List or create plans
POST	/schedule-plans/import/	Import a plan
GET	/schedule-plans/{planId}/	Read a plan
GET	/planning-algorithms/	List scheduler descriptors
GET, POST	/planning-sessions/	List or create planning sessions
GET	/planning-sessions/{sessionId}/	Read a session
POST	/planning-sessions/{sessionId}/cancel/	Cancel a session
GET	/planning-sessions/{sessionId}/candidates/	List candidates
GET	/planning-sessions/{sessionId}/candidates/{candidateId}/	Read a candidate
POST	/planning-sessions/{sessionId}/candidates/{candidateId}/select/	Select a candidate and produce a plan

Create a workflow by posting the current workflow definition document:

curl --fail-with-body -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @workflow.json \
  "$AKOFLOW_API_URL/workflow-definitions/"

Executions

Method	Path	Purpose
GET, POST	/execution-runs/	List or create runs
GET	/execution-runs/{runId}/	Read run detail, including related execution data

List queries accept endpoint-specific pagination and filters. For execution runs, the Desktop uses page and pageSize and follows hasNext.

Artifacts and builds

Method	Path	Purpose
GET	/artifacts/	List executable artifact versions
POST	/artifacts/docker/	Register a Docker source and SIF build specification
GET	/artifact-locations/	List verified artifact locations
GET, POST	/artifact-materializations/	List or record materializations (runId filters list)
POST	/build-contexts/	Upload multipart context, or register stored metadata
POST	/artifact-builds/	Create an immutable build specification
GET	/artifact-builds/{buildId}/	Read a build specification
GET	/artifacts/{artifactId}/builds/	List builds for an artifact
GET, POST	/artifact-builds/{buildId}/runs/	List or start build runs
GET	/build-runs/{runId}/	Read build-run status and logs
GET	/build-runs/{runId}/output/	Stream SIF output

See Artifacts, storage, and builds for payload examples and lifecycle semantics.

Provenance

Method	Path	Purpose
GET	/provenance/entities/	List safe entity projections
GET	/provenance/entities/{entity}/	Search, filter, sort, and page an entity
GET	/provenance/sql/schema/	Read the queryable schema
POST	/provenance/sql/	Execute parameterized read-only SQL
POST	/provenance/sql/explain/	Explain read-only SQL
GET	/provenance/lineage/{entity}/{id}/	Traverse lineage

See Provenance and audit for query parameters and examples.

Console

Method	Path	Purpose
GET, POST	/console-commands/	List or execute recorded console commands
GET, POST	/console-sessions/	List or open interactive sessions
DELETE	/console-sessions/{sessionId}/	Close a session
GET	/console-sessions/{sessionId}/log/	Export session log
GET	/console-sessions/{sessionId}/stream/	Stream the interactive session

The stream route is intentionally not wrapped as ordinary JSON. Use the Desktop client or a compatible streaming client rather than treating it as a request/response endpoint.

Discover payload shapes

This overview intentionally does not duplicate every domain schema. Use these sources in order:

1. Start from a Desktop operation or a task guide to understand the required lifecycle.
2. Fetch server-described catalogs such as planning algorithms, provenance entities, and provenance SQL schema.
3. Use an existing object returned by a list/detail route as the basis for create or replace operations where applicable.
4. Treat identifiers, immutable digests, credential references, and capability flags as opaque unless a specific guide defines them.

Do not send secrets in general resource objects. Credential endpoints store secrets separately, while environment and connector records refer to them.

Priority contract recipes

The endpoints below are the entry points that most readers copy from this page. Each recipe shows a minimal, runnable request, the success status, and the most common failure. The generated endpoint pages list every other field; use them for fields not shown here.

Import an instance archive

The handler reads the request body as an application/zip stream, not JSON. The ZIP must contain the manifest, the database snapshot, and the redaction marker written by GET /instances/default/export/. Symbolic links, archives larger than 8 GiB compressed, archives with more than 10,000 entries, and archives whose checksum or schema version does not match are rejected with 422.

curl --fail-with-body \
  -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  -H 'Content-Type: application/zip' \
  --data-binary @akoflow-instance.zip \
  "$AKOFLOW_API_URL/instances/import/"

Success returns 201 Created with the new instance projection. Activation is a separate request:

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  "$AKOFLOW_API_URL/instance-activations/<snapshot-id>/"

Activation returns 202 Accepted with { "instance": ..., "restarting": true|false }.

Upload a build context

The handler accepts either an application/json envelope or a multipart/form-data upload. The multipart path is the recommended way to send large build contexts because the JSON envelope requires a storageUri that already points at bytes the daemon has stored.

curl --fail-with-body \
  -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  -F "context=@./context.tgz" \
  "$AKOFLOW_API_URL/build-contexts/"

The multipart field name is context. The handler enforces a maximum body size plus one extra megabyte; an oversized upload returns 413 Request Entity Too Large. A missing context field returns 422 Unprocessable Entity.

For the JSON envelope path, the required fields are digest, storageUri, and a positive sizeBytes. Any missing required field returns 422.

Create a workflow definition

The handler accepts either the canonical JSON shape or a YAML document whose top-level keys match the JSON. The Desktop sends YAML for the upload path; the API examples in the workflow guide use application/yaml because the checked-in fixtures are YAML.

curl --fail-with-body \
  -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @workflow.json \
  "$AKOFLOW_API_URL/workflow-definitions/"

The POST /workflow-definitions/import/ route accepts the same body and is the endpoint the Desktop calls when the user imports a YAML file. The handler validates the workflow version against the registered activities, runtimes, capabilities, and simulation profiles; missing required fields, unsupported capabilities, and unknown activity IDs return 422. See Workflow definitions for the schema.

Create an execution run

The handler accepts an application/json or application/yaml envelope that contains the run id, the referenced plan id, the mode, and a snapshot of the workflow and infrastructure that the supervisor will use. The versioned files under examples/simulation/execution-request.yaml and examples/kind/requests/execution-request.yaml are the canonical envelopes.

curl --fail-with-body \
  -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  -H 'Content-Type: application/yaml' \
  --data-binary @examples/simulation/execution-request.yaml \
  "$AKOFLOW_API_URL/execution-runs/"

Submission is asynchronous. The success status is 202 Accepted with the queued run projection. Validation failures from the supervisor (unknown plan id, missing required profile field, runtime not bound) return 422. A run id that already exists returns 409 Conflict.

Query provenance with read-only SQL

The handler accepts a single read-only statement with positional parameters. Statements that touch more than one entity or that are not parseable as a read return 400.

curl --fail-with-body \
  -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "statement": "SELECT id, makespan_seconds, transferred_bytes FROM execution_runs WHERE id = ?",
    "params": ["simulation-example-run-v1"]
  }' \
  "$AKOFLOW_API_URL/provenance/sql/"

Use POST /provenance/sql/explain/ to inspect the planned query before running it. The result is a JSON projection of the rows; there is no envelope.