Fetch the latest version of a flow

GET

/v1/flows/{flowId}

curl --request GET \
  --url https://example.com/v1/flows/example \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

An item more than one project serves (an environment order carries it to later environments) answers its newest active version that can run in a project the caller reads, and 404 when there is none. projectId narrows that to one project. An item with one project answers its latest active version.

Authorizations

• bearerAuth

Parameters

Path Parameters

flowId

required

string

FlowId — dotted namespace (acme.ingest-invoice).

Query Parameters

projectId

string format: uuid

The newest active version that can run in this project, a project the caller reads; 404 when there’s none, or when the caller doesn’t read the project. An item with one project answers its latest version for its own project and 404 for any other; one that names no project (under kindgi dev, a pack’s agents, flows and tools) answers it for any. With authorization off, the caller reads every project. An older runtime ignores it and answers the latest version.

Responses

200

Flow.

Media typeapplication/json

object

id

required

FlowId — dotted namespace (e.g. ingest.contract-pdf).

string

version

required

Semver.

string

projectId

The flow’s project: every version of a flow is in the one project. Absent when the runtime doesn’t record it: a pack kindgi dev serves from disk, or a runtime before Kindgi 0.1.6.

string format: uuid

name

string

description

string

nodes

required

Array<object>

object

id

required

string

kind

required

string

Allowed values: tool agent loop fanout subgraph

ref

Handler reference for leaf nodes.

string

config

object

key

additional properties

any

key

additional properties

any

edges

required

Array<object>

object

id

required

string

from

required

Source node id or $start sentinel.

string

to

required

Destination node id or $end sentinel.

string

when

Optional predicate expression evaluated at edge dispatch time (see @kindgi/flow).

object

key

additional properties

any

policy

Optional per-edge runtime policy (retry, timeoutMs, …).

object

key

additional properties

any

maxParallelism

integer

>= 1

metadata

object

key

additional properties

any

pins

The exact tool and agent versions a flow version runs: its lockfile. Set by the runtime when the version is published, never in the publish body: each tool the flow runs, and each agent it runs at no named version, resolves once to its latest version then, which every run of that flow version uses. Absent on a version published before pins existed (it binds the latest versions per run).

object

tools

required

Tool id → exact version.

object

key

additional properties

string

agents

required

Agent id → exact version, for agent nodes that name no version.

object

key

additional properties

string

pinsDigest

Set by the runtime with pins: sha256:<hex> of the pins’ canonical JSON (sorted keys, no whitespace).

string

/^sha256:[0-9a-f]{64}$/

derivedFrom

Set by the runtime on an agent or flow version a deploy registered in place of the definition’s version, which was registered already with other pins or content (versions never change). Never in the publish body.

object

version

required

The version the definition names.

string

reason

required

pins-changed: a block it uses has a new version; unpinned: the definition’s version was published before pins existed; version-taken: the definition’s version holds another definition; edited: derived from version with some data-block pins swapped (POST /v1/agents/{agentId}/versions).

string

Allowed values: pins-changed unpinned version-taken edited

label

For edited: a short label for the version.

string

by

For edited: who derived it (user:<id>).

string

proposalId

For edited: the improvement proposal it was derived for. Such a version serves no scope until a promotion makes it live.

string

unregisteredAt

Present only on an unregistered version (GET …/versions/{version} reads those too). Unregister stops a version being chosen, not the pins that hold it: a new run naming it is refused, while a resumed run and a published version that pins it still run it.

string format: date-time

Example

{
  "nodes": [
    {
      "kind": "tool"
    }
  ],
  "derivedFrom": {
    "reason": "pins-changed"
  }
}

400

projectId is not a project id (a UUID).

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No flow with that id under this tenant.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also

• GET /v1/flows/{flowId}/versions: List versions of a flow
• GET /v1/flows/{flowId}/versions/{version}: Fetch a specific flow version
• POST /v1/flows/{flowId}/versions/{version}/unregister: Unregister a specific flow version
• POST /v1/flows/{flowId}/versions/{version}/reinstate: Reinstate a specific tombstoned flow version
• Every error code