Admin API: OpenAPI contract

typerequiredstring

Format : uri

titlerequiredstring

statusrequiredinteger

detailstring

instancestring

coderequiredstring

Example : not_found

request_idstring

trace_idstring

errorslist<FieldError>

invalid_request only - each field that broke the contract, and the rule it broke.

grpcGRPCStatus

Cited by : GET /configPOST /simulatePOST /simulate/mqtt

methodrequiredstring

Example : GET

hostrequiredstring

Example : api.example.com

pathrequiredstring

With its query, as a client would send it.Example : /orders/42?status=open

headersmap<string>

identitySimulatedIdentity

Cited by : POST /simulate

issuerrequiredstring

subjectrequiredstring

tenantstring

scopeslist<string>

roleslist<string>

Cited by : SimulationRequest

packetrequiredstring

will: a CONNECT's will, judged as a PUBLISH.Values : publish subscribe will

topicrequiredstring

A topic name (publish, will) or a filter (subscribe), $share/<group>/ included.

qosinteger

Bounds : value ≥ 0, ≤ 2Default : 0

response_topicstring

An MQTT 5 Response Topic

identityrequiredMQTTSimulatedIdentity

Cited by : POST /simulate/mqtt

kindrequiredstring

Values : token api_key certificate

idstring

api_key: the key's id; certificate: the auth.mtls client's id.

issuerstring

subjectstring

tenantstring

token: its tenant claim; a key's or a certificate's is the configuration's.

scopeslist<string>

claimsmap<string>

token: the claims a claim:<name> binding reads.

certificateobject

certificate: the fields a cert:<field> binding reads - cn, serial, fingerprint, ou, o, san.dns, san.uri, san.ip, san.email (lists for the multi-valued ones).

Cited by : MQTTSimulationRequest

verdictrequiredstring

Values : served refused

reason_codeinteger

The MQTT 5 reason code a refusal answers (0x87 = 135...).

causestring

The refusal's cause - the label of flexway.mqtt.packets.Values : authentication not_authorized binding wildcard payload_invalid quota packet_too_large upstream_unavailable

operationstring

upstreamstring

writtenstring

The topic or filter as written toward the broker - a $share/ group in the tenant's name.

qosinteger

The QoS the broker sees - a subscription's granted at the operation's qos_max at most.

client_idstring

The client id the broker sees for this identity.

Cited by : POST /simulate/mqtt

verdictrequiredstring

Values : served refused

statusrequiredinteger

codestring

The refusal's problem code.

operationstring

upstreamstring

chainlist<string>

appliedlist<string>

outboundOutbound

Cited by : POST /simulate

pathrequiredstring

querystring

headersrequiredmap<list<string>>

Cited by : SimulationResult

statusrequiredstring

Values : ok

uptime_secrequiredinteger

Cited by : GET /healthz

statusrequiredstring

Values : ready not ready

operationsinteger

Operations served, when ready.

reasonstring

Why not, when not ready.

Cited by : GET /readyz

coderequiredinteger

Example : 5

statusrequiredstring

The code's name - what a client switches on.Example : NOT_FOUND

messagestring

detailslist<object>

The status details in the proto3 JSON mapping; a type the gateway does not know keeps only its "@type".

Cited by : Problem

fieldrequiredstring

Example : query.limit

rulerequiredstring

For a human.

coderequiredstring

The JSON Schema keyword broken, or the operator's name for it (errors.field_codes).

Cited by : Problem

operationrequiredstring

identitiesrequiredlist<object>

The alternatives of its security - token (with its scopes), apikey, certificate.

transactionsboolean

A send operation that opens the transactional producer.

admin_scopestring

The scope a token carries to administer the topic.

decrypt_scopestring

A receive operation's scope a token carries to read the topic's encrypted fields in clear.

versionrequiredinteger

The configuration schema's version - not the gateway's, see build.

buildrequiredBuildInfo

config_versionrequiredstring

Short digest of the bytes served.

config_digeststring

Short semantic digest of the configuration served: the decoded flexway.yaml in a canonical form and each contract under the path flexway.yaml writes, the API key store excluded. The same whatever the mount path or the chart's rendering - what flexway validate prints, and what a pipeline or the console expects to see served after a merge.

last_reloadobject

catalogrequiredlist<CatalogEntry>

fragmentslist<PolicyFragment>

The policy fragments imported, in the order policies.fragments writes them; empty without one. Their definitions are also under policies.definitions, as <import>/<name>.

agentsobject

The agents section as loaded, when one is configured: mcp (path, resources, servers and clients) and delegation (max_depth, max_age, introspection).

kafkaobject

The Kafka listener's virtual clusters (1.6.0), read from the AsyncAPI contract in force; absent without listeners.kafka. Its bounds and quotas are under listeners.kafka, its signals' settings under observability.kafka. Never a key, a certificate, a tenant's name.

devicesobject

The MQTT device listener's operations (1.7.0), read from the AsyncAPI contract in force; absent without listeners.mqtt. Its bounds are under listeners.mqtt, its signals' settings under observability.mqtt. Never a key, a certificate, a tenant's name.

kmsobject

The KMS of field-level encryption on the Kafka listener (1.6.0), as loaded: its kind, host and key name - per_tenant_key when the name holds {tenant} -, the previous keys records may still name (previous_keys, read only), timeout, rotation, cache and tenant_calls bounds, and its kind's section with references (${VAR}, file:/path) and mounted file paths - never a secret, never a key. The epochs in use and the keys cached are runtime state, in the metrics flexway.kafka.dek.epoch and flexway.kafka.dek.cached.

listenersobject

The listeners beside HTTP, as loaded: kafka - its addresses, bounds (max_connections, max_connections_per_tenant, max_tenant_in_flight_bytes, on_tenant_budget_exceeded...) and, when declared, quotas (client and tenant producer_byte_rate, consumer_byte_rate, request_rate; window, max_throttle, quota) - what the console shows as the bounds in force; mqtt - its address, TLS files, websocket, advertised_address, every bound (max_connections, max_connections_per_ip, max_connection_rate_per_tenant, topic_alias_maximum...), device and tenant rates, the tenant's quota policy, failover (mode, reason, server_reference, redirect_above, handover_timeout, drain_spread).

mcp_federationmap<FederationState>

Live, not the configuration: each federated MCP server's last discovery, by server name - read at each GET /config, since discovery moves on its own.

a2aobject

The governed A2A agents (1.2.0): what each serves and how - from the configuration in force, read at each GET /config. Absent when no agent is declared. Never a key, never a token.

chainsrequiredmap<map<ChainDetail>>

By host ("*" for every host without contracts of its own), then by operationId.

effective_chainsmap<list<string>>

The chain's policy names alone, by operationId, on hosts not configured otherwise.

policiesobject

The policies section as loaded - definitions and chains, secret-looking values masked.

aiobject

The ai section as loaded, when one is configured: budget (monthly_tokens, daily_tokens, monthly_eur, soft), overrides (match, backend, caps) and backends - the quotas the console compares a tenant's consumption with.

Cited by : GET /config

replicarequiredstring

The answering process's host name - the pod's name.

capacityrequiredinteger

Events kept per kind.

eventsrequiredlist<Event>

Cited by : GET /events

atrequiredstring

Format : date-time

kindrequiredstring

Values : reload breaker shedding delegation

reasonstring

Delegation - why the chain was refused.Values : depth age revoked widened unverifiable

clientstring

Delegation - the agent's client: a declared client_id, _undeclared, none or _other.

tenantstring

Delegation - the tenant, bounded as on the metrics.

actorslist<string>

Delegation - the agents of act, the current one first; at most max_depth + 1, 256 characters each.

depthinteger

Delegation - the chain's measured depth.

age_secondsinteger

Delegation - the chain's measured age; -1 when the token carries no time it started.Format : int64

max_depthinteger

Delegation - the depth bound in force for the operation.

max_age_secondsinteger

Delegation - the age bound in force for the operation.Format : int64

operationstring

Delegation - the operation (REST or a tool's replay); absent at the MCP connection.

toolstring

Delegation - the tool; absent for a REST request and at the MCP connection.

scopeslist<string>

Delegation - the presented token's scopes that a contract or a federated server declares.

resultstring

Values : loaded applied rejected unchanged

versionstring

causestring

upstreamstring

fromstring

Values : closed half_open open

tostring

Values : closed half_open open

statestring

Values : started stopped

Cited by : EventLog

replicarequiredstring

The answering process's host name - the pod's name.

capacityrequiredinteger

observability.sparkplug.max_nodes.

offline_retention_secondsrequiredinteger

observability.sparkplug.offline_retention

droppedrequiredinteger

Nodes and host applications not kept since the start - the table was full of online nodes.Format : int64

nodesrequiredlist<SparkplugNode>

hostsrequiredlist<SparkplugHost>

Cited by : GET /sparkplug/nodes

tenantrequiredstring

The node's group - the tenant it is bound to.

edge_noderequiredstring

staterequiredstring

Values : online offline moved unknown

sincerequiredstring

When the node took its state on this replica.Format : date-time

bd_seqinteger

The bdSeq of its last NBIRTH here; absent when none was read.Format : int64

will_bd_seqinteger

The bdSeq of the will (NDEATH) its connection registered; absent when none was read.Format : int64

seq_gapsrequiredinteger

Messages whose seq was not the next since its birth here.Format : int64

bd_seq_gapsrequiredinteger

Births whose bdSeq was not their will's.Format : int64

protocol_versionrequiredstring

5 or 3.1.1; empty for an unknown node.

authrequiredstring

The mode of identity of its connection - certificate, token, api_key; empty for an unknown node.

devices_onlinerequiredinteger

Its devices online (DBIRTH without a later DDEATH) since its birth.

devices_totalrequiredinteger

Its devices kept since its birth.

devicesrequiredlist<SparkplugDevice>

Its devices (DBIRTH, DDEATH) since its birth, sorted by id - listed only when the node is asked for (node); empty otherwise.Bounds : items ≤ 100000

devices_truncatedrequiredboolean

Past observability.sparkplug.max_devices_per_node

commandsrequiredSparkplugCommands

Cited by : SparkplugNodes

devicerequiredstring

staterequiredstring

Values : online offline

Cited by : SparkplugNode

admittedrequiredinteger

Format : int64

refusedrequiredinteger

Format : int64

Cited by : SparkplugNode

tenantrequiredstring

host_idrequiredstring

staterequiredstring

Values : online offline

sincerequiredstring

Format : date-time

Cited by : SparkplugNodes

replicarequiredstring

The answering process's host name - the pod's name.

capacityrequiredinteger

Errors kept per kind.

write_limitrequiredinteger

Errors detailed per second and per kind; past it they are counted in dropped.

kindsrequiredlist<ErrorKindCount>

Each kind's count of the errors it could not detail since the start.

errorsrequiredlist<GatewayError>

Cited by : GET /errors

kindrequiredErrorKind

droppedrequiredinteger

Errors past the write limit since the start.Format : int64

last_dropped_atstring

The last of them; absent when none was dropped.Format : date-time

Cited by : ErrorLog

Values : upstream refused internal

Cited by : ErrorKindCountGatewayError

atrequiredstring

Format : date-time

kindrequiredErrorKind

operationrequiredstring

The operationId; _unmatched when no route matched.

upstreamstring

The upstream's name in the configuration; absent when the request never reached one.

tenantstring

The verified identity's tenant; absent for an anonymous caller. A tenant longer than 128 characters is never truncated: it is written sha256:<hex digest of the whole tenant>.Bounds : length ≤ 128

statusrequiredinteger

The HTTP status answered - for a refusal answered in gRPC's status, the one its code maps to.

coderequiredstring

The problem code the gateway wrote; upstream_status for an upstream's 5xx relayed as is - never a code or a text of the upstream.

stagerequiredstring

Where the error was written, derived from its code.Values : routing identity authorization policies validation protection upstream response internal

causestring

Upstream errors only - why the upstream failed, a closed set; never the network's text.Values : dial_refused dns tls timeout reset circuit_open bulkhead buffer_full rejected status other

duration_msrequirednumber

Time from the request's arrival to its answer.Format : double

trace_idstring

The request's trace when it was sampled.Pattern : ^[0-9a-f]{32}$

Cited by : ErrorLog

versionrequiredstring

Example : v1.0.0

commitrequiredstring

Short commit; empty when the build did not say.Example : 9438ab3

Cited by : EffectiveConfig

operation_idrequiredstring

methodrequiredstring

pathrequiredstring

The path template, never a concrete URL.

hostsrequiredlist<string>

"*" stands for every host without contracts of its own.

upstreamrequiredstring

summarystring

tagslist<string>

deprecatedrequiredboolean

securityrequiredlist<list<string>>

The alternatives, each the schemes it combines; an empty one is anonymous access.

rate_classstring

toolstring

The tool name when offered to agents (x-flexway-tool).

tool_unattendedboolean

Present only with tool: false when the tool is kept for agents a person supervises (x-flexway-tool with unattended false), true otherwise.

builtinrequiredboolean

An operation the gateway declares itself (ai.*).

protocolstring

grpc for a method of a Protobuf service (1.1.0): path is its gRPC path. Absent: HTTP.Values : grpc

restlist<CatalogRoute>

The REST routes of a gRPC method (google.api.http), the same operation translated.

cachelist<CatalogCache>

The operation's response cache (1.2.0), one entry per distinct rule - from its x-flexway-cache, or a cache policy attached around it. Absent: nothing of it is cached.

timeout_msrequiredinteger

The operation's total budget in milliseconds: its x-flexway-timeout, otherwise its upstream's timeout. An external-call of the request phase consumes it; the upstream gets what is left.Format : int64

ownerCatalogOwner

sunsetstring

The date a deprecated operation is withdrawn (x-flexway-sunset), YYYY-MM-DD.Pattern : ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

streamstring

How the operation answers when it is not one response - a text/event-stream, a protocol switch (101), a streaming gRPC method. The vocabulary of flexway.streams.open. Absent: one response.Values : sse websocket grpc

security_detailrequiredlist<CatalogAlternative>

The alternatives of security, in the same order, with each scheme's kind and what it requires.

effective_rate_classrequiredstring

The rate-limit class the operation counts against: rate_class when declared, read for a gRPC method without side effects, otherwise by method.

contractstring

The contract file that declares it, as flexway.yaml writes the path; absent for the gateway's own operations.

prioritystring

x-flexway-priority when declared.Values : critical normal sheddable

validationstring

x-flexway-validation when declared; absent - the host's.Values : full params off

delegationobject

x-flexway-delegation when declared; a bound absent is the configuration's.

added_scopeslist<string>

The scopes x-flexway-scopes adds to every token alternative (already in security_detail).

paramsrequiredlist<CatalogParam>

The parameters in short - never a schema nor an example.

bodyobject

The request body in short; absent - none declared.

responsesrequiredlist<CatalogResponse>

The declared responses in short - status as written ("200", "2XX", "default") and media types.

Cited by : EffectiveConfig

teamrequiredstring

Bounds : length ≤ 128

contactstring

Bounds : length ≤ 128

Cited by : CatalogEntry

anonymousrequiredboolean

The empty alternative {}: no identity needed.

schemesrequiredlist<object>

scopeslist<string>

roleslist<string>

Cited by : CatalogEntry

namerequiredstring

inrequiredstring

Values : path query header

requiredrequiredboolean

typestring

The schema's type; "a|b" for a list of types.

formatstring

Cited by : CatalogEntry

statusrequiredstring

mediarequiredlist<string>

Cited by : CatalogEntry

agentrequiredstring

The agent's name in operation ids (a2a.<agent>.<Method>) and metrics.

cardrequiredstring

The declared card, as flexway.yaml writes its path.

upstreamrequiredstring

bindingsrequiredmap<string>

The bindings served (JSONRPC, HTTP+JSON), each with the gateway's address.

methodsrequiredmap<string>

The methods served, each with its rate class - free debits nothing.

verifyrequiredstring

How the upstream's own card is verified - none until card verification is built.Values : none

streamingrequiredboolean

max_streamsinteger

The streams one caller may hold open to the agent, per replica.

max_task_durationstring

The longest a stream of the agent runs, as a Go duration.

card_pathrequiredstring

Where the gateway publishes the agent's card.

statusrequiredobject

toolsrequiredlist<string>

The tools discovered, under their names on the surface.

descriptionsmap<string>

What each tool says of itself, by name, 512 characters at most - a third party's text.

not_servedlist<string>

Tools announced and not served, their name taken: "<name> (taken by <who>)".

Cited by : EffectiveConfig

ttl_secondsrequiredinteger

The longest a response is kept; the upstream's Cache-Control may shorten it.Format : int64

scoperequiredstring

public: anonymous callers; subject: keyed by tenant and subject.Values : public subject

policystring

The cache policy it comes from; absent for the contract's x-flexway-cache.

hostsrequiredlist<string>

The hosts it applies on; "*" alone: every host.

Cited by : CatalogEntry

methodrequiredstring

pathrequiredstring

Cited by : CatalogEntry

stepsrequiredlist<object>

removedlist<Attachment & object>

replacedlist<object>

Cited by : EffectiveConfig

levelrequiredstring

Values : global host route operation

sourcestring

The host, the route motif, x-flexway-policies, or policies.fragments for the enforced head of the chain.

Cited by : ChainDetail

importrequiredstring

The import name flexway.yaml gives it - the prefix of its definitions.

fragmentrequiredstring

The fragment's own name.

versionrequiredstring

The fragment's semantic version - informative; the digest says what runs.

enforcedrequiredboolean

At the head of every chain: never removed, never replaced.

importrequiredstring

fragmentrequiredstring

versionrequiredstring

digestrequiredstring

sha256:<hex>, the digest pinned - equal to the file's.

pathrequiredstring

The file

signaturerequiredstring

How the file was proven beyond its digest: none in this version.Values : none

requires_uncheckedrequiredboolean

true when the fragment requires a gateway version and a development build (dev) loaded it without comparing - said here and in the log, never refused.

requiresrequiredobject

definitionsrequiredlist<string>

The imported names, <import>/<name>.

enforcedrequiredlist<string>

The enforced definitions

unusedrequiredlist<string>

The imported definitions no chain names - never an error.

Cited by : EffectiveConfig