# Buddo Platform — Agent Entry Point

Machine-readable guide for AI agents building on the Buddo platform.

## API

- **Base URL:** `https://api.buddo.xyz`
- **OpenAPI Spec:** `https://api.buddo.xyz/.well-known/openapi.json`
- **Local spec:** `./openapi.json`
- **Documentation site:** `https://docs.buddocloud.com`
- **API version:** 2.0.0

## Authentication

Two authentication methods exist. Choose based on your role:

### Operator Auth (JWT — for platform operators managing their own account)

```
POST /api/auth/register  {email, password, username}  → 201 {user}
POST /api/auth/login     {email, password}             → 200 {token, user}
```

Use the returned `token` as: `Authorization: Bearer <token>`

JWT gives access to: auth management, social features, education, OAuth app management, and user account endpoints.

### OAuth 2.0 PKCE (for operator apps acting on behalf of users)

```
1. Register an OAuth app:  POST /api/oauth/apps {app_name, redirect_uris, requested_scopes}  → client_id + client_secret
2. Authorization code:     GET  /api/oauth/authorize ?client_id=...&response_type=code&code_challenge=...&code_challenge_method=S256
3. Exchange for tokens:    POST /api/oauth/token {grant_type: "authorization_code", code, redirect_uri, client_id, code_verifier}
4. Use access token:       Authorization: Bearer <access_token>
5. Refresh:                POST /api/oauth/token {grant_type: "refresh_token", refresh_token, client_id, client_secret}
```

PKCE with S256 is mandatory for public clients. Plain is not supported.

**Guides:**
- `https://docs.buddocloud.com/quickstart/` — Full walkthrough
- `https://docs.buddocloud.com/guides/jwt-vs-oauth.html` — When to use which
- `https://docs.buddocloud.com/guides/oauth-pkce.html` — PKCE implementation details

## OAuth Scopes

| Scope | Description |
|---|---|
| `profile:read` | Read user profile and session information |
| `points:read` | Read user point balance |
| `points:spend` | Spend user points (credits operator account) |
| `points:transfer` | Transfer points between users |
| `points:award` | Deprecated — award is admin-only. Retained for existing token compatibility |
| `deploy:manage` | Deploy and manage hosted applications |
| `app:balance:read` | Read the operator app's point balance |

## Capabilities

The Buddo platform provides:

- **App Hosting (Deploy):** Container-based deployment with tiered pricing, health checks, custom domains, audit logs
- **Loyalty Points:** Award, spend, transfer, and read point balances for users
- **OAuth Provider:** Full OAuth 2.0 authorization server with PKCE, token introspection, scope requests
- **Social Features:** Friends, presence tracking, chat channels/messages, user search, blocking
- **Ad Marketplace:** Serve ads (banner/video/interstitial/native/rewarded), record impressions/clicks, treasury-funded payouts
- **Education (Bitcoin Learning):** Learning paths, modules, step completion with rewards
- **Operator Analytics:** User counts, spend/award totals, app management
- **User Management:** Connected apps, profile, app revocation

## First Steps (for agents)

1. Fetch the OpenAPI spec: `GET https://api.buddo.xyz/.well-known/openapi.json`
2. Register: `POST /api/auth/register` with `{email, password, username}`
3. Login: `POST /api/auth/login` with `{email, password}` — returns JWT
4. Check profile: `GET /api/auth/me` with `Authorization: Bearer <jwt>`
5. Create an OAuth app: `POST /api/oauth/apps` with `{app_name, redirect_uris, requested_scopes: ["deploy:manage"]}`
6. Explore endpoints by domain (see Documentation Map below)

## Deploy Flow (for agents — complete sequence)

This is the full sequence to deploy a container application on buddocloud. All steps are executable from curl alone; no CLI required.

### 1. Register and authenticate

```
POST /api/auth/register  {email, password, username}  → 201 {user}
POST /api/auth/login     {email, password}             → 200 {token, user}
```

Save `token` as your JWT. Use it as `Authorization: Bearer <token>` for all subsequent requests.

### 2. Create an OAuth app with deploy:manage scope

```
POST /api/oauth/apps
Authorization: Bearer <jwt>
Body: {
  "app_name": "My App",
  "redirect_uris": ["http://localhost:9876/callback"],
  "requested_scopes": ["deploy:manage"]
}
→ 201 { "app": { "client_id": "...", "client_secret": "...", "approved_scopes": ["deploy:manage"] } }
```

Save `client_id` and `client_secret`. The `client_secret` is shown only once.

**Note:** Deploy endpoints require an OAuth access token, not a JWT. Use PKCE (see [OAuth PKCE guide](https://docs.buddocloud.com/guides/oauth-pkce/)) to exchange your app credentials for an access token with `deploy:manage` scope, then use that token for all `/api/deploy/*` calls.

### 3. List available deploy tiers

```
GET /api/deploy/tiers
Authorization: Bearer <oauth_access_token>
→ 200 { "tiers": [ { "slug": "buddo-starter", "payment_method": "buddo_points", ... } ] }
```

Pick a tier `slug` for the next step. The `buddo-starter` tier is the default entry point.

### 4. Create a deployment

```
POST /api/deploy/apps
Authorization: Bearer <oauth_access_token>
Body: {
  "subdomain": "my-app",
  "image": "docker.io/library/nginx:latest",
  "tier": "buddo-starter",
  "port": 80
}
→ 201 { "deployment": { "id": "...", "status": "pending", "subdomain": "my-app" } }
```

Save the deployment `id`.

**Image whitelist** — `image` must start with one of:
- `harbor.buddo.xyz:4443/` (Buddo private registry)
- `docker.io/library/` (official Docker Hub images)
- `ghcr.io/` (GitHub Container Registry)

**Subdomain rules** — 1–32 chars, lowercase alphanumeric and hyphens. Your app will be live at `https://<subdomain>.buddocloud.com`.

### 5. Poll status until running

```
GET /api/deploy/apps/{id}/status
Authorization: Bearer <oauth_access_token>
→ 200 { "id": "...", "status": "running", "health_status": "healthy", "last_health_check": "..." }
```

Status progression: `pending` → `deploying` → `running`

Poll every 5–10 seconds. Rate limit: 30 requests/minute. Deployment typically reaches `running` within 30–60 seconds.

### 6. Verify the deployment is live

Once status is `running`, your app is reachable at `https://<subdomain>.buddocloud.com`.

```
GET /api/deploy/apps/{id}/logs
Authorization: Bearer <oauth_access_token>
→ 200 { "logs": [ { "action": "create", "status": "completed" }, { "action": "deploy", "status": "completed" } ] }
```

### 7. Stop or destroy when done

```
# Stop (preserves subdomain, can restart later)
POST /api/deploy/apps/{id}/stop
Authorization: Bearer <oauth_access_token>
→ 200 { "deployment": { "status": "stopped" } }

# Destroy permanently (cannot be undone)
DELETE /api/deploy/apps/{id}
Authorization: Bearer <oauth_access_token>
→ 200 { "message": "Deployment destroyed", "id": "..." }
```

### Deploy error reference

| Status | Cause |
|---|---|
| `401` | Missing or invalid token |
| `404` | Tier or deployment not found |
| `422` | Invalid subdomain, unsupported image registry, or unknown tier |
| `429` | Deployment limit reached or rate limit hit |

### Full guide

`https://docs.buddocloud.com/guides/quickstart/` — step-by-step operator quickstart with curl examples for every step above.

## Endpoint Summary (57 paths)

### Auth (9 endpoints) — JWT authentication
| Method | Path | Summary |
|---|---|---|
| POST | `/api/auth/register` | Register a new user account |
| POST | `/api/auth/login` | Authenticate and receive a JWT token |
| GET | `/api/auth/me` | Get the authenticated user's full profile |
| POST | `/api/auth/verify-email` | Verify a user's email address with a token |
| POST | `/api/auth/send-verification` | Resend the email verification link |
| POST | `/api/auth/forgot-password` | Request a password reset link |
| POST | `/api/auth/reset-password` | Reset password using a reset token |
| POST | `/api/auth/totp/setup` | Generate a TOTP secret and provisioning URI |
| POST | `/api/auth/totp/enable` | Enable TOTP by confirming a valid code |
| POST | `/api/auth/totp/verify` | Verify a TOTP or recovery code |

### OAuth (8 endpoints) — App registration and token management
| Method | Path | Summary |
|---|---|---|
| POST | `/api/oauth/apps` | Register a new OAuth app |
| GET | `/api/oauth/apps/{client_id}` | Get public app metadata by client_id |
| GET | `/api/oauth/authorize` | Request an authorization code |
| POST | `/api/oauth/token` | Exchange authorization code or refresh token for access tokens |
| POST | `/api/oauth/token/verify` | Introspect an access token |
| GET | `/api/oauth/my-apps` | List OAuth apps owned by the authenticated user |
| PUT | `/api/oauth/my-apps/{id}` | Update an OAuth app owned by the authenticated user |
| POST | `/api/oauth/my-apps/{id}/scope-request` | Request additional scopes for an owned app |

### Deploy (8 endpoints) — Container hosting
| Method | Path | Summary |
|---|---|---|
| GET | `/api/deploy/tiers` | List available deployment tiers |
| GET | `/api/deploy/apps` | List operator's deployments |
| POST | `/api/deploy/apps` | Create a new deployment |
| GET | `/api/deploy/apps/{id}` | Get a single deployment |
| DELETE | `/api/deploy/apps/{id}` | Destroy a deployment |
| GET | `/api/deploy/apps/{id}/status` | Lightweight deployment status check |
| GET | `/api/deploy/apps/{id}/logs` | Get deployment action logs |
| POST | `/api/deploy/apps/{id}/stop` | Stop a running deployment |
| POST | `/api/deploy/apps/{id}/restart` | Restart a deployment |

### Social (14 endpoints) — Friends, presence, chat, blocking
| Method | Path | Summary |
|---|---|---|
| GET | `/api/social/users/search` | Search users by username |
| GET | `/api/social/friends` | List current user's friends |
| POST | `/api/social/friends` | Send a friend request |
| GET | `/api/social/friends/pending` | List pending friend requests |
| PUT | `/api/social/friends/{id}` | Accept or reject a friend request |
| DELETE | `/api/social/friends/{id}` | Remove a friendship |
| POST | `/api/social/block` | Block a user |
| DELETE | `/api/social/block/{user_id}` | Unblock a user |
| GET | `/api/social/presence` | Get friends' online presence |
| POST | `/api/social/presence` | Track user presence |
| DELETE | `/api/social/presence` | Untrack user presence |
| GET | `/api/social/presence/table` | Get presence for a game table |
| POST | `/api/social/chat/channels` | Create or ensure a chat channel |
| GET | `/api/social/chat/{channel_id}/messages` | Get messages from a chat channel |
| POST | `/api/social/chat/{channel_id}/messages` | Send a message to a chat channel |

### Operator (3 endpoints) — App and analytics management
| Method | Path | Summary |
|---|---|---|
| GET | `/api/operator/app` | Get operator's app details |
| PUT | `/api/operator/app` | Update operator's app |
| GET | `/api/operator/analytics` | Get operator analytics |

### User (3 endpoints) — User account and connected apps
| Method | Path | Summary |
|---|---|---|
| GET | `/api/external/user` | Get authenticated user profile |
| GET | `/api/user/connected-apps` | List user's connected OAuth apps |
| DELETE | `/api/user/connected-apps/{app_id}` | Revoke app access |

### Points (3 endpoints) — Loyalty point operations
| Method | Path | Summary |
|---|---|---|
| GET | `/api/external/points` | Get user point balance |
| POST | `/api/external/points/spend` | Spend user points, crediting the operator account |
| POST | `/api/external/points/transfer` | Transfer points from the authenticated user to another user |

### Sessions (3 endpoints) — Session lifecycle
| Method | Path | Summary |
|---|---|---|
| GET | `/api/external/session/status` | Check whether the user has an active session |
| POST | `/api/external/session/end` | End the user's active session |
| POST | `/api/session/refresh` | Refresh a session token |

### Ads (2 endpoints) — Ad marketplace
| Method | Path | Summary |
|---|---|---|
| GET | `/api/external/ads/serve` | Serve an ad campaign for a given surface type |
| POST | `/api/external/ads/event` | Record an ad impression or click event |

### App (1 endpoint) — Operator app balance
| Method | Path | Summary |
|---|---|---|
| GET | `/api/external/app/balance` | Get the operator app's earned-point balance |

### Education (5 endpoints) — Bitcoin learning
| Method | Path | Summary |
|---|---|---|
| POST | `/api/btc-progress/learning-path` | Set learning path |
| GET | `/api/btc-progress/available-modules` | List available modules |
| GET | `/api/btc-progress/module/{module_number}/status` | Get module progress |
| POST | `/api/btc-progress/module/{module_number}/reset` | Reset a completed module |
| POST | `/api/btc-progress/{step_id}/complete` | Complete a learning step |

### Public (1 endpoint) — No auth required
| Method | Path | Summary |
|---|---|---|
| GET | `/api/public/operators` | List approved public operators |

### Infrastructure (2 endpoints) — Health and discovery
| Method | Path | Summary |
|---|---|---|
| GET | `/health` | Health check |
| GET | `/.well-known/oauth-protected-resource` | RFC 9728 OAuth Protected Resource discovery |

## Documentation Map

| Page | URL |
|---|---|
| Landing Page | `https://docs.buddocloud.com/` |
| Quickstart Guide | `https://docs.buddocloud.com/quickstart/` |
| API Reference Index | `https://docs.buddocloud.com/reference/` |
| Auth Reference | `https://docs.buddocloud.com/reference/auth.html` |
| OAuth Reference | `https://docs.buddocloud.com/reference/oauth.html` |
| Deploy Reference | `https://docs.buddocloud.com/reference/deploy.html` |
| Social Reference | `https://docs.buddocloud.com/reference/social.html` |
| Operator Reference | `https://docs.buddocloud.com/reference/operator.html` |
| User Reference | `https://docs.buddocloud.com/reference/user.html` |
| Public Reference | `https://docs.buddocloud.com/reference/public.html` |
| Education Reference | `https://docs.buddocloud.com/reference/education.html` |
| Infrastructure Reference | `https://docs.buddocloud.com/reference/infrastructure.html` |
| Guide: Operator Quickstart | `https://docs.buddocloud.com/guides/quickstart/` |
| Guide: OAuth PKCE | `https://docs.buddocloud.com/guides/oauth-pkce.html` |
| Guide: JWT vs OAuth | `https://docs.buddocloud.com/guides/jwt-vs-oauth.html` |
| Guide: Deploy Lifecycle | `https://docs.buddocloud.com/guides/deploy-lifecycle.html` |
| Guide: Social Integration | `https://docs.buddocloud.com/guides/social-integration.html` |
| Guide: Ad Marketplace | `https://docs.buddocloud.com/guides/ad-marketplace.html` |
| OpenAPI Spec (JSON) | `https://api.buddo.xyz/.well-known/openapi.json` |
| Agent Entry Point | `https://docs.buddocloud.com/AGENTS.md` |

## Rate Limits

Key rate limits to respect:
- **Register:** 5 requests/hour/IP
- **Login:** 10 requests/minute/IP
- **OAuth app creation:** 3 requests/hour
- **Session refresh:** 20 requests/minute/IP
- **Deploy operations:** 10–30 requests/minute depending on endpoint
- **Password reset:** 5 requests/hour/IP

## Key Concepts

- **Operator:** A business that registers an OAuth app to integrate with Buddo. Operators use the external OAuth API only.
- **User:** An end user who signs up on Buddo and authorizes operator apps via OAuth.
- **Points:** Buddo's loyalty currency. Operators can read, spend (crediting their own account), and transfer points. Award is admin-only.
- **Deploy Tiers:** Two payment methods — `buddo_points` and `bitcoin`. Each tier defines CPU, memory, domain, and stipend limits.
- **Sessions:** Lightweight presence tracking per-app. Refresh tokens rotate atomically.
- **Ad Surfaces:** `banner`, `video`, `interstitial`, `native`, `rewarded`. Treasury pays both user and operator for ad views.