API.md

API Reference

All endpoints are under /api/. Authentication uses Firebase Auth ID tokens (Bearer) or session cookies. Spec: /openapi.json · interactive: /api/docs.

186 paths, 223 operations across 35 areas.

---

Agents

Programmatic agent registration, claiming, and self-service.

Method	Endpoint	Auth	Description
GET	/api/agents/claim/{token}	No	Get info about an agent pending claim
POST	/api/agents/claim/{token}	Yes	Claim an agent (link to authenticated user)
GET	/api/agents/me	Yes	Get the authenticated agent's profile
PATCH	/api/agents/me	Yes	Update the authenticated agent's profile
POST	/api/agents/register	Yes	Register a new agent (returns API key + claim URL)
GET	/api/agents/user	Yes	List agents owned by the authenticated user

Analytics

Public aggregate analytics snapshots.

Method	Endpoint	Auth	Description
GET	/api/analytics/summary	No	Public aggregate analytics summary (cached snapshot)

Auth

Authentication and email resolution.

Method	Endpoint	Auth	Description
POST	/api/auth/change-primary-email	Yes	Promote an additional verified email to primary
POST	/api/auth/remove-email	Yes	Remove an additional email from the account
POST	/api/auth/resolve-email	No	Resolve an email (or alias) to its primary account email
POST	/api/auth/send-email-verification	Yes	Send a verification email for an additional email
GET	/api/auth/verify-email	No	Verify an email via tokenized link (redirects to /profile)

Badges

Badge definitions and per-user awards.

Method	Endpoint	Auth	Description
POST	/api/badges/awards	Yes	Recompute and persist badge awards for the current user
GET	/api/badges/definitions	No	Public list of badge definitions

Certificate

Verifiable merged-PR certificates.

Method	Endpoint	Auth	Description
POST	/api/certificate/claim	Yes	Claim a Cursor Boston merged-PR certificate
GET	/api/certificate/mine	Yes	List LinkedIn certificates issued to the signed-in user

Cfp

CFP graduate-student .edu email verification.

Method	Endpoint	Auth	Description
POST	/api/cfp/send-edu-code	Yes	Send a 6-digit verification code to a .edu email
POST	/api/cfp/verify-edu-code	Yes	Verify the .edu code and attach the email + eduBadge

Community

Community posts, replies, reactions, moderation.

Method	Endpoint	Auth	Description
DELETE	/api/community/block	Yes	Unblock another user
POST	/api/community/block	Yes	Block another user
POST	/api/community/delete	Yes	Delete the current user's own community message
GET	/api/community/feed	No	List visible community feed messages
GET	/api/community/moderate	Yes	Admin: list community reports (paginated)
POST	/api/community/moderate	Yes	Admin: act on a community report (dismiss / hide / suspend)
GET	/api/community/my-reactions	Yes	Get the current user's reactions for a batch of messages
POST	/api/community/post	Yes	Create a community post
POST	/api/community/reaction	Yes	Add / remove / switch a like or dislike on a message
POST	/api/community/reply	Yes	Reply to a community post
POST	/api/community/report	Yes	Report a message for moderation
POST	/api/community/repost	Yes	Repost a community message with optional commentary

Cookbook

Prompt cookbook entries and votes.

Method	Endpoint	Auth	Description
GET	/api/cookbook/entries	No	List cookbook entries (paginated, filterable, searchable)
POST	/api/cookbook/entries	Yes	Submit a new cookbook entry
GET	/api/cookbook/vote	No	Get the current user's vote map across all cookbook entries
POST	/api/cookbook/vote	Yes	Up- or down-vote a cookbook entry (toggle / switch supported)

Discord

Discord OAuth (link / unlink).

Method	Endpoint	Auth	Description
GET	/api/discord/authorize	No	Begin Discord OAuth — redirects to discord.com
GET	/api/discord/callback	No	Discord OAuth callback — finishes the link and redirects

Events

Coworking sessions and PyData 2026 ticketing.

Method	Endpoint	Auth	Description
GET	/api/events/{eventId}/coworking/eligibility	No	Check coworking eligibility for the current user
DELETE	/api/events/{eventId}/coworking/register	Yes	Cancel the current user's coworking registration
POST	/api/events/{eventId}/coworking/register	Yes	Register for a coworking session in an event
GET	/api/events/{eventId}/coworking/slots	No	List coworking sessions with availability for an event
GET	/api/events/pydata-2026/access	No	Whether the signed-in user is on the 150-person PyData 2026 door list
GET	/api/events/pydata-2026/admin/list	Yes	Admin: paginated PyData 2026 registrations with cap-vs-waitlist
GET	/api/events/pydata-2026/capacity	No	Public PyData 2026 capacity / claimed / remaining counts
GET	/api/events/pydata-2026/luma-status	No	Whether the current user appears on the PyData Luma guest list
GET	/api/events/pydata-2026/registration	Yes	Get the current user's PyData 2026 registration (if any)
POST	/api/events/pydata-2026/registration	Yes	Create or update the current user's PyData 2026 registration
POST	/api/events/pydata-2026/withdraw	No	Two-step PyData withdrawal: confirmation page POSTs here with HMAC token

Game

Strategy game endpoints (leaderboard, attacks, artifacts, turns).

Method	Endpoint	Auth	Description
POST	/api/game/admin/grant	Yes	Admin: grant turns to a user (testing helper)
POST	/api/game/admin/units	Yes	Admin: drop units on a tile (bootstrap helper)
POST	/api/game/artifact/use	Yes	Spend an artifact (optionally on a target tile)
GET	/api/game/artifacts	Yes	List the player's artifact inventory
POST	/api/game/attack	Yes	Launch an attack from one of your tiles
POST	/api/game/attack/preview	Yes	Project the outcome of a hypothetical attack
GET	/api/game/attacks	Yes	List the player's attacks (sent/received/all)
POST	/api/game/build	Yes	Build units on a tile
POST	/api/game/build/bulk	Yes	Execute a bulk build plan across tiles
POST	/api/game/caste/change	Yes	Switch castes (one-time, after reaching 1000 tiles)
GET	/api/game/community/chat	Yes	Recent community chat messages
POST	/api/game/community/chat	Yes	Post a chat message (rate-limited: 10 / 60s per user)
DELETE	/api/game/community/chat/{messageId}	Yes	Delete a chat message (own or admin)
GET	/api/game/community/feed	Yes	Recent community events (player joins, caste picks, attacks)
POST	/api/game/distribute/bulk	Yes	Distribute one land type across multiple tiles
GET	/api/game/eligibility	Yes	Get the current user's game eligibility state
POST	/api/game/explore	Yes	Frontier-explore one or more new tiles
POST	/api/game/explore/bulk	Yes	Bulk frontier-explore (count required)
POST	/api/game/explore/far	Yes	Spend 2 turns to plant a tile adjacent to a random enemy tile (Far Expedition).
POST	/api/game/flyover	Yes	Air raid that attrits defenders without taking the tile
GET	/api/game/heroes	Yes	List heroes (mine / all living / fallen)
GET	/api/game/heroes/{heroId}	Yes	Get a hero's profile + first page of events
GET	/api/game/heroes/{heroId}/backstory	Yes	Get the markdown backstory for a hero, if one exists
GET	/api/game/heroes/{heroId}/events	Yes	Paginated event log for a hero
GET	/api/game/leaderboard	Yes	Get the leaderboard ranked by tiles held
GET	/api/game/map/me	Yes	Get the current user's personal map view (own tiles + enemy ring)
POST	/api/game/npc-weekly	No	Cron-only weekly NPC turn-spender
GET	/api/game/player	Yes	Get the current user's game profile + visible tiles
PATCH	/api/game/player	Yes	Rename the current user's general (display name)
POST	/api/game/player	Yes	Create the current user's game profile
POST	/api/game/rollover	No	Cron-only weekly turn-grant rollover
POST	/api/game/setup/caste	Yes	Choose initial caste during onboarding
POST	/api/game/setup/distribute	Yes	Distribute land type to a tile during onboarding
POST	/api/game/setup/explore	Yes	Frontier-explore tiles during onboarding
POST	/api/game/siege	Yes	Soften a target tile's standing-defense floor
POST	/api/game/special-units/summon	Yes	Station a caste-themed special unit on one of your tiles
POST	/api/game/special-units/unsummon	Yes	Recall a stationed special unit back into your pool
POST	/api/game/spell/arm	Yes	Arm a defense spell on one tile (single) or many (bulk)
POST	/api/game/spell/cast	Yes	Cast a standalone siege/disarm/attrition spell against a target tile
POST	/api/game/spell/produce	Yes	Cast a production spell (with optional batch count)
POST	/api/game/spy	Yes	Cast an intel ('spy') spell on an enemy tile.
GET	/api/game/tile/{tileId}	Yes	Get a single tile by id
POST	/api/game/upgrades/apply	Yes	Apply an upgrade to a target
POST	/api/game/upgrades/remove	Yes	Remove an upgrade from a target
GET	/api/game/world	Yes	Fetch tiles for the world map (full or bbox)
GET	/api/game/world-3d	No	Public 3D flyover world snapshot (daily, anonymous-accessible)

Github

GitHub OAuth + signed webhook receiver.

Method	Endpoint	Auth	Description
GET	/api/github/authorize	No	Begin GitHub OAuth — redirects to github.com
GET	/api/github/callback	No	GitHub OAuth callback — finishes the link and redirects
GET	/api/github/webhook	No	Webhook health-check (GitHub fires GET on initial setup)
POST	/api/github/webhook	Yes	GitHub webhook receiver (HMAC-signed by github.com)

Hackathons

Hackathon pool, teams, submissions, and Hack-a-Sprint showcase.

Method	Endpoint	Auth	Description
GET	/api/hackathons/eligibility	Yes	Get current user's hackathon eligibility
POST	/api/hackathons/events/{eventId}/checkin	Yes	Admin-only: check a user in to an event
DELETE	/api/hackathons/events/{eventId}/confirm-attendance	Yes	Withdraw the user's attendance confirmation (keeps signup)
POST	/api/hackathons/events/{eventId}/confirm-attendance	Yes	Confirm attendance for an event the user has signed up for
POST	/api/hackathons/events/{eventId}/refresh-submissions	Yes	Admin-only — force-refresh the three-tier submission cache
DELETE	/api/hackathons/events/{eventId}/signup	Yes	Withdraw the current user's signup
GET	/api/hackathons/events/{eventId}/signup	Yes	Public event-signup leaderboard
PATCH	/api/hackathons/events/{eventId}/signup	Yes	Update the current user's signup state
POST	/api/hackathons/events/{eventId}/signup	Yes	Sign up the current user for an event
POST	/api/hackathons/invites/accept	Yes	Accept a team invite
GET	/api/hackathons/pool-dashboard	Yes	Get the current user's hackathon pool dashboard
POST	/api/hackathons/pool/join	Yes	Join the hackathon pool (matchmaking)
POST	/api/hackathons/requests/accept	Yes	Accept a team-join request from another user
GET	/api/hackathons/showcase/hack-a-sprint-2026/admin-dashboard	Yes	Admin: Hack-a-Sprint scoring dashboard
POST	/api/hackathons/showcase/hack-a-sprint-2026/ai-score	Yes	Admin: set AI score (1-10) on a submission
GET	/api/hackathons/showcase/hack-a-sprint-2026/credit-code	Yes	Get the current user's Cursor credit link
POST	/api/hackathons/showcase/hack-a-sprint-2026/credit-email	Yes	Email the credit link to the current user
POST	/api/hackathons/showcase/hack-a-sprint-2026/judge-score	Yes	Judge: score a submission during peerVotingOpen
GET	/api/hackathons/showcase/hack-a-sprint-2026/me	Yes	Get the current user's Hack-a-Sprint state
POST	/api/hackathons/showcase/hack-a-sprint-2026/participant-score	Yes	Participant: score a peer submission
GET	/api/hackathons/showcase/hack-a-sprint-2026/submissions	No	Public Hack-a-Sprint submissions gallery
POST	/api/hackathons/showcase/hack-a-sprint-2026/unlock	No	Legacy passcode unlock (retired)
POST	/api/hackathons/showcase/hack-a-sprint-2026/vote	No	Legacy voting endpoint (retired — use participant-score)
GET	/api/hackathons/submissions/check-disqualified	Yes	Cron: scan submissions for late commits and mark disqualified
POST	/api/hackathons/submissions/register	Yes	Register a team's repo URL for the hackathon
POST	/api/hackathons/submissions/submit	Yes	Lock the team's submission (sets submittedAt, cutoffAt)
GET	/api/hackathons/team-dashboard	Yes	Get the current user's team dashboard
POST	/api/hackathons/team/leave	Yes	Leave the user's current hackathon team
PATCH	/api/hackathons/team/profile	Yes	Update the team's name / logo (gated on prior wins)
GET	/api/hackathons/teams-board	No	Public hackathon teams board

Health

Liveness probe.

Method	Endpoint	Auth	Description
GET	/api/health	No	Liveness probe (always 200 if the app is up)

Hunt

Treasure hunt: oracle, paths, prize claim.

Method	Endpoint	Auth	Description
GET	/api/hunt/oracle	No	Daily oracle riddle + answer fingerprint
GET	/api/hunt/oracle/konami	No	Daily Konami token (only revealed with X-Konami-Sequence header)
POST	/api/hunt/paths/{pathId}/submit	Yes	Submit a candidate answer for a hunt path
GET	/api/hunt/status	No	Caller eligibility + remaining-prize counts

Internal

Cron-secret-protected maintenance endpoints.

Method	Endpoint	Auth	Description
GET	/api/internal/digest/weekly-hiring-partners	Yes	Cron: weekly digest of pending hiring-partner applications
POST	/api/internal/digest/weekly-hiring-partners	Yes	Cron: weekly digest of pending hiring-partner applications (POST form)
GET	/api/internal/hunt/email-retry	Yes	Cron: retry undelivered treasure-hunt prize emails
POST	/api/internal/hunt/email-retry	Yes	Cron: retry undelivered treasure-hunt prize emails (POST form)
POST	/api/internal/rate-limits/cleanup	Yes	Cron: delete expired rate-limit docs in batches
GET	/api/internal/snapshots/rebuild	Yes	Cron: rebuild analytics + members snapshots
POST	/api/internal/snapshots/rebuild	Yes	Cron: rebuild analytics + members snapshots (POST form)

Live

Live lightning-talks sessions, emcee control, and audience queue.

Method	Endpoint	Auth	Description
POST	/api/live/{sessionId}/control	Yes	Emcee control deck: drive the session forward
POST	/api/live/{sessionId}/queue	Yes	Audience: join the speaker queue for a live session
POST	/api/live/session	Yes	Admin: create a new live (lightning-talks) session

Ludwitt

Ludwitt OAuth + AI proxy through the shared credit pool.

Method	Endpoint	Auth	Description
POST	/api/ludwitt/ai/messages	Yes	Proxy an Anthropic Messages-shaped request through Ludwitt
GET	/api/ludwitt/authorize	No	Begin Ludwitt OAuth (PKCE) — redirects to Ludwitt
POST	/api/ludwitt/connect-start	Yes	Authenticated PKCE handshake — returns the authorize URL
POST	/api/ludwitt/disconnect	Yes	Disconnect the Ludwitt link for the current user
POST	/api/ludwitt/finalize-token	No	Trade the one-time finalize cookie for the linked-account token

Maintainers

Maintainer self-service and review queue.

Method	Endpoint	Auth	Description
GET	/api/maintainers/review-queue	Yes	Get the open-PR review queue for the current maintainer
GET	/api/maintainers/status	Yes	Get the current user's maintainer eligibility

Members

Public community members directory.

Method	Endpoint	Auth	Description
GET	/api/members/public	No	Public, cached community members directory

Mentorship

Mentor/mentee profiles, matches, requests.

Method	Endpoint	Auth	Description
GET	/api/mentorship/matches	Yes	Get top mentor/mentee matches for the current user
GET	/api/mentorship/profile	Yes	Get the current user's mentorship profile
POST	/api/mentorship/profile	Yes	Create or update the current user's mentorship profile
GET	/api/mentorship/request	Yes	List the current user's mentorship requests
POST	/api/mentorship/request	Yes	Send a mentorship request to another user
POST	/api/mentorship/respond	Yes	Accept or decline a received mentorship request

Notifications

Email unsubscribe (HMAC token).

Method	Endpoint	Auth	Description
GET	/api/notifications/unsubscribe	No	One-click email unsubscribe (HMAC token in query)

Pair

Pair-programming profiles, matches, requests.

Method	Endpoint	Auth	Description
GET	/api/pair/matches	Yes	Get top pair-programming matches for the current user
GET	/api/pair/profile	Yes	Get the current user's pair-programming profile
POST	/api/pair/profile	Yes	Create or update the current user's pair-programming profile
GET	/api/pair/request	Yes	List the current user's pair requests
POST	/api/pair/request	Yes	Send a pair request to another user
POST	/api/pair/respond	Yes	Accept or decline a received pair request

Account

Account lifecycle: GDPR delete, scheduled purge.

Method	Endpoint	Auth	Description
DELETE	/api/account	Yes	GDPR Article 17: delete the current user's account
POST	/api/account/purge	No	Cron-only: resume stale 30-day account deletions

Profile

User profile: data, visibility, subscription, GitHub reconcile.

Method	Endpoint	Auth	Description
GET	/api/profile/data	Yes	Get the current user's profile data (with optional GDPR-portable export)
POST	/api/profile/github/reconcile	Yes	Reconcile merged-PR counts from the connected GitHub account
GET	/api/profile/subscription	Yes	Get the current user's email-subscription status
PATCH	/api/profile/subscription	Yes	Update the current user's email-subscription status
PATCH	/api/profile/update	Yes	Update the current user's profile fields
GET	/api/profile/visibility	Yes	Get the current user's profile visibility flags
PATCH	/api/profile/visibility	Yes	Update the current user's profile visibility flags

Questions

Q&A: questions, answers, votes, accept.

Method	Endpoint	Auth	Description
GET	/api/questions	No	List questions with cursor pagination
GET	/api/questions/{questionId}	No	Get question detail (with top answers + related cookbook entries)
POST	/api/questions/accept	Yes	Mark an answer as accepted (question owner only)
POST	/api/questions/answer	Yes	Post an answer on a question
POST	/api/questions/post	Yes	Create a new question
GET	/api/questions/vote	Yes	Get the current user's votes (per target id)
POST	/api/questions/vote	Yes	Vote up/down on a question or answer

Showcase

Showcase project submissions, moderation, and votes.

Method	Endpoint	Auth	Description
GET	/api/showcase/submission	Yes	Get the current user's showcase submissions
POST	/api/showcase/submission	Yes	Submit a curated showcase project for moderation
GET	/api/showcase/submission/approve	Yes	Admin: list pending showcase submissions
POST	/api/showcase/submission/approve	Yes	Admin: approve or reject a showcase submission
GET	/api/showcase/vote	No	Get aggregate showcase project vote counts (paginated) and user's ledger
POST	/api/showcase/vote	Yes	Vote on a showcase project (toggle / switch supported)

Talks

Talk-submission moderation queue.

Method	Endpoint	Auth	Description
GET	/api/talks/submission/moderate	Yes	Admin: list talk submissions (paginated by status, or three-bucket default)
POST	/api/talks/submission/moderate	Yes	Admin: approve a talk submission or mark it delivered

Cursor

Method	Endpoint	Auth	Description
POST	/api/cursor/connect	Yes	Validate and store the current user's Cursor API key
POST	/api/cursor/disconnect	Yes	Disconnect the current user's Cursor API key
GET	/api/cursor/github-issues	Yes	List open GitHub issues for PR Studio
GET	/api/cursor/idea-runs	Yes	List recent Cursor PR idea runs for the current user
POST	/api/cursor/idea-runs	Yes	Launch a Cursor Cloud Agent to propose contribution PR ideas
DELETE	/api/cursor/idea-runs/{runId}	Yes	Delete the Cursor agent and local record for an idea run
GET	/api/cursor/idea-runs/{runId}	Yes	Get and refresh a Cursor PR idea run
POST	/api/cursor/idea-runs/{runId}/answers	Yes	Submit clarification answers and request a build plan
POST	/api/cursor/idea-runs/{runId}/approve-plan	Yes	Approve the generated build plan and start implementation
POST	/api/cursor/idea-runs/{runId}/archive	Yes	Archive the Cursor agent behind an idea run
POST	/api/cursor/idea-runs/{runId}/cancel	Yes	Cancel an active Cursor PR idea run
POST	/api/cursor/idea-runs/{runId}/open-pr	Yes	Open a pull request for a built Cursor idea run
POST	/api/cursor/idea-runs/{runId}/questions	Yes	Ask clarification questions for a selected Cursor PR idea
POST	/api/cursor/idea-runs/{runId}/recover-agent	Yes	Start a fresh Cursor Cloud Agent from the current workflow context

HiringPartners

Method	Endpoint	Auth	Description
GET	/api/hiring-partners/apply	Yes	Get the current user's hiring-partner application
POST	/api/hiring-partners/apply	Yes	Create or update the current user's hiring-partner application

MonthlyChallenges

Method	Endpoint	Auth	Description
POST	/api/challenges/{challengeId}/submissions	Yes	Create a monthly challenge submission draft or submitted entry

NotifyAdmin

Method	Endpoint	Auth	Description
POST	/api/notify-admin/cfp	No	Email admin about a new CFP submission
POST	/api/notify-admin/event	No	Email admin about a new event request
POST	/api/notify-admin/talk	No	Email admin about a new talk submission

PromptTemplates

Method	Endpoint	Auth	Description
POST	/api/templates	Yes	Create a private prompt template draft or pending-review template

Skills

Method	Endpoint	Auth	Description
GET	/api/skills/progress	Yes	Get the current user's Skills Passport progress

SummerCohort

Method	Endpoint	Auth	Description
GET	/api/summer-cohort/admin/access	Yes	Probe whether the current user is allowed in the Summer Cohort admin area
GET	/api/summer-cohort/admin/applications	Yes	List applications (admin only) with optional cohort/status filter
GET	/api/summer-cohort/admin/intake-aggregates	Yes	Aggregate stats for intake-survey responses (admin only, no PII or free text)
DELETE	/api/summer-cohort/apply	Yes	Withdraw the current user's summer-cohort application
GET	/api/summer-cohort/apply	Yes	Get the current user's summer-cohort application + counts
POST	/api/summer-cohort/apply	Yes	Create or update the current user's summer-cohort application
POST	/api/summer-cohort/confirm-dev-env	Yes	Admitted cohort participant confirms dev environment is set up (Node + Git + IDE)
GET	/api/summer-cohort/intake-survey	Yes	Get the current user's intake-survey response
POST	/api/summer-cohort/intake-survey	Yes	Submit (or re-submit) the intake survey
GET	/api/summer-cohort/my-score/{weekId}	Yes	Return only the calling user's own AI-judge score for a vote-format week — other users' scores are never exposed by this endpoint
GET	/api/summer-cohort/submissions/{weekId}	No	Public read of merged submissions on a vote-format week
GET	/api/summer-cohort/votes	No	Aggregate vote counts for a vote-format week
POST	/api/summer-cohort/votes	Yes	Toggle the current user's vote for a submission
GET	/api/summer-cohort/withdraw	No	One-click cohort withdrawal (HMAC token in query)