Create A2A API Proxy

Endpoint

POST /apiops/projects/{projectName}/apiProxies/a2a/{apiProxyName}/

Creates an API proxy of type A2A. See A2A Gateway for the concepts — Expose Agent vs Passthrough, task lifecycle, and the inline-agent model.

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Permission: API_MANAGEMENT × MANAGE.

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. Overrides any name carried in the body.

Request Body

Field	Type	Required	Description
relativePath	string	Yes	Client-facing path the gateway listens on (for example `/a2a/support`)
description	string	No	Free-text description
routingMode	string	No	`AGENT_EXPOSE` or `PASSTHROUGH`. Defaults to `AGENT_EXPOSE` when omitted — unlike the MCP create endpoint, which has no implicit default
protocolVersion	string	No	A2A protocol version; blank keeps the null-safe default

Minimal Body Example (AGENT_EXPOSE, the default)

{
  "relativePath": "/a2a/support"
}

bilgi

When routingMode resolves to AGENT_EXPOSE (explicitly, or by omission), the endpoint also seeds an empty aiRouting on the created proxy — AGENT_EXPOSE requires it (the exposed agent is served by an LLM provider through AI routing) and validation would otherwise reject the save. Configure the actual LLM provider/model afterward with Update AI Routing, the same "empty routing now, configured later" pattern Create AI API Proxy uses.

agentCard/skills (AGENT_EXPOSE) aren't part of this create call — configure them afterward with Update A2A Routing.

uyarı

This endpoint has no backendServers field, and PASSTHROUGH mode requires at least one inline backend agent entry — sending "routingMode": "PASSTHROUGH" here always fails with HTTP 400 (a2aRouting.backendServersRequired). There is no name-based reference that can satisfy this requirement instead. To end up with a PASSTHROUGH proxy, create it with the default AGENT_EXPOSE first, then switch it over in a single Update A2A Routing call that carries routingMode: "PASSTHROUGH" and backendServers together.

Two-Step PASSTHROUGH Setup

1. Create the proxy (POST /apiops/projects/{projectName}/apiProxies/a2a/{apiProxyName}/):

{
  "relativePath": "/a2a/partner",
  "description": "Forwards tasks to a partner agent"
}

2. Switch it to PASSTHROUGH with an inline backend agent (PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/a2a-routing/):

{
  "routingMode": "PASSTHROUGH",
  "backendServers": [
    {
      "name": "partner-agent",
      "endpoint": "https://agents.partner.example.com/a2a",
      "authScheme": "BEARER",
      "bearerToken": "raw-token-in-transit-only"
    }
  ]
}

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": false,
    "detailList": []
  }
}

Creation does not deploy the proxy. Deploy it separately with POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/environments/{environmentName}/.

Error Responses

HTTP Code	Condition
400	`apiProxyName` is empty, request body is missing, `relativePath` is empty, an API proxy with the same name already exists in the project, or `routingMode` is `PASSTHROUGH` (this endpoint carries no `backendServers`, so the required-backend check always fails)
401	Token is missing or invalid
500	Unexpected server error

Notes and Warnings

routingMode defaults to AGENT_EXPOSE, unlike the MCP create endpoint's fail-closed (required, no default) contract — mirrors the Manager UI's own A2A proxy create flow.
Agents are configured inline, not by reference — there is no reference option. This create call has no backendServers field, so a PASSTHROUGH target can't be set in one step: create the proxy (defaults to AGENT_EXPOSE), then add one or more inline A2A agents through Update A2A Routing's backendServers field, in the same call that switches routingMode to PASSTHROUGH.
Proxy-level settings apply the same as any other proxy type — CORS, cache, error templates, client route, trace and traffic-log settings.
Policies (including A2A Call (LLM) / A2A Call (Fixed) on other proxies) are attached the same way as for any other proxy, through POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/.

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Request Body​

Minimal Body Example (AGENT_EXPOSE, the default)​

Two-Step PASSTHROUGH Setup​

Response​

Success Response (200 OK)​

Error Responses​

Notes and Warnings​

Related Documentation​