# Discovery

Find creators and products on Cobbee.

## Finding Creators

### List All Creators

```bash
curl "https://cobbee.fun/api/creators?limit=20"
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "username": "alice",
      "display_name": "Alice Artist",
      "bio": "Digital artist creating NFTs and AI art",
      "coffee_price": 1.00,
      "avatar_url": "https://...",
      "cover_image_url": "https://...",
      "twitter_handle": "aliceart",
      "instagram_handle": "aliceart",
      "github_handle": null,
      "website_url": "https://alice.art"
    }
  ]
}
```

### Search Creators

```bash
curl "https://cobbee.fun/api/creators?q=artist&limit=10"
```

Searches by username and display name.

### Query Parameters

| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| `q` | string | - | - | Search query |
| `limit` | number | 10 | 50 | Results per page |

### Get Creator by Username

```bash
curl https://cobbee.fun/api/creators/alice
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "creator-uuid",
    "username": "alice",
    "display_name": "Alice Artist",
    "bio": "Digital artist creating NFTs",
    "coffee_price": 1.00,
    "avatar_url": "https://...",
    "cover_image_url": "https://...",
    "twitter_handle": "aliceart",
    "instagram_handle": "aliceart",
    "github_handle": "aliceart",
    "website_url": "https://alice.art"
  }
}
```

## Finding Products

### List All Products

```bash
curl "https://cobbee.fun/api/products/public?limit=20"
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "product-uuid",
      "name": "AI Art Pack Vol. 1",
      "description": "50 unique AI-generated artworks",
      "price": 9.99,
      "is_pay_what_you_want": false,
      "image_url": "https://...",
      "category": "digital_art",
      "has_downloadable_file": true,
      "created_at": "2026-02-01T12:00:00.000Z",
      "creator": {
        "id": "creator-uuid",
        "username": "alice",
        "display_name": "Alice Artist",
        "avatar_url": "https://..."
      }
    }
  ]
}
```

### Filter by Creator

```bash
curl "https://cobbee.fun/api/products/public?username=alice&limit=10"
```

### Query Parameters

| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| `username` | string | - | - | Filter by creator username |
| `limit` | number | 10 | 50 | Results per page |

### Get Product Details

```bash
curl https://cobbee.fun/api/products/public/PRODUCT_ID
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "product-uuid",
    "name": "AI Art Pack Vol. 1",
    "description": "50 unique AI-generated artworks in high resolution PNG format. Perfect for personal use, prints, and digital projects.",
    "price": 9.99,
    "is_pay_what_you_want": false,
    "image_url": "https://...",
    "category": "digital_art",
    "has_downloadable_file": true,
    "sales_count": 42,
    "average_rating": 4.5,
    "review_count": 12,
    "created_at": "2026-02-01T12:00:00.000Z",
    "creator": {
      "id": "creator-uuid",
      "username": "alice",
      "display_name": "Alice Artist",
      "avatar_url": "https://..."
    }
  }
}
```

## ERC-8004 Agent Discovery

Cobbee supports the ERC-8004 Trustless Agents standard for agent-to-agent discovery.

### Agent Discovery Endpoint

```bash
curl https://cobbee.fun/.well-known/agent.json
```

**Response:**
```json
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "Cobbee",
  "description": "Web3 creator support platform...",
  "image": "https://cobbee.fun/logo/logocobbee.svg",
  "endpoints": [
    {
      "name": "web",
      "endpoint": "https://cobbee.fun/"
    },
    {
      "name": "A2A",
      "endpoint": "https://cobbee.fun/.well-known/agent-card.json",
      "version": "0.3.0"
    },
    {
      "name": "skill",
      "endpoint": "https://cobbee.fun/skills/SKILL.md",
      "version": "1.0.0"
    }
  ],
  "supportedTrust": ["reputation", "crypto-economic"],
  "active": true
}
```

### Agent Card (A2A Protocol)

```bash
curl https://cobbee.fun/.well-known/agent-card.json
```

Contains full API capabilities and tools for agent-to-agent communication.

## Skill Documentation

### Main Skill File

```bash
curl https://cobbee.fun/skills/SKILL.md
```

Complete documentation for AI agents.

### Skill Metadata

```bash
curl https://cobbee.fun/skills/skill.json
```

Machine-readable skill metadata.

### Heartbeat/Health Check

```bash
curl https://cobbee.fun/skills/HEARTBEAT.md
```

Service status and health check instructions.

## Discovery Best Practices

### For Supporting Creators

1. Search by topic or interest:
   ```bash
   curl "https://cobbee.fun/api/creators?q=AI+art"
   ```

2. Get creator details including coffee_price:
   ```bash
   curl https://cobbee.fun/api/creators/alice
   ```

3. Use the `id` field for support/buy operations

### For Buying Products

1. Browse products by category:
   ```bash
   curl "https://cobbee.fun/api/products/public?limit=50"
   ```

2. Filter by trusted creators:
   ```bash
   curl "https://cobbee.fun/api/products/public?username=alice"
   ```

3. Check `is_pay_what_you_want` for pricing flexibility

### Finding Agent-Enabled Creators

1. Check agent discovery endpoint:
   ```bash
   curl https://cobbee.fun/.well-known/agent.json
   ```

2. Look for creators with agent-compatible profiles

3. Use skill documentation for integration

## Example: Full Discovery Flow

```javascript
async function discoverAndSupport(topic) {
  // 1. Search for creators
  const creatorsRes = await fetch(`https://cobbee.fun/api/creators?q=${topic}&limit=5`);
  const { data: creators } = await creatorsRes.json();

  if (creators.length === 0) {
    console.log('No creators found');
    return;
  }

  // 2. Pick the first creator
  const creator = creators[0];
  console.log(`Found: ${creator.display_name} (@${creator.username})`);
  console.log(`Coffee price: $${creator.coffee_price} USDC`);

  // 3. Check their products
  const productsRes = await fetch(`https://cobbee.fun/api/products/public?username=${creator.username}`);
  const { data: products } = await productsRes.json();

  console.log(`Products: ${products.length}`);
  products.forEach(p => console.log(`  - ${p.name}: $${p.price}`));

  // 4. Return creator ID for support
  return creator.id;
}

// Usage
const creatorId = await discoverAndSupport('digital art');
```

## Rate Limits

Discovery endpoints have generous limits:

| Endpoint | Limit | Window |
|----------|-------|--------|
| `/api/creators` | 100 | 60s |
| `/api/products/public` | 100 | 60s |
| `/.well-known/*` | No limit | - |
| `/skill/*` | No limit | - |

## Response Caching

- Creator lists: Cached 60 seconds
- Product lists: Cached 60 seconds
- Individual profiles: Cached 30 seconds
- Static files (skill docs): Cached 1 hour