# A2A API

> Each deployment as an agent other agents can call, over the A2A protocol.

Send `Authorization: Bearer vk_test_...` on every call.

## `GET /v1/a2a/{deployment_id}/.well-known/agent-card.json`

Its own page: [GET /v1/a2a/{deployment_id}/.well-known/agent-card.json](https://vestra.ai/developers/reference/api/a2a/get-v1-a2a-deployment-id-well-known-agent-card-json.md)

What this deployment does and how to authenticate, for other agents to discover.

No key: anyone may call it. On the card: [`mcp`](https://vestra.ai/developers/mcp.md). Every call here is a checked sample.

### Request

Path:

- `deployment_id` (`string`, required): The deployment's id (`dep_...`). The /v1/deployments routes also take its name.

### Answers 200

- `name` (`string`): The deployment's name. Limits: at least 1 character.
- `description` (`string`): The deployment's description, then how to talk to Bash. Limits: at least 1 character.
- `supportedInterfaces` (`object[]`): Where and how to call it. Limits: at least 1 item.
  - `url` (`string (URL)`): The deployment's A2A address.
  - `protocolBinding` (`string`): How to call it: JSONRPC.
  - `protocolVersion` (`string`): The A2A version it speaks. Example: `1.0`.
- `provider` (`object`, may be absent): Who runs the agent.
  - `url` (`string (URL)`): The provider's site.
  - `organization` (`string`): The provider's name: Vestra.
- `version` (`string`): The deployment's live version, as a string. Limits: at least 1 character.
- `documentationUrl` (`string (URL)`, may be absent): Where its documentation is.
- `capabilities` (`object`): What it can do.
  - `streaming` (`boolean`, may be absent): Whether it streams: true.
  - `pushNotifications` (`boolean`, may be absent): Whether it sends push notifications: false, use a webhook endpoint instead.
  - `extendedAgentCard` (`boolean`, may be absent): Whether it has an extended card: false.
- `securitySchemes` (`map of object`, may be absent): How a caller proves who it is, by name.
- `securityRequirements` (`object[]`, may be absent): Which schemes a call must use.
  - `schemes` (`map of object`): The schemes a call needs, by name.
- `defaultInputModes` (`string[]`): What it takes: text/plain and application/json. Limits: at least 1 item.
- `defaultOutputModes` (`string[]`): What it answers with: text/plain and application/json. Limits: at least 1 item.
- `skills` (`object[]`): What the agent offers: one skill, talking to Bash. Limits: at least 1 item.
  - `id` (`string`): The skill's id.
  - `name` (`string`): The skill's name.
  - `description` (`string`): What it does.
  - `tags` (`string[]`): Words to find it by.
  - `examples` (`string[]`, may be absent): Requests it handles, as examples.
  - `inputModes` (`string[]`, may be absent): What it takes.
  - `outputModes` (`string[]`, may be absent): What it answers with.

### Code

**HTTP**

```bash
# Connect any MCP client. Point it at this URL with your key. Over plain HTTP the endpoint speaks JSON-RPC,
# and it needs both types in the Accept header. tools/list shows the tools it offers.
curl "$VESTRA_BASE_URL/v1/mcp" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

# Connect an agent that speaks A2A. Each deployment has an agent card, and reading it needs no key.
curl "$VESTRA_BASE_URL/v1/a2a/dep_4kq/.well-known/agent-card.json"
```

**MCP**

```json
{
  "mcpServers": {
    "vestra": {
      "type": "http",
      "url": "https://api-staging.vestra.ai/v1/mcp",
      "headers": { "Authorization": "Bearer vk_test_..." }
    }
  }
}
```

**TypeScript, Python, CLI**: No sample in your language for this route, so here it is over HTTP.

## `POST /v1/a2a/{deployment_id}`

Its own page: [POST /v1/a2a/{deployment_id}](https://vestra.ai/developers/reference/api/a2a/post-v1-a2a-deployment-id.md)

A2A JSON-RPC: send a message, stream, get, list or cancel. Push notifications are not offered; subscribe to webhooks instead. An A2A exchange is a conversation; an A2A task is its work.

Your API key, scope `runtime` or `all`. On the card: [`mcp`](https://vestra.ai/developers/mcp.md). Over HTTP it is made from the contract: fill in each {…} and every value.

### Request

Path:

- `deployment_id` (`string`, required): The deployment's id (`dep_...`). The /v1/deployments routes also take its name.

Headers:

- `Vestra-User` (`string`): Your id for the user this call acts for.

### Answers 200

Its answer is a protocol of its own: its line's page says more.

### Code

**HTTP**

```bash
curl -X POST "$VESTRA_BASE_URL/v1/a2a/{deployment_id}" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**TypeScript, Python, CLI, MCP**: No sample in your language for this route, so here it is over HTTP.