# Tampa.dev Platform API
> The Tampa.dev Platform API provides authenticated access to community data including user profiles, events, groups, badges, and more.

## Base URL
https://api.tampa.dev

## Markdown for Agents
All pages on tampa.dev support content negotiation. Request any page with Accept: text/markdown to receive a clean markdown version instead of HTML.

## MCP Server
Tampa.dev exposes a Model Context Protocol server for AI agents.
- Discovery: https://tampa.dev/.well-known/mcp-configuration
- Endpoint: https://api.tampa.dev/mcp (Streamable HTTP, JSON-RPC 2.0)
- Supports: tools, resources, and prompt templates
- Auth: OAuth 2.0 or Personal Access Token

## Authentication
- Personal Access Tokens: Authorization: Bearer td_pat_...
- OAuth 2.0: Authorization: Bearer <access_token>
- Create PATs at https://tampa.dev/developer
- OAuth authorize: https://tampa.dev/oauth/authorize

## OpenAPI Spec
Full machine-readable spec: https://api.tampa.dev/openapi.json
Interactive docs: https://api.tampa.dev/docs

## Scopes
- user: Read/write access to profile info (includes user:email and read:user)
- read:user: Read your public profile data
- user:email: Read your email address
- read:events: Read events and event details
- write:events: RSVP to events and check in
- read:groups: Read groups and group details
- read:favorites: Read your favorite groups
- write:favorites: Manage your favorite groups
- read:portfolio: Read your portfolio items
- write:portfolio: Manage your portfolio items
- read:meetpass: Read your MeetPass passes and connections
- write:meetpass: Manage your MeetPass passes
- manage:groups: Manage groups you own or co-manage
- manage:events: Create and manage events in your groups
- manage:checkins: Manage checkin codes and view attendees
- manage:badges: Create, award, and manage group badges
- admin: Full admin access

## Endpoint Categories

### User (scope: read:user, user)
- GET /v1/me - Basic identity
- GET /v1/profile - Full profile
- PATCH /v1/profile - Update profile
- GET /v1/profile/email - Email address
- GET /v1/profile/entitlements - Active entitlements
- GET /v1/profile/achievements - Achievement progress
- GET /v1/me/linked-accounts - Connected OAuth providers

### Portfolio (scope: read:portfolio, write:portfolio)
- GET /v1/profile/portfolio - List portfolio items
- POST /v1/profile/portfolio - Create portfolio item
- PATCH /v1/profile/portfolio/:id - Update portfolio item
- DELETE /v1/profile/portfolio/:id - Delete portfolio item

### Tokens (scope: user)
- GET /v1/profile/tokens - List PATs
- POST /v1/profile/tokens - Create PAT
- DELETE /v1/profile/tokens/:id - Revoke PAT

### Events (scope: read:events, write:events)
- GET /v1/events - List upcoming events
- GET /v1/events/:id - Event details
- GET /v1/events/:eventId/rsvp - Your RSVP status
- GET /v1/events/:eventId/rsvp-summary - RSVP counts
- POST /v1/events/:eventId/rsvp - RSVP to event
- DELETE /v1/events/:eventId/rsvp - Cancel RSVP
- POST /v1/checkin/:code - Check in to event

### Badges (scope: read:user)
- GET /v1/badges - List platform badges with rarity
- GET /v1/badges/:slug - Badge detail

### Public Users (scope: read:user)
- GET /v1/users - User directory (search, badge filter)
- GET /v1/users/:username - Public user profile
- GET /v1/users/:username/group-badges - User's group badges

### Leaderboard (scope: read:user, read:groups)
- GET /v1/leaderboard - Global XP leaderboard
- GET /v1/groups/:slug/leaderboard - Group XP leaderboard

### Groups (scope: read:groups, read:favorites, write:favorites)
- GET /v1/groups - List groups
- GET /v1/groups/:slug - Group details
- GET /v1/favorites - Favorite groups
- POST /v1/favorites/:groupSlug - Add favorite
- DELETE /v1/favorites/:groupSlug - Remove favorite

### Follows (scope: user)
- POST /v1/users/:username/follow - Follow user
- DELETE /v1/users/:username/follow - Unfollow user
- GET /v1/users/:username/followers - List followers
- GET /v1/users/:username/following - List following

### Claims
- GET /v1/claim/:code - Claim link info (no auth)
- POST /v1/claim/:code - Claim badge (scope: read:user)

### Scopes Discovery
- GET /v1/scopes - List available scopes (no auth)

### Management (scope: manage:groups, manage:events, manage:badges, manage:checkins)
- GET /v1/manage/groups - List managed groups
- PUT /v1/manage/groups/:groupId - Update group
- GET /v1/manage/groups/:groupId/members - List members
- POST /v1/manage/groups/:groupId/events - Create event
- POST /v1/manage/groups/:groupId/badges - Create badge
- POST /v1/manage/groups/:groupId/badges/:badgeId/award/:userId - Award badge

### Admin (scope: admin)
- GET /v1/admin/users - List users
- GET /v1/admin/groups - List groups
- GET /v1/admin/events - List events

## Response Format
Success: { "data": { ... } }
List: { "data": [...], "pagination": { "total", "limit", "offset", "hasMore" } }
Action: { "data": { "success": true } }
Error: { "error": "message", "code": "machine_code" }