# Agent Discovery

Public endpoints for AI agents to discover products and capabilities

---

Discovery endpoints let AI agents find your app 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 app and its ACP capabilities. This follows the `.well-known` convention used in agent-to-agent protocols, making it easy for AI agents to discover what your app offers and how to interact with it.

### Example Request

```bash
curl https://build.chipp.ai/acp/{appId}/.well-known/agent.json
```

### Response

```json
{
  "name": "My AI Assistant",
  "description": "An assistant that helps with data analysis",
  "url": "https://build.chipp.ai/acp/{appId}",
  "version": "1.0.0",
  "capabilities": {
    "products": true,
    "checkout": true
  },
  "endpoints": {
    "products": "https://build.chipp.ai/acp/{appId}/products",
    "checkout": "https://build.chipp.ai/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 application's name |
| `description` | string or null | Your application's description |
| `url` | string | Base URL for this app'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://build.chipp.ai/acp/{appId}/products
```

### Response

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Data Analysis Report",
      "description": "Generate a comprehensive analysis of your dataset",
      "sku": "ANALYSIS-001",
      "price": {
        "amount": 2500,
        "currency": "usd"
      },
      "fulfillment_type": "automatic"
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "Custom Research Brief",
      "description": "A tailored research brief on any topic",
      "sku": "RESEARCH-001",
      "price": {
        "amount": 4999,
        "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 (e.g., 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 application 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" }
```