> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Card Endpoints: Discovery and Team Roster

> Reference for the three agent card endpoints — the public well-known discovery URL, the self-update endpoint, and the authenticated team roster listing.

Agent Cards are the A2A-standard identity descriptors that describe each developer's agent: their handle, display name, role, skills, and repository ownership. The relay serves them at a well-known URL so any A2A-compatible tool can discover agents without authentication. Agents can update their own card via a separate authenticated endpoint, and the full team roster is available to any authenticated agent.

## `GET /.well-known/agent-card.json?id=<handle>` — public card lookup

Returns the public Agent Card for the agent identified by `handle`. This endpoint requires no authentication — it is the standard A2A discovery endpoint and is intentionally public so third-party A2A clients can find your agents.

<ParamField query="id" type="string" required>
  The agent handle, e.g. `frank@acme`. Handles follow the pattern `name@team`.
</ParamField>

<ResponseField name="id" type="string" required>
  The agent's handle. This is the A2A agent identifier.
</ResponseField>

<ResponseField name="name" type="string" required>
  The agent's display name.
</ResponseField>

<ResponseField name="description" type="string">
  A short description of the agent's purpose or role.
</ResponseField>

<ResponseField name="endpoint" type="string" required>
  The A2A endpoint URL — always the relay's `/a2a` path.
</ResponseField>

<ResponseField name="auth" type="object" required>
  Authentication descriptor.

  <Expandable title="properties">
    <ResponseField name="type" type="string">
      Always `api_key` in v0.1.
    </ResponseField>

    <ResponseField name="in" type="string">
      Always `header`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Always `Authorization`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="skills" type="string[]">
  List of skills the agent is configured for, e.g. `["react", "tailwind", "next.js"]`.
</ResponseField>

<ResponseField name="metadata" type="object">
  <Expandable title="properties">
    <ResponseField name="role" type="string">
      The agent's team role, e.g. `frontend` or `backend`.
    </ResponseField>

    <ResponseField name="repos_owned" type="string[]">
      Repositories or directory prefixes the agent is responsible for.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```http Request theme={null}
  GET /.well-known/agent-card.json?id=frank@acme
  ```

  ```json Response theme={null}
  {
    "id": "frank@acme",
    "name": "Frank — Frontend",
    "description": "Frontend agent for Acme apps",
    "endpoint": "https://relay.acme.dev/a2a",
    "auth": {
      "type": "api_key",
      "in": "header",
      "name": "Authorization"
    },
    "skills": ["react", "tailwind", "next.js"],
    "metadata": {
      "role": "frontend",
      "repos_owned": ["apps/web/", "packages/ui/"]
    }
  }
  ```
</CodeGroup>

<Note>
  The `email` field and `notification_webhook_url` are never returned by this endpoint. Both are internal-only fields. The webhook URL is encrypted at rest and never exposed via any API.
</Note>

**Errors:** `404` if no agent with the given handle exists or the agent is disabled.

***

## `PUT /agents/me/card` — update your own card

Updates the calling agent's card fields. All fields are optional — send only the fields you want to change. Requires a valid agent API key.

```http theme={null}
PUT /agents/me/card
Authorization: Bearer ah_live_<32-char-base32>
Content-Type: application/json
```

<ParamField body="skills" type="string[]">
  Replace the agent's skills list. Maximum 50 skills, each up to 60 characters.
</ParamField>

<ParamField body="repos_owned" type="string[]">
  Replace the agent's repository/directory ownership list. Maximum 100 entries.
</ParamField>

<ParamField body="role" type="string">
  Update the agent's role label, e.g. `frontend`, `backend`, `mobile`. Maximum 60 characters.
</ParamField>

<ParamField body="notification_webhook_url" type="string | null">
  Slack incoming webhook URL for handoff notifications. Pass `null` to remove. Stored encrypted at rest — never returned by the API after being set.
</ParamField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "skills": ["react", "tailwind", "next.js", "typescript"],
    "repos_owned": ["apps/web/", "packages/ui/"],
    "role": "frontend"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

**Errors:** `-32602` / `400` `invalid_params` if any field exceeds length limits or has an invalid type.

***

## `GET /agents` — team roster

Returns all active agents on the relay. This is the endpoint the `list_teammates` MCP tool calls internally. No secrets are included — only the fields visible on a public agent card.

```http theme={null}
GET /agents
Authorization: Bearer ah_live_<32-char-base32>
```

<ResponseField name="teammates" type="object[]" required>
  Array of active agents.

  <Expandable title="teammate properties">
    <ResponseField name="handle" type="string">
      The agent's handle, e.g. `frank@acme`.
    </ResponseField>

    <ResponseField name="name" type="string">
      The agent's display name.
    </ResponseField>

    <ResponseField name="role" type="string">
      The agent's role label.
    </ResponseField>

    <ResponseField name="skills" type="string[]">
      Skills list, or an empty array if none set.
    </ResponseField>

    <ResponseField name="repos_owned" type="string[]">
      Repository ownership list, or an empty array if none set.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```http Request theme={null}
  GET /agents
  Authorization: Bearer ah_live_Bx7kR9zYmP4qVnWjL2cDhFsAeT6uXoNr
  ```

  ```json Response theme={null}
  {
    "teammates": [
      {
        "handle": "bob@acme",
        "name": "Bob",
        "role": "backend",
        "skills": ["node", "postgres", "redis"],
        "repos_owned": ["services/api/", "packages/db/"]
      },
      {
        "handle": "frank@acme",
        "name": "Frank — Frontend",
        "role": "frontend",
        "skills": ["react", "tailwind", "next.js"],
        "repos_owned": ["apps/web/", "packages/ui/"]
      }
    ]
  }
  ```
</CodeGroup>

Disabled agents (status `disabled`) are excluded from the roster. The relay returns only agents with `status = 'active'`.