API d'administration : contrat OpenAPI

typeobligatoirestring

Format : uri

titleobligatoirestring

statusobligatoireinteger

detailstring

instancestring

codeobligatoirestring

Exemple : not_found

request_idstring

trace_idstring

errorslist<FieldError>

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

grpcGRPCStatus

Cité par : GET /configPOST /simulatePOST /simulate/mqtt

methodobligatoirestring

Exemple : GET

hostobligatoirestring

Exemple : api.example.com

pathobligatoirestring

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

headersmap<string>

identitySimulatedIdentity

Cité par : POST /simulate

issuerobligatoirestring

subjectobligatoirestring

tenantstring

scopeslist<string>

roleslist<string>

Cité par : SimulationRequest

packetobligatoirestring

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

topicobligatoirestring

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

qosinteger

Bornes : valeur ≥ 0, ≤ 2Défaut : 0

response_topicstring

An MQTT 5 Response Topic

identityobligatoireMQTTSimulatedIdentity

Cité par : POST /simulate/mqtt

kindobligatoirestring

Valeurs : 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).

Cité par : MQTTSimulationRequest

verdictobligatoirestring

Valeurs : 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.Valeurs : 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.

Cité par : POST /simulate/mqtt

verdictobligatoirestring

Valeurs : served refused

statusobligatoireinteger

codestring

The refusal's problem code.

operationstring

upstreamstring

chainlist<string>

appliedlist<string>

outboundOutbound

Cité par : POST /simulate

pathobligatoirestring

querystring

headersobligatoiremap<list<string>>

Cité par : SimulationResult

statusobligatoirestring

Valeurs : ok

uptime_secobligatoireinteger

Cité par : GET /healthz

statusobligatoirestring

Valeurs : ready not ready

operationsinteger

Operations served, when ready.

reasonstring

Why not, when not ready.

Cité par : GET /readyz

codeobligatoireinteger

Exemple : 5

statusobligatoirestring

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

messagestring

detailslist<object>

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

Cité par : Problem

fieldobligatoirestring

Exemple : query.limit

ruleobligatoirestring

For a human.

codeobligatoirestring

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

Cité par : Problem

operationobligatoirestring

identitiesobligatoirelist<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.

versionobligatoireinteger

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

buildobligatoireBuildInfo

config_versionobligatoirestring

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

catalogobligatoirelist<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.

chainsobligatoiremap<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.

Cité par : GET /config

replicaobligatoirestring

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

capacityobligatoireinteger

Events kept per kind.

eventsobligatoirelist<Event>

Cité par : GET /events

atobligatoirestring

Format : date-time

kindobligatoirestring

Valeurs : reload breaker shedding delegation

reasonstring

Delegation - why the chain was refused.Valeurs : 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

Valeurs : loaded applied rejected unchanged

versionstring

causestring

upstreamstring

fromstring

Valeurs : closed half_open open

tostring

Valeurs : closed half_open open

statestring

Valeurs : started stopped

Cité par : EventLog

replicaobligatoirestring

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

capacityobligatoireinteger

observability.sparkplug.max_nodes.

offline_retention_secondsobligatoireinteger

observability.sparkplug.offline_retention

droppedobligatoireinteger

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

nodesobligatoirelist<SparkplugNode>

hostsobligatoirelist<SparkplugHost>

Cité par : GET /sparkplug/nodes

tenantobligatoirestring

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

edge_nodeobligatoirestring

stateobligatoirestring

Valeurs : online offline moved unknown

sinceobligatoirestring

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_gapsobligatoireinteger

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

bd_seq_gapsobligatoireinteger

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

protocol_versionobligatoirestring

5 or 3.1.1; empty for an unknown node.

authobligatoirestring

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

devices_onlineobligatoireinteger

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

devices_totalobligatoireinteger

Its devices kept since its birth.

devicesobligatoirelist<SparkplugDevice>

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

devices_truncatedobligatoireboolean

Past observability.sparkplug.max_devices_per_node

commandsobligatoireSparkplugCommands

Cité par : SparkplugNodes

deviceobligatoirestring

stateobligatoirestring

Valeurs : online offline

Cité par : SparkplugNode

admittedobligatoireinteger

Format : int64

refusedobligatoireinteger

Format : int64

Cité par : SparkplugNode

tenantobligatoirestring

host_idobligatoirestring

stateobligatoirestring

Valeurs : online offline

sinceobligatoirestring

Format : date-time

Cité par : SparkplugNodes

replicaobligatoirestring

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

capacityobligatoireinteger

Errors kept per kind.

write_limitobligatoireinteger

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

kindsobligatoirelist<ErrorKindCount>

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

errorsobligatoirelist<GatewayError>

Cité par : GET /errors

kindobligatoireErrorKind

droppedobligatoireinteger

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

Cité par : ErrorLog

Valeurs : upstream refused internal

Cité par : ErrorKindCountGatewayError

atobligatoirestring

Format : date-time

kindobligatoireErrorKind

operationobligatoirestring

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>.Bornes : longueur ≤ 128

statusobligatoireinteger

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

codeobligatoirestring

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.

stageobligatoirestring

Where the error was written, derived from its code.Valeurs : 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.Valeurs : dial_refused dns tls timeout reset circuit_open bulkhead buffer_full rejected status other

duration_msobligatoirenumber

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

trace_idstring

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

Cité par : ErrorLog

versionobligatoirestring

Exemple : v1.0.0

commitobligatoirestring

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

Cité par : EffectiveConfig

operation_idobligatoirestring

methodobligatoirestring

pathobligatoirestring

The path template, never a concrete URL.

hostsobligatoirelist<string>

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

upstreamobligatoirestring

summarystring

tagslist<string>

deprecatedobligatoireboolean

securityobligatoirelist<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.

builtinobligatoireboolean

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.Valeurs : 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_msobligatoireinteger

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.Motif : ^[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.Valeurs : sse websocket grpc

security_detailobligatoirelist<CatalogAlternative>

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

effective_rate_classobligatoirestring

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.Valeurs : critical normal sheddable

validationstring

x-flexway-validation when declared; absent - the host's.Valeurs : 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).

paramsobligatoirelist<CatalogParam>

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

bodyobject

The request body in short; absent - none declared.

responsesobligatoirelist<CatalogResponse>

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

Cité par : EffectiveConfig

teamobligatoirestring

Bornes : longueur ≤ 128

contactstring

Bornes : longueur ≤ 128

Cité par : CatalogEntry

anonymousobligatoireboolean

The empty alternative {}: no identity needed.

schemesobligatoirelist<object>

scopeslist<string>

roleslist<string>

Cité par : CatalogEntry

nameobligatoirestring

inobligatoirestring

Valeurs : path query header

requiredobligatoireboolean

typestring

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

formatstring

Cité par : CatalogEntry

statusobligatoirestring

mediaobligatoirelist<string>

Cité par : CatalogEntry

agentobligatoirestring

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

cardobligatoirestring

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

upstreamobligatoirestring

bindingsobligatoiremap<string>

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

methodsobligatoiremap<string>

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

verifyobligatoirestring

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

streamingobligatoireboolean

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_pathobligatoirestring

Where the gateway publishes the agent's card.

statusobligatoireobject

toolsobligatoirelist<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>)".

Cité par : EffectiveConfig

ttl_secondsobligatoireinteger

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

scopeobligatoirestring

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

policystring

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

hostsobligatoirelist<string>

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

Cité par : CatalogEntry

methodobligatoirestring

pathobligatoirestring

Cité par : CatalogEntry

stepsobligatoirelist<object>

removedlist<Attachment & object>

replacedlist<object>

Cité par : EffectiveConfig

levelobligatoirestring

Valeurs : global host route operation

sourcestring

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

Cité par : ChainDetail

importobligatoirestring

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

fragmentobligatoirestring

The fragment's own name.

versionobligatoirestring

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

enforcedobligatoireboolean

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

importobligatoirestring

fragmentobligatoirestring

versionobligatoirestring

digestobligatoirestring

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

pathobligatoirestring

The file

signatureobligatoirestring

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

requires_uncheckedobligatoireboolean

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.

requiresobligatoireobject

definitionsobligatoirelist<string>

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

enforcedobligatoirelist<string>

The enforced definitions

unusedobligatoirelist<string>

The imported definitions no chain names - never an error.

Cité par : EffectiveConfig