Skip to main content
API docs by Redocly

Converge API (1.0.0)

Download OpenAPI specification:Download

Get API v1 cluster members

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ClusterInfoOutputBody.json",
  • "members": [
    ]
}

Get API v1 kinds

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ListKindsOutputBody.json",
  • "kinds": [
    ]
}

Get API v1 kinds manifests

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ListManifestsOutputBody.json",
  • "manifests": [
    ]
}

Put API v1 kinds by kind manifest

path Parameters
kind
required
string

Resource kind.

Request Body schema: application/json
required
config_schema
any
description
string
finalizer_name
string
kind
required
string
kind_version
required
integer <int64> [ 1 .. 32767 ]

Web-API version (v1, v2, …; 1–32767). REQUIRED — no implicit v1 default.

max_inflight
integer <int64>
max_transient_attempts
integer <int64>
orphan_grace_secs
integer <int64>
required
Array of objects or null (ReactionDecl)
resync_interval_secs
integer <int64>
resync_recomposes
boolean
spec_schema
any
status_schema
any
task_deadline_secs
integer <int64>
type
string
Value: "manifest"

Optional self-describing tag; must be "manifest" if set. Ignored for routing.

Responses

Request samples

Content type
application/json
{
  • "config_schema": null,
  • "description": "string",
  • "finalizer_name": "string",
  • "kind": "string",
  • "kind_version": 1,
  • "max_inflight": 0,
  • "max_transient_attempts": 0,
  • "orphan_grace_secs": 0,
  • "reactions": [
    ],
  • "resync_interval_secs": 0,
  • "resync_recomposes": true,
  • "spec_schema": null,
  • "status_schema": null,
  • "task_deadline_secs": 0,
  • "type": "manifest"
}

Response samples

Content type
application/json
{}

Get API v1 kinds by kind schema

path Parameters
kind
required
string

Resource kind.

query Parameters
kind_version
integer <int64>

Web-API version (v1, v2, …) whose /docs schema refs to resolve; omitted resolves the LOWEST published version, an over-large value clamps to the highest. A /docs display convenience only (no data is written), so it has no v1 default.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/KindSchemaOutputBody.json",
  • "config_schema": null,
  • "config_schema_ref": "string",
  • "default_config": null,
  • "operational": {
    },
  • "spec_schema": null,
  • "spec_schema_ref": "string",
  • "status_schema": null,
  • "status_schema_ref": "string"
}

Put API v1 kinds by kind versions by kind version config

path Parameters
kind
required
string

Resource kind.

kind_version
required
integer <int64> [ 1 .. 32767 ]

Web-API version (v1, v2, …; 1–32767) whose operational config to edit.

Request Body schema: application/json
required
max_inflight
required
integer <int64> >= 0

Global in-flight cap across all pods; 0 = uncapped.

max_transient_attempts
required
integer <int64> >= 0

Consecutive transient reconcile failures before a task dead-letters (marked terminal); 0 = unbounded (retry forever).

orphan_grace_seconds
required
integer <int64> >= 0

Grace window in seconds before a composer-dropped child of this kind is torn down; 0 = prune immediately.

resync_interval_seconds
required
integer <int64> >= 0

Drift re-check interval in seconds; 0 = disabled.

resync_recomposes
boolean

Whether a resync also re-runs the composer (only meaningful when resync is enabled).

retired
boolean

RETIRE this web-API version: freeze NEW creates/flips onto it (422) while existing resources keep reconciling so they can drain/migrate off. Runtime-editable; effective values (not deltas), so send the current value to preserve it.

task_deadline_seconds
required
integer <int64> >= 0

Per-task timeout in seconds; 0 = no deadline.

Responses

Request samples

Content type
application/json
{
  • "max_inflight": 0,
  • "max_transient_attempts": 0,
  • "orphan_grace_seconds": 0,
  • "resync_interval_seconds": 0,
  • "resync_recomposes": true,
  • "retired": true,
  • "task_deadline_seconds": 0
}

Response samples

Content type
application/json
{}

Delete API v1 kinds by kind versions by kind version manifest

path Parameters
kind
required
string

Resource kind.

kind_version
required
integer <int64> [ 1 .. 32767 ]

Web-API version (v1, v2, …; 1–32767) to delete.

Responses

Response samples

Content type
application/json
{}

Get API v1 kinds by kind versions by kind version manifest

path Parameters
kind
required
string

Resource kind.

kind_version
required
integer <int64> [ 1 .. 32767 ]

Web-API version (v1, v2, …; 1–32767).

Responses

Response samples

Content type
application/json
{}

Get API v1 providerconfigs

query Parameters
kind
string

Optional exact consumer-kind filter; omit for all.

kind_version
integer <int64> [ 0 .. 32767 ]

Optional exact consumer-kind version (v1, v2, …; 1–32767) filter; 0/omit for any.

name
string

Optional case-insensitive substring match on name.

default
string
Enum: "true" "false"

Optional is_default filter; omit for any, true/false to filter.

limit
integer <int64> [ 1 .. 500 ]
Default: 100
offset
integer <int64> >= 0
Default: 0

Responses

Response samples

Content type
application/json
{}

Post API v1 providerconfigs

Request Body schema: application/json
required
data
string

base64-encoded opaque provider bundle (e.g. a zip of Starlark .star files); decoded into the config's data bytes. Bounded by the 50 MiB request-body cap (~37 MiB decoded).

is_default
boolean

True = this (kind, version)'s single live-reconfigurable DEFAULT; false = a CUSTOM override referenced via provider_config_ref.

kind
required
string non-empty

Consumer kind this config parameterises.

kind_version
required
integer <int64> [ 1 .. 32767 ]

Consumer kind web-API version (v1, v2, …; 1–32767). REQUIRED — no implicit v1 default.

name
required
string non-empty

Global config name; provider_config_ref resolves by it.

spec
required
any

Config document; shape is the kind's config_schema (GET /api/kinds/{kind}/schema).

type
string
Value: "providerconfig"

Optional self-describing tag; must be "providerconfig" if set. Ignored for routing.

Responses

Request samples

Content type
application/json
{
  • "data": "string",
  • "is_default": true,
  • "kind": "string",
  • "kind_version": 1,
  • "name": "string",
  • "spec": null,
  • "type": "providerconfig"
}

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ProviderConfigBody.json",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": "string",
  • "is_default": true,
  • "kind": "string",
  • "kind_version": 0,
  • "name": "string",
  • "owner_kind": "string",
  • "owner_name": "string",
  • "spec": null,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete API v1 providerconfigs by name

path Parameters
name
required
string

Config name.

Responses

Response samples

Content type
application/json
{}

Get API v1 providerconfigs by name

path Parameters
name
required
string

Config name.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ProviderConfigBody.json",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": "string",
  • "is_default": true,
  • "kind": "string",
  • "kind_version": 0,
  • "name": "string",
  • "owner_kind": "string",
  • "owner_name": "string",
  • "spec": null,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get API v1 raw resources by kind by name manifest

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name.

Responses

Response samples

Content type
application/problem+json
{}

Get API v1 raw resources by kind by name spec by generation

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name.

generation
required
integer <int64>

Authored generation to download

Responses

Response samples

Content type
application/problem+json
{}

Get API v1 raw resources by kind by name status

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name.

Responses

Response samples

Content type
application/problem+json
{}

Get API v1 reactor bindings

Responses

Response samples

Content type
application/json
{}

Post API v1 reactor bindings

Request Body schema: application/json
required
enabled
boolean

Whether the subscription is active. Defaults true.

label_match
any

Optional label predicate: {} (or omitted) matches all; else the resource's labels must contain these.

name
required
string non-empty

Unique subscription name (operator-chosen; opaque).

reactor
required
string non-empty

Reactor kind whose reaction runs when the subscription fires (the broker ships STAGE_REACT to a worker advertising this kind). Must be a registered reactor kind, distinct from the watched kind.

reactor_version
integer <int64> >= 0

Optional: pin the reactor's web-API version (v1, v2, …). 0/omitted resolves the reactor's highest published version at claim time.

transition
required
string
Enum: "created" "synced" "degraded" "failed" "deleted"

Lifecycle transition that fires the subscription.

type
string
Value: "reactorbinding"

Optional self-describing tag; must be "reactorbinding" if set. Ignored for routing.

watch_kind
required
string non-empty

Resource kind to watch.

watch_kind_version
integer <int64> >= 0

Optional: fire only for this web-API version (v1, v2, …) of the watched kind. 0/omitted = all versions.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "label_match": null,
  • "name": "string",
  • "reactor": "string",
  • "reactor_version": 0,
  • "transition": "created",
  • "type": "reactorbinding",
  • "watch_kind": "string",
  • "watch_kind_version": 0
}

Response samples

Content type
application/json
{}

Delete API v1 reactor bindings by name

path Parameters
name
required
string

Binding name.

Responses

Response samples

Content type
application/json
{}

Get API v1 resources

query Parameters
owner
Array of strings or null

Scope to these owners' children; each is kind/name. Repeat for a union.

kind
Array of strings or null
kv
Array of strings or null

Repeatable (kind, version) pair filter as kind/vN (e.g. vpc/v1). Exact per-pair match.

kind_version
integer <int64> [ 0 .. 32767 ]

DEPRECATED single-version filter (use kv=kind/vN); 0/omitted = any.

phase
Array of strings or null
Enum: "Ready" "Reconciling" "Degraded" "Failed" "Deleting" "Orphaned" "Quarantined"

Return rows in ANY of these readiness phases (repeat the param to union; omit for all).

name
string
label
Array of strings or null
limit
integer <int64> [ 1 .. 500 ]
Default: 100
cursor
string

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ListResourcesPageMultiOutputBody.json",
  • "owners": [
    ],
  • "resources": [
    ]
}

Post API v1 resources

Request Body schema: application/json
required
kind
required
string

Resource kind.

kind_version
required
integer <int64> [ 1 .. 32767 ]

Web-API version (v1, v2, …; 1–32767). REQUIRED — no implicit v1 default. A change from the resource's current kindVersion is a breaking flip.

object

Full label set (string→string); applied wholesale — omitting a key removes it.

name
required
string non-empty

Resource name; identity together with kind.

provider_config_ref
string

Name of a providerconfig resource to attach as a per-resource config override.

spec
required
any

Per-kind desired-state spec.

type
string
Value: "resource"

Optional self-describing tag; must be "resource" if set. Ignored for routing.

Responses

Request samples

Content type
application/json
{
  • "kind": "string",
  • "kind_version": 1,
  • "labels": {
    },
  • "name": "string",
  • "provider_config_ref": "string",
  • "spec": null,
  • "type": "resource"
}

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ResourceFull.json",
  • "conditions": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "deletion_requested_at": "2019-08-24T14:15:22Z",
  • "failure_attempts": 0,
  • "failure_terminal": true,
  • "finalizers": [
    ],
  • "generation": 0,
  • "health_ok": true,
  • "is_ready": true,
  • "kind": "string",
  • "kind_version": 0,
  • "labels": {
    },
  • "manifest_drift": true,
  • "max_transient_attempts": 0,
  • "name": "string",
  • "owner_kind": "string",
  • "owner_name": "string",
  • "phase": "string",
  • "provider_config": {
    },
  • "root_kind": "string",
  • "root_name": "string",
  • "spec": null,
  • "status": null,
  • "synced_gen": 0,
  • "uid": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "work": {
    }
}

Get API v1 resources roots

query Parameters
kind
Array of strings or null

Repeatable kind filter (any version of these kinds).

kv
Array of strings or null

Repeatable (kind, version) pair filter as kind/vN (e.g. vpc/v1). Exact per-pair match.

kind_version
integer <int64> [ 0 .. 32767 ]

DEPRECATED single-version filter (use kv=kind/vN); 0/omitted = any version. Only meaningful alongside a kind filter.

name
string

ILIKE substring filter.

created_after
string <date-time>

RFC3339.

created_before
string <date-time>

RFC3339.

updated_after
string <date-time>

RFC3339.

updated_before
string <date-time>

RFC3339.

gen_min
integer <int64>

Min generation.

gen_max
integer <int64>

Max generation.

count_min
integer <int64>

Min child count.

count_max
integer <int64>

Max child count.

phase
string
Enum: "Ready" "Reconciling" "Degraded" "Failed" "Deleting" "Orphaned" "Quarantined"

Only return rows in this readiness phase.

limit
integer <int64> [ 1 .. 500 ]
Default: 50
cursor
string

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ListRootsPageOutputBody.json",
  • "roots": [
    ]
}

Get API v1 resources summary

query Parameters
owner
Array of strings or null

Scope to these owners; each is kind/name. Repeat for a union.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/SummaryScopedOutputBody.json",
  • "by_kind": [
    ],
  • "owners": [
    ],
  • "totals": {
    }
}

Delete API v1 resources by kind by name

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Responses

Response samples

Content type
application/json
{}

Get API v1 resources by kind by name

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ResourceFull.json",
  • "conditions": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "deletion_requested_at": "2019-08-24T14:15:22Z",
  • "failure_attempts": 0,
  • "failure_terminal": true,
  • "finalizers": [
    ],
  • "generation": 0,
  • "health_ok": true,
  • "is_ready": true,
  • "kind": "string",
  • "kind_version": 0,
  • "labels": {
    },
  • "manifest_drift": true,
  • "max_transient_attempts": 0,
  • "name": "string",
  • "owner_kind": "string",
  • "owner_name": "string",
  • "phase": "string",
  • "provider_config": {
    },
  • "root_kind": "string",
  • "root_name": "string",
  • "spec": null,
  • "status": null,
  • "synced_gen": 0,
  • "uid": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "work": {
    }
}

Get API v1 resources by kind by name changes

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
since
string <date-time>

Only resources whose updated_at > this.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ChangesOutputBody.json",
  • "owner": {
    },
  • "resources": [
    ]
}

Get API v1 resources by kind by name children

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
kind
Array of strings or null
kv
Array of strings or null

Repeatable (kind, version) pair filter as kind/vN (e.g. vpc/v1). Exact per-pair match.

kind_version
integer <int64> [ 0 .. 32767 ]

DEPRECATED single-version filter (use kv=kind/vN); 0/omitted = any.

phase
Array of strings or null
Enum: "Ready" "Reconciling" "Degraded" "Failed" "Deleting" "Orphaned" "Quarantined"

Return rows in ANY of these readiness phases (repeat the param to union; omit for all).

name
string
label
Array of strings or null
limit
integer <int64> [ 1 .. 500 ]
Default: 100
cursor
string

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ListResourcesPageOutputBody.json",
  • "owner": {
    },
  • "resources": [
    ]
}

Get API v1 resources by kind by name dependencies

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/ListDependenciesOutputBody.json",
  • "dependencies": [
    ]
}

Get API v1 resources by kind by name events

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
cursor
string

Opaque pagination token for paging older events.

limit
integer <int64> [ 1 .. 500 ]
Default: 100

Responses

Response samples

Content type
application/json
{}

Get API v1 resources by kind by name graph

path Parameters
kind
required
string

Owner resource kind.

name
required
string

Owner resource name.

query Parameters
limit
integer <int64> [ 1 .. 1000 ]
Default: 500

Max nodes AND max edges returned.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/GraphOutputBody.json",
  • "edges": [
    ],
  • "nodes": [
    ],
  • "owner": {
    }
}

Get API v1 resources by kind by name ops

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
state
Array of strings or null
Enum: "pending" "running" "succeeded" "failed"

Filter by state; repeat for a union.

limit
integer <int64> [ 1 .. 500 ]
Default: 100

Responses

Response samples

Content type
application/json
{}

Post API v1 resources by kind by name ops

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Request Body schema: application/json
required
input
any

Verb-specific input.

verb
required
string non-empty

Operator verb name (must be a declared verb of the kind).

Responses

Request samples

Content type
application/json
{
  • "input": null,
  • "verb": "string"
}

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/OperationDTO.json",
  • "attempts": 0,
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": null,
  • "output": null,
  • "requested_at": "2019-08-24T14:15:22Z",
  • "requested_by": "string",
  • "state": "string",
  • "uid": "string",
  • "verb": "string"
}

Get API v1 resources by kind by name ops by op UID

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

op_uid
required
string

Opaque operation handle.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/OperationDTO.json",
  • "attempts": 0,
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": null,
  • "output": null,
  • "requested_at": "2019-08-24T14:15:22Z",
  • "requested_by": "string",
  • "state": "string",
  • "uid": "string",
  • "verb": "string"
}

Post API v1 resources by kind by name quarantine

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Responses

Response samples

Content type
application/json
{}

Post API v1 resources by kind by name reconcile

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Responses

Response samples

Content type
application/json
{}

Post API v1 resources by kind by name rollback

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Request Body schema: application/json
required
generation
required
integer <int64>

The authored generation to check out.

Responses

Request samples

Content type
application/json
{
  • "generation": 0
}

Response samples

Content type
application/json
{}

Get API v1 resources by kind by name spec history

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
limit
integer <int64> [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{}

Get API v1 resources by kind by name subgraph

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
ancestor_depth
integer <int64> [ 0 .. 10 ]
Default: 3
descendant_depth
integer <int64> [ 0 .. 10 ]
Default: 1
limit
integer <int64> [ 1 .. 1000 ]
Default: 200

Responses

Response samples

Content type
application/json
{}

Get API v1 resources by kind by name summary

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/SummaryOutputBody.json",
  • "by_kind": [
    ],
  • "owner": {
    },
  • "totals": {
    }
}

Get API v1 resources by kind by name topology

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
group_by
Array of strings or null
path
Array of strings or null

key:value pairs already drilled.

cursor
string
limit
integer <int64> [ 1 .. 500 ]
Default: 200

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/TopologyOutputBody.json",
  • "buckets": [
    ],
  • "group_by": [
    ],
  • "next_key": "string",
  • "owner": {
    },
  • "path": [
    ]
}

Get API v1 resources by kind by name topology keys

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
limit
integer <int64> [ 1 .. 500 ]
Default: 100

Responses

Response samples

Content type
application/json
{}

Get API v1 resources by kind by name topology leaves

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

query Parameters
path
Array of strings or null
cursor
string
limit
integer <int64> [ 1 .. 500 ]
Default: 200

Responses

Response samples

Content type
application/json
{
  • "$schema": "https://example.com/schemas/TopologyLeavesOutputBody.json",
  • "owner": {
    },
  • "resources": [
    ]
}

Post API v1 resources by kind by name unquarantine

path Parameters
kind
required
string

Resource kind.

name
required
string

Resource name; identity together with kind.

Responses

Response samples

Content type
application/json
{}

Get API v1 version

Responses

Response samples

Content type
application/json
{}