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.

Discovery

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

Domain-level index of all active agents.

Response:

{
  "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 for full schema.

Body:

{
  "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:

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

`POST /api/public/recommendation/register`

Body:

{
  "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 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 for the full tier table.