# Agent Discovery

Public endpoints for AI agents to discover products and capabilities.

---

Discovery endpoints let AI agents find your AVCodex agent and browse its product catalog. These endpoints are public. No authentication required.

## Agent Card

```
GET /acp/{appId}/.well-known/agent.json
```

Returns metadata about your AVCodex agent and its ACP capabilities. This follows the `.well-known` convention used in agent-to-agent protocols, making it easy for external AI agents to discover what your agent offers and how to interact with it.

### Example request

```bash
curl https://app.avcodex.com/acp/{appId}/.well-known/agent.json
```

### Response

```json
{
  "name": "AVCodex Pro Services",
  "description": "An AVCodex agent that handles room audits, programming hours, and remote commissioning",
  "url": "https://app.avcodex.com/acp/{appId}",
  "version": "1.0.0",
  "capabilities": {
    "products": true,
    "checkout": true
  },
  "endpoints": {
    "products": "https://app.avcodex.com/acp/{appId}/products",
    "checkout": "https://app.avcodex.com/acp/{appId}/checkout_sessions"
  },
  "authentication": {
    "type": "bearer",
    "description": "Requires ACP API key (acp_*) in Authorization header for checkout operations. Product discovery is public."
  }
}
```

### Response fields

| Field             | Type           | Description                                            |
|-------------------|----------------|--------------------------------------------------------|
| `name`            | string         | Your AVCodex agent's name.                             |
| `description`    | string or null | Your AVCodex agent's description.                      |
| `url`             | string         | Base URL for this agent's ACP endpoints.               |
| `version`         | string         | ACP protocol version.                                  |
| `capabilities`    | object         | Supported ACP features.                                |
| `endpoints`       | object         | Full URLs for products and checkout endpoints.         |
| `authentication` | object         | Authentication requirements.                           |

## List products

```
GET /acp/{appId}/products
```

Returns all active products in your catalog. Inactive or deleted products are excluded.

### Example request

```bash
curl https://app.avcodex.com/acp/{appId}/products
```

### Response

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Room Audit Report",
      "description": "Generate a detailed audit of an existing AV room (DSP, codec, control system, signal flow)",
      "sku": "AUDIT-001",
      "price": {
        "amount": 25000,
        "currency": "usd"
      },
      "fulfillment_type": "automatic"
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "Remote Commissioning, single room",
      "description": "Live remote commissioning session with a senior programmer",
      "sku": "COMMISSION-001",
      "price": {
        "amount": 49900,
        "currency": "usd"
      },
      "fulfillment_type": "manual"
    }
  ]
}
```

### Product fields

| Field              | Type           | Description                                                                          |
|--------------------|----------------|--------------------------------------------------------------------------------------|
| `id`               | string (UUID)  | Unique product identifier. Use this when creating checkout sessions.                  |
| `name`             | string         | Product name.                                                                         |
| `description`      | string or null | What the product or service does.                                                     |
| `sku`              | string or null | Optional SKU for inventory tracking.                                                  |
| `price.amount`     | integer        | Price in currency minor units (for example, 2500 = $25.00).                           |
| `price.currency`   | string         | ISO currency code (e.g., `"usd"`).                                                    |
| `fulfillment_type` | string         | `"automatic"` (tool execution on purchase) or `"manual"` (human fulfillment).         |

> **Note:** Prices are always in minor units of the currency. For USD, 2500 means $25.00. For JPY, 2500 means 2500 yen.

## Error responses

### 404 Not Found

The agent ID does not exist or has been deleted:

```json
{ "error": "Application not found" }
```

### 429 Too Many Requests

Public endpoints are limited to 200 requests per minute per IP:

```json
{ "error": "Rate limit exceeded" }
```

*AVCodex · Your AV expertise. Amplified by AI.*