# API Reference

Bindly's REST API is available at `bind.ly/api/*`.

## Authentication

All API endpoints (except `/api/public/*`) require authentication.

### Session Cookie (Web)
Automatically set on login. Used by the SPA at bind.ly.

### User Key (MCP / Programmatic)
Pass as Bearer token:
```
Authorization: Bearer userk_abc123...
```

Create User Keys at bind.ly/settings.

### Space API Key
For Space-level access:
```
Authorization: Bearer spacek_abc123...
```

## Endpoints

### Auth
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/auth/register` | Register with email/password |
| POST | `/api/auth/login` | Login, returns JWT cookies |
| POST | `/api/auth/logout` | Clear session |
| GET | `/api/auth/me` | Current user profile |
| GET | `/api/auth/google` | Start Google OAuth |
| GET | `/api/auth/callback/google` | Google OAuth callback |
| POST | `/api/auth/verify-email` | Verify email token |
| POST | `/api/auth/forgot-password` | Request password reset |
| POST | `/api/auth/reset-password` | Reset password with token |
| GET | `/api/auth/keys` | List User Keys |
| POST | `/api/auth/keys` | Create User Key |
| DELETE | `/api/auth/keys/:id` | Revoke User Key |
| POST | `/api/auth/add-password` | Add password to OAuth-only account |

### Bindings
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/bindings?spaceId=` | List bindings in Space |
| POST | `/api/bindings` | Create binding |
| GET | `/api/bindings/:id?tier=1` | Get binding (Tier 1/1.5/2) |
| PUT | `/api/bindings/:id` | Update (creates new Version) |
| DELETE | `/api/bindings/:id` | Delete binding |

### Spaces
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/spaces` | List accessible Spaces |
| POST | `/api/spaces` | Create Space |
| GET | `/api/spaces/:id` | Get Space details |

### Sets
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/sets?spaceId=` | List Sets |
| POST | `/api/sets` | Create Set |
| GET | `/api/sets/:id` | Get Set |
| DELETE | `/api/sets/:id` | Delete Set |

### Search
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/search?q=&mode=` | Search (auto/semantic/keyword) |

### Public (No Auth)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/public/@:space/:binding` | Public binding by slug |
| GET | `/api/public/spaces` | List public Spaces |
| GET | `/api/health` | Health check |