Update A2A Routing

Endpoint

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/a2a-routing/

uyarı

This endpoint returns HTTP 400 for API proxies whose type is not A2A — a2aRouting can only be set on A2A proxies. To create a new A2A proxy in one call, use Create A2A API Proxy — this endpoint only updates the routing config of a proxy that already exists.

Authentication

Requires a Personal API Access Token.

Permission: API_MANAGEMENT × MANAGE (consistent with the Update AI Routing and mcp-routing endpoints).

Header

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	A2A API Proxy name

Request Body

The body is the full A2aRouting object — it replaces the proxy's current A2A routing configuration.

Full JSON Body Example (AGENT_EXPOSE)

{
  "routingMode": "AGENT_EXPOSE",
  "agentCard": {
    "descriptionOverride": "Answers customer support questions",
    "inputModes": ["text/plain"],
    "outputModes": ["text/plain"],
    "skills": [
      {
        "id": "answer-question",
        "name": "Answer Question",
        "description": "Answers a free-form question",
        "tags": ["support"]
      }
    ]
  },
  "pushSettings": null,
  "identityAcl": [],
  "callQuota": null
}

bilgi

AGENT_EXPOSE additionally requires the proxy's aiRouting to be configured (the exposed agent is served by an LLM provider through AI routing) — enforced by validation.

Full JSON Body Example (PASSTHROUGH, inline backend agent)

{
  "routingMode": "PASSTHROUGH",
  "backendServers": [
    {
      "name": "partner-agent",
      "endpoint": "https://agents.partner.example.com/a2a",
      "authScheme": "BEARER",
      "bearerToken": "raw-token-in-transit-only",
      "driftPolicy": "WARN_ONLY"
    }
  ],
  "allowedSkillNames": ["translate", "summarize"],
  "identityAcl": [],
  "callQuota": null
}

Field Reference

Field	Type	Description
routingMode	string	AGENT_EXPOSE (expose an Apinizer-hosted agent backed by aiRouting) or PASSTHROUGH (proxy one or more external backend A2A agents)
protocolVersion	string	A2A protocol version
agentCard	object	AGENT_EXPOSE only. AgentCard settings served at /.well-known/agent-card.json — descriptionOverride, inputModes, outputModes, skills[] (id, name, description, tags); the agent name comes from the proxy itself
pushSettings	object	Push-notification (task update) settings
backendServers	array	PASSTHROUGH only. The only way to configure a backend target — there is no reference-based alternative. Inline backend agent definitions — up to 10. Each entry is a full connection object: name, endpoint, authentication (authScheme/bearerToken, or OAuth2 client-credentials fields, or mTLS settings), driftPolicy (WARN_ONLY | FAIL_CLOSED), allowPrivateNetworkEgress. Server-managed fields (id, discoveredSkills, health/drift state) are always read from the agent's own persisted state — a client-supplied value for any of them is ignored. Multiple entries aggregate behind one endpoint for discovery only (see Multi-Target Aggregation) — sending an actual task requires exactly one configured agent. PASSTHROUGH mode requires at least one entry
allowedSkillNames	array	PASSTHROUGH skill filter — only listed backend skills are exposed
identityAcl	array	Per-principal allow rules (principalType: CREDENTIAL | ROLE | ORGANIZATION)
callQuota	object	Call quota config (scoped counters)
tokenForwardSettings	object	Explicit opt-in client-token forwarding. The legacy forwardClientToken boolean is a no-op (logged with WARN) — forwarding happens only through these settings

Behavior

• The configuration is validated (McpA2aRoutingValidator) before save; invalid mode/field combinations (including AGENT_EXPOSE without aiRouting) return HTTP 400.
• Updating an existing backendServers entry: to update rather than replace an agent, send back the id from a prior read unchanged — a matching id is treated as an update and its server-managed fields (discovered skills, health, drift) are preserved. An entry whose id is blank, or doesn't match anything currently persisted, is always treated as brand-new: a fresh id is minted server-side.
• Secret fields on backendServers entries (bearerToken, clientSecret) follow the platform's standard blank-preserves-existing convention: omit the field to keep the currently stored secret, send a non-blank value to replace it.
• endpoint on a backendServers entry is the address tasks are relayed to. Its agent card is looked for at that same address first and, if the card isn't served there, at the standard discovery path below it (.../.well-known/agent-card.json) — so an agent's task endpoint and its card URL are both accepted.
• GetTask/CancelTask in PASSTHROUGH mode resolve against the gateway's own task records first and are relayed to the backend agent when the task ID isn't one of them (a non-streaming Passthrough task is created and owned by that agent). With more than one entry in backendServers they return an error instead of guessing which agent owns the task — see Task Submission and Lifecycle.
• Every environment the proxy is currently deployed to is marked redeploy required — redeploy to activate the new configuration.

Response

Success Response (200 OK)

{
  "result": {
    "success": true
  }
}

Error Responses

Status	Condition
400	Blank apiProxyName, empty body, proxy not found, proxy is not an A2A proxy, backendServers exceeds 10 entries, or validation failure
401	Invalid or missing token
500	Unexpected server error

Related Documentation

• Create A2A API Proxy
• Update MCP Routing
• Discover A2A Skills for a Policy
• API Proxies
• A2A Gateway — concepts, inline agent model, governance