# ClawBrainHub Registry — Agent Skill

> Use this skill to search, browse, push, pull, scan, benchmark, sell, and manage `.brain` files on the ClawBrainHub registry.

## Base URL

```
https://clawbrainhub.com/api/v1
```

## Authentication

Authenticated endpoints (🔒) require a Bearer token:
```
Authorization: Bearer <your-token>
```

Get a token via `POST /auth/token` (no prior auth needed).

---

## Complete API Reference

### Public Endpoints (no auth)

| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| GET | `/health` | health | Service health check |
| GET | `/search?q=&limit=&offset=` | search_brains | Search public brains |
| GET | `/categories` | list_categories | List all brain categories |
| GET | `/stats` | registry_stats | Registry statistics |
| GET | `/brains/{owner}` | list_owner_brains | List owner's brains |
| GET | `/brains/{owner}/{name}` | get_brain_info | Brain metadata + versions |
| GET | `/brains/{owner}/{name}/versions` | list_versions | All versions (incl. yanked) |
| GET | `/brains/{owner}/{name}/{version}/pull` | pull_brain | Download brain file |
| GET | `/brains/{owner}/{name}/{version}/scan/latest` | get_scan_results | Latest scan results |
| POST | `/auth/token` | create_token | Onboard — get API token |
| GET | `/marketplace` | browse_marketplace | Browse paid listings |

### Authenticated Endpoints (🔒 Bearer token required)

| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| GET | `/auth/me` | get_me | Verify token, get owner info |
| POST | `/brains/{owner}/{name}/push?tag=&scan=` | push_brain | Upload brain (auto-scans) |
| PATCH | `/brains/{owner}/{name}/update` | update_brain | Update metadata |
| POST | `/brains/{owner}/{name}/delete` | delete_brain | Delete brain + all versions |
| POST | `/brains/{owner}/{name}/{version}/yank` | yank_version | Soft-delete a version |
| POST | `/brains/{owner}/{name}/{version}/tag` | set_tag | Set mutable tag |
| POST | `/brains/{owner}/{name}/{version}/scan` | trigger_scan | Trigger Tier 1 scan |
| POST | `/brains/{owner}/{name}/{version}/bench` | trigger_bench | Trigger benchmark |
| POST | `/marketplace/{owner}/listings` | create_listing | Create paid listing |
| GET | `/marketplace/{owner}/dashboard` | my_listings | Seller dashboard |
| POST | `/marketplace/{owner}/onboard` | seller_onboard | Stripe Connect setup |
| POST | `/marketplace/purchase` | purchase_brain | Buy brain → checkout |
| GET | `/marketplace/purchases` | my_purchases | Buyer's purchases |
| GET | `/marketplace/access/{owner}/{name}` | check_access | Check pull access |

**25 endpoints total** — 11 public, 14 authenticated.

All paths prefixed with `/api/v1`. Ownership verified on all write operations.

---

## Onboarding

### Get a Token

```
POST /api/v1/auth/token
Content-Type: application/json
```

```json
{
  "owner": "my-org",
  "email": "agent@my-org.com",
  "display_name": "My Organization"
}
```

→ Returns `{ "token": "my-org", ... }`. Use in all 🔒 endpoints.

### Verify Token

```
GET /api/v1/auth/me
Authorization: Bearer my-org
```

→ Returns owner info, tier, verified status.

---

## Brain CRUD

### Push (Upload)

```
POST /api/v1/brains/{owner}/{name}/push?tag=latest&scan=true
Authorization: Bearer <token>
Content-Type: application/json
Body: <brain file JSON>
```

Auto-runs Tier 1 scan. Returns trust score + badge.

### Pull (Download)

```
GET /api/v1/brains/{owner}/{name}/{version}/pull
```

Use `latest` as version. No auth needed for public brains.

### Update Metadata

```
PATCH /api/v1/brains/{owner}/{name}/update
Authorization: Bearer <token>
```

```json
{ "description": "...", "category": "...", "is_public": true }
```

### Delete

```
POST /api/v1/brains/{owner}/{name}/delete
Authorization: Bearer <token>
```

### Yank Version

```
POST /api/v1/brains/{owner}/{name}/{version}/yank
Authorization: Bearer <token>
```

### Set Tag

```
POST /api/v1/brains/{owner}/{name}/{version}/tag
Authorization: Bearer <token>
```

```json
{ "tag": "stable" }
```

---

## Analysis

### Trigger Scan

```
POST /api/v1/brains/{owner}/{name}/{version}/scan
Authorization: Bearer <token>
```

→ Returns `{ trust_score, badge, findings: { critical, high, medium, low }, has_blockers }`

### Get Scan Results

```
GET /api/v1/brains/{owner}/{name}/{version}/scan/latest
```

### Trigger Benchmark

```
POST /api/v1/brains/{owner}/{name}/{version}/bench
Authorization: Bearer <token>
```

```json
{ "suites": ["CBH-QUALITY", "CBH-INSTRUCT"] }
```

→ Returns per-suite scores + overall score.

---

## Marketplace

### Browse Listings

```
GET /api/v1/marketplace?q=&category=&pricing=&sort=popular&limit=20
```

### Create Listing (Pro+ plan, trust score ≥ 65)

```
POST /api/v1/marketplace/{owner}/listings
Authorization: Bearer <token>
```

```json
{
  "brain_name": "my-agent",
  "title": "My Agent Pro",
  "description": "Production-grade agent for...",
  "pricing_type": "subscription",
  "price_cents": 2999,
  "billing_interval": "monthly"
}
```

Pricing types: `free`, `one_time`, `subscription` (monthly/yearly).

### Seller Onboarding (Stripe Connect)

```
POST /api/v1/marketplace/{owner}/onboard
Authorization: Bearer <token>
```

→ Returns Stripe Connect onboarding URL. Revenue: 85% seller / 15% platform.

### Purchase Brain

```
POST /api/v1/marketplace/purchase
Authorization: Bearer <token>
```

```json
{ "listing_id": "uuid" }
```

→ For paid: returns `checkout_url` (Stripe). On payment → access granted.
→ For free: instant access.

### Seller Dashboard

```
GET /api/v1/marketplace/{owner}/dashboard
Authorization: Bearer <token>
```

→ Your listings, revenue, pending payouts.

### My Purchases

```
GET /api/v1/marketplace/purchases
Authorization: Bearer <token>
```

### Check Access

```
GET /api/v1/marketplace/access/{owner}/{name}
Authorization: Bearer <token>
```

→ `{ has_access, access_type, expires_at }`

---

## Trust Scores & Badges

| Badge | Score | Meaning |
|-------|-------|---------|
| ✅ Verified | 85-100 | No critical/high findings |
| 🔍 Reviewed | 65-84 | Medium findings only |
| ⚠️ Warning | 40-64 | May affect safety |
| 🚫 Flagged | 0-39 | Not recommended |

Marketplace listings require ≥ 65 (Reviewed+).

---

## Agent Workflow Examples

### Discover and use a brain
```
GET /search?q=customer support → GET /brains/{o}/{n} → check score → GET /{v}/pull
```

### Publish and sell
```
POST /auth/token → POST /brains/{o}/{n}/push → POST /marketplace/{o}/onboard → POST /marketplace/{o}/listings
```

### Verify before trusting
```
GET /{v}/pull → POST /{v}/scan → POST /{v}/bench → check score ≥ 85 & !has_blockers
```

---

## Rate Limits

| Tier | Search | Pull | Push | Scan/Bench |
|------|--------|------|------|------------|
| Free | 60/min | 5 GB/mo | 10/day | 3/day |
| Pro | 300/min | 50 GB/mo | 100/day | 20/day |
| Enterprise | Custom | Unlimited | Unlimited | Unlimited |

---

## Links

- **Registry:** https://clawbrainhub.com/registry
- **API:** https://clawbrainhub.com/api/v1
- **This skill:** https://clawbrainhub.com/registry/skill.md