Skip to content
Kindgi

List flows

View as Markdown
GET
/v1/flows
curl --request GET \
  --url 'https://example.com/v1/flows?limit=25&scopeKind=tenant&inherit=true&includeRetired=false' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated list of the latest version per flow id. Optional ?name= filters by prefix on flow id. A retired flow (every version unregistered) is listed only with ?includeRetired=true, as its highest version with unregisteredAt, so it can be found and a version reinstated.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

name
string

Prefix match on flow id.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string
Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId
string
>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

inherit
boolean
default: true

Default true. false = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/…).

includeRetired
boolean

When true, retired items (every version unregistered) are listed too, each as its highest version with that version’s unregisteredAt. Default: false (items with an active version only).

Responses

Section titled “Responses”

200

Section titled “200”

Page of flows.

Media typeapplication/json
object
data
required
Array<object>
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
nextCursor

Opaque cursor for the next page. Absent when hasMore: false.

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "nodes": [
        {
          "kind": "tool"
        }
      ],
      "derivedFrom": {
        "reason": "pins-changed"
      }
    }
  ]
}

400

Section titled “400”

Malformed query parameter.

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also