# API Reference — every endpoint

Base URL: `https://agilityos.co`

All public agent endpoints are listed here with their request/response shapes. For protocol-specific details (A2A envelopes, MCP JSON-RPC), see [Recommendation Agents reference](/docs/recommendation-agents).

## Discovery

### `GET /.well-known/agents.json`

Domain-level index of all active agents.

**Response:**
```json
{
  "schema_version": "1.0",
  "operator": "Agility Automations",
  "operator_url": "https://agilityautomations.com",
  "total": 5,
  "agents": [
    {
      "url": "savoir",
      "name": "Savoir",
      "business": "Savoir Faire",
      "industry": "fragrance",
      "description": "...",
      "type": "connoisseur",
      "rich_card": "...",
      "a2a_card": "...",
      "a2a_endpoint": "...",
      "mcp_manifest": "..."
    }
  ]
}
```

### `GET /api/public/agents/<slug>/agent.json`

Per-agent rich card (custom AgilityOS format).

### `GET /api/public/agents/<slug>/.well-known/agent.json`

Per-agent A2A AgentCard (Google spec).

### `GET /api/public/agents/<slug>/agent-card.json`

Alias for the A2A AgentCard above.

### `GET /api/public/agents/<slug>/agents.txt`

robots.txt-style hint with all endpoints.

### `GET /api/public/agents/<slug>/mcp`

MCP tool manifest.

## Invocation

### `POST /api/public/agents/<slug>/recommend`

REST recommend endpoint. See [Recommendation Agents reference](/docs/recommendation-agents) for full schema.

**Body:**
```json
{
  "goal": "string (required)",
  "budget": 80,
  "constraints": ["string"],
  "maxResults": 5,
  "callerMode": "b2c | b2b"
}
```

### `POST /api/public/agents/<slug>/a2a`

Google A2A JSON-RPC endpoint. Methods: `tasks/send`, `message/send`, `tasks/sendSubscribe` (returns one-shot result).

### `POST /api/public/agents/<slug>/mcp/invoke`

MCP JSON-RPC endpoint. Methods: `initialize`, `tools/list`, `tools/call`, `ping`.

## Attribution

### `POST /api/public/agents/<slug>/track-conversion`

Report a conversion. Requires `conversionToken` from `/recommend` response.

**Body:**
```json
{
  "productId": "p_<hash>",
  "productName": "...",
  "value": 79,
  "currency": "USD",
  "sessionId": "...",
  "conversionToken": "<expiry>.<sig>",
  "metadata": {}
}
```

### `POST /api/public/recommendation/register`

Register a caller agent for elevated tier + attribution.

**Body:**
```json
{
  "name": "...",
  "contactEmail": "...",
  "description": "..."
}
```

**Response:** `{ ok, callerId, callerKey, tier, rateLimit, usage }` — `callerKey` shown ONCE.

## Voice agents (separate system)

Voice agents have their own authenticated agent-api. See [Voice Agents](/docs/voice-agents) for the full reference. Public chat embed at `/api/public/agents/<slug>/chat` (existing UI surface) is unchanged.

## Common errors

| HTTP | Code | Meaning |
|---|---|---|
| 400 | `goal_required` | `/recommend` body missing `goal` |
| 400 | `agent_not_indexed` | Agent has no product catalog |
| 400 | `agent_not_configured` | Agent missing instructions |
| 401 | `invalid_conversion_token` | Token failed verification |
| 404 | `agent_not_found` | Bad slug |
| 404 | `session_not_found` | sessionId doesn't match a real recommend call |
| 429 | `RATE_LIMITED` | Tier exceeded |
| 500 | `recommend_failed` | LLM or vector store error |

## Rate limits

See [Authentication](/docs/auth#tiers) for the full tier table.