API Reference

The Tampa.dev Platform API provides authenticated access to community data including user profiles, events, groups, badges, and more. The full OpenAPI spec is available at /openapi.json and interactive docs at /docs.

Base URL

All authenticated API endpoints live under /v1/:

https://api.tampa.dev/v1/

Authentication

Include a Bearer token in the Authorization header:

curl -H "Authorization: Bearer td_pat_abc123..." \
  https://api.tampa.dev/v1/profile

Two token types are supported:

Type	Format	How to get
Personal Access Token	`td_pat_` + 40 hex chars	Create at tampa.dev/developer or via `POST /v1/profile/tokens`
OAuth Access Token	Opaque string	Obtained via the OAuth 2.0 flow

Both token types use the same scope system to control access. Session cookies are also accepted for first-party web UI requests.

API Sub-Pages

Profile & Users -- Profile, portfolio, tokens, achievements, linked accounts, following, uploads, and onboarding
Events & RSVP -- Events, RSVP, and checkin
Groups & Badges -- Groups, favorites, badges, leaderboard, and claims
Management -- Group management, event management, badge management, and checkin codes
Error Catalog -- Comprehensive error code reference with example payloads

Response Format

All /v1/ endpoints return JSON with standardized envelopes.

Detail / Mutation Responses

Single-item responses wrap the object in a data field:

{
  "data": {
    "id": "usr_abc123",
    "name": "Jane Developer",
    "username": "janedev"
  }
}

List Responses

List responses include a data array and pagination metadata:

{
  "data": [
    { "id": "evt_1", "title": "React Meetup" },
    { "id": "evt_2", "title": "Rust Workshop" }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Action Responses

Endpoints that perform an action without returning a resource:

{
  "data": {
    "success": true
  }
}

Error Responses

All errors include a human-readable error message and a machine-readable code:

{
  "error": "This endpoint requires the 'read:events' scope",
  "code": "insufficient_scope"
}

See the Error Catalog for the full list of error codes.

Pagination

List endpoints accept limit and offset query parameters:

Parameter	Type	Default	Max	Description
`limit`	integer	20	100	Maximum items per page
`offset`	integer	0	--	Number of items to skip

Example:

curl -H "Authorization: Bearer td_pat_abc123..." \
  "https://api.tampa.dev/v1/events?limit=10&offset=20"

HTTP Status Codes

Status	Meaning
`200`	Success
`201`	Created
`204`	No content (successful deletion)
`400`	Bad request -- invalid input
`401`	Unauthorized -- missing or invalid token
`403`	Forbidden -- insufficient scope or permissions
`404`	Not found
`409`	Conflict -- duplicate or state conflict
`410`	Gone -- resource expired or exhausted
`429`	Rate limited (includes `Retry-After` header)
`500`	Internal server error

Scope Headers

When a token lacks a required scope, the response includes a WWW-Authenticate header:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="read:events"

{
  "error": "This endpoint requires the 'read:events' scope",
  "code": "insufficient_scope"
}

Rate Limiting

Most endpoints are rate-limited. When the limit is exceeded, the response includes a Retry-After header with the number of seconds to wait. See Rate Limits for details.

MCP Server

In addition to the REST API, Tampa.dev exposes a Model Context Protocol (MCP) server at POST /mcp. MCP provides a standardized JSON-RPC 2.0 interface for AI agents, personal assistants, and automation tools to interact with the same platform capabilities available through the REST API.

MCP clients use the same authentication (OAuth or PAT) and scope system. The server automatically filters available tools based on token scopes. See the MCP documentation for details.

API Documentation