Publish a flow definition

POST

/v1/flows

const url = 'https://example.com/v1/flows';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"id":"example","version":"example","name":"example","description":"example","projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","nodes":[{"id":"example","kind":"tool","ref":"example","config":{}}],"edges":[{"id":"example","from":"example","to":"example","when":{},"policy":{}}],"maxParallelism":1,"metadata":{}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/flows \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "version": "example", "name": "example", "description": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "nodes": [ { "id": "example", "kind": "tool", "ref": "example", "config": {} } ], "edges": [ { "id": "example", "from": "example", "to": "example", "when": {}, "policy": {} } ], "maxParallelism": 1, "metadata": {} }'

Body is a full flow JSON. Server validates via @kindgi/flow.loadFlow before persisting. Node handler code is not uploaded through this route.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body^required

application/json

Full flow definition. Validated server-side via @kindgi/flow.loadFlow — validation failures return 400 validation-failed with the issue list under details.issues.

object

required

string

version

required

string

name

string

description

string

projectId

required

Project this belongs to (its content scope). Required: missing, or not a project in the caller’s tenant → 400 bad-input.

string format: uuid

nodes

required

Array<object>

object

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

required

string

from

required

Source node id or $start sentinel.

string

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

Responses

201

Flow published.

application/json

object

flowId

required

string

version

required

string

Example^generated

{
  "flowId": "example",
  "version": "example"
}

400

Validation failed (see details.issues); or projectId isn’t a project id (a UUID). Or reference-out-of-scope: a tool, agent or subflow it names isn’t registered in its project, its org or the tenant (details.issues, each with path, kind and id).

application/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.

application/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

The body’s projectId names no project of this tenant (project-not-found).

application/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"
  }
}

409

flow-already-registered: that (id, version) is taken. Or flow-project-mismatch: the flow’s versions live in another project (a flow belongs to the project its first version was published into and never moves, though in a tenant with environment orders a version may be made in another project of that project’s order; the message doesn’t name the project). Or environment-takes-promotions: the project is a later environment of an environment order, which takes builds only by promotion from the one before it; publish in the order’s first environment instead (details.firstProjectId, when you can read that project; details.position, the project’s place from 0). Nothing is written. Or registry-read-only: this registry takes no writes (under kindgi dev, the pack’s files are the source); the message says what to do instead.

application/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"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

application/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"
  }
}

429

rate-limit-exceeded with details.limit: "schema-compile-time", on a server with a compile budget (Kindgi Cloud): this tenant’s schemas spent details.budgetMs compiling in the last 60 seconds. Nothing was stored; Retry-After says when to send it again.

application/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"
  }
}

500

Server error (unmapped domain code or framework crash).

application/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"
  }
}

Publish a flow definition

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Examplegenerated

400

Examplegenerated

401

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

429

Examplegenerated

500

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated