Teams
Read teams directly, or use the organizer team-management surface for full CRUD
over teams: create them, edit metadata, assign members, transfer leadership, move
them between tracks. The management endpoints live under
/super-events/:superEventId/team-management/*. Click an endpoint to expand its
tabs. Success responses use the standard { "success": true, "data": ... } envelope.
Field-casing note: the team-management list/detail reads return camelCase, mapped fields (
userId,avatarUrl,createdAt). ThePOST/PATCH /teamswrites return the raw snake_case database row (event_id,is_open,created_at). Plan for both.
Read
List teams (by track) GET /events/:eventId/teams
{ "data": { "teams": [ { "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "name": "Beat Wizards", "member_count": 4 } ], "count": 12 }}Optional query params: limit, offset, search.
Get team (with members) GET /teams/:id
{ "data": { "team": { "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "name": "Beat Wizards", "event_id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16" }, "members": [ { "user_id": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "role": "LEADER", "name": "Alice Rivera", "email": "alice.rivera@northwind.io" } ], "member_count": 4 }} Get team & builder counts GET /super-events/:id/team-management/counts
{ "data": { "builders": { "all": 120, "lookingForTeam": 30, "withTeam": 80 }, "teams": { "all": 25, "lookingForMembers": 10, "closed": 8, "full": 7 } }}Aggregate counts by track - useful for dashboards. Optional ?trackId filter.
List builders GET /super-events/:id/team-management/builders
{ "data": { "builders": [ { "type": "builder", "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "registrationId": "9f2c4a18-7b3d-4e60-a512-6c8d0f2a4b73", "name": "Alice Rivera", "email": "alice.rivera@northwind.io", "avatarUrl": "https://cdn.builderbase.com/avatars/alice.png", "status": "accepted", "trackIds": [ "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16" ], "tracks": [ { "id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "name": "Autonomous Agents Track", "slug": "autonomous-agents" } ], "activeTeam": { "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "name": "Beat Wizards", "trackId": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "trackName": "Autonomous Agents Track", "role": "LEADER" }, "interestedTrackIds": [ "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16" ], "squad": null, "lookingForTeam": false, "createdAt": "2026-07-14T09:00:00.000Z", "updatedAt": "2026-07-14T09:00:00.000Z" } ], "pagination": { "limit": 30, "nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTA3LTE0In0", "hasMore": true } }}Cursor-paginated. Filters: search, trackId, teamState, cursor, limit.
activeTeam is null when the builder is unassigned. Paginate with pagination.nextCursor.
Get builder details GET /super-events/:id/team-management/builders/:userId
{ "data": { "builder": { "type": "builder", "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "name": "Alice Rivera", "email": "alice.rivera@northwind.io", "status": "accepted", "activeTeam": { "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "name": "Beat Wizards", "trackId": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "role": "MEMBER" }, "answers": { "github": "https://github.com/arivera" }, "trackRegistrations": [ { "id": "9f2c4a18-7b3d-4e60-a512-6c8d0f2a4b73", "track": { "id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "name": "Autonomous Agents Track", "slug": "autonomous-agents" }, "status": "accepted", "lookingForTeam": false, "createdAt": "2026-07-14T09:00:00.000Z" } ], "teamHistory": [ { "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "teamName": "Beat Wizards", "track": { "id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "name": "Autonomous Agents Track", "slug": "autonomous-agents" }, "role": "MEMBER", "joinedAt": "2026-07-14T09:00:00.000Z", "leftAt": null } ] } }}Richer than the list - adds answers, per-track registrations, and team history.
List teams GET /super-events/:id/team-management/teams
{ "data": { "teams": [ { "type": "team", "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "name": "Beat Wizards", "avatarUrl": "https://cdn.builderbase.com/avatars/beat-wizards.png", "problem": "Cut support response time in half with an agent", "track": { "id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "name": "Autonomous Agents Track", "slug": "autonomous-agents" }, "memberCount": 4, "maxMembers": 5, "status": "looking_for_members", "recruitingStatus": "looking_for_members", "isFull": false, "leader": { "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "name": "Alice Rivera", "email": "alice.rivera@northwind.io", "role": "LEADER", "joinedAt": "2026-07-14T09:00:00.000Z" }, "hasSubmission": false, "createdAt": "2026-07-14T09:00:00.000Z", "updatedAt": "2026-07-14T09:00:00.000Z", "members": [ { "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "name": "Alice Rivera", "email": "alice.rivera@northwind.io", "role": "LEADER", "joinedAt": "2026-07-14T09:00:00.000Z" } ], "submission": null } ], "pagination": { "limit": 30, "nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTA3LTE0In0", "hasMore": true } }}Cursor-paginated. Filters: search, trackId, status, cursor, limit.
status is one of full, looking_for_members, closed.
Get team details GET /super-events/:id/team-management/teams/:teamId
{ "data": { "team": { "type": "team", "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "name": "Beat Wizards", "track": { "id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "name": "Autonomous Agents Track", "slug": "autonomous-agents" }, "memberCount": 4, "status": "closed", "leader": { "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "name": "Alice Rivera", "role": "LEADER" }, "members": [ { "userId": "c4e9f2a1-5d6b-4f0c-9e28-4a7b1d3c6f05", "name": "Bob Chen", "role": "MEMBER", "joinedAt": "2026-07-14T09:00:00.000Z" } ] } }} List team members GET /super-events/:id/team-management/teams/:teamId/members
{ "data": { "members": [ { "userId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "name": "Alice Rivera", "email": "alice.rivera@northwind.io", "avatarUrl": "https://cdn.builderbase.com/avatars/alice.png", "role": "LEADER", "joinedAt": "2026-07-14T09:00:00.000Z" } ], "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53" }}Active members only, sorted by join time, with their roles (LEADER / MEMBER).
Write
Create a team POST /super-events/:superEventId/team-management/teams
{ "data": { "team": { "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "event_id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "name": "Beat Wizards", "problem": "Cut support response time in half with an agent", "is_open": true, "squad_id": null, "created_at": "2026-07-14T09:00:00.000Z", "updated_at": "2026-07-14T09:00:00.000Z" } }}{ "name": "Beat Wizards", "trackId": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "problem": "Cut support response time in half with an agent", "recruitingStatus": "looking_for_members"}| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 2 to 100 characters. |
trackId | string (UUID) | Yes | Must be a track of this super event. Stored as event_id. |
problem | string | null | No | Up to 500 chars. Use it to encode a per-team challenge. |
recruitingStatus | string (enum) | No | looking_for_members or closed. |
Returns 201; the team is the raw snake_case DB row. Use problem to encode a
per-team challenge (e.g. a distinct sponsor problem each team works on).
Update a team PATCH /super-events/:superEventId/team-management/teams/:teamId
{ "data": { "team": { "id": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "event_id": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "name": "Renamed Team", "problem": "Updated challenge text", "is_open": false, "squad_id": null, "created_at": "2026-07-14T09:00:00.000Z", "updated_at": "2026-07-14T10:30:00.000Z" } }}{ "name": "Renamed Team", "problem": "Updated challenge text", "recruitingStatus": "closed", "avatar_url": "https://..."}All fields optional - send any subset.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | 2 to 100 characters. |
problem | string | null | No | Up to 500 chars. |
recruitingStatus | string (enum) | No | looking_for_members or closed. |
avatar_url | string | null | No |
Update name, problem, recruiting status, or avatar. Returns the raw snake_case team row.
Delete a team DELETE /super-events/:superEventId/team-management/teams/:teamId
{ "data": { "result": { "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "deleted": true, "actorUserId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94" } }}Soft-delete - all members are removed, then the team is marked as deleted.
Move team to track PATCH /super-events/:superEventId/team-management/teams/:teamId/track
{ "data": { "result": { "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "fromEventId": "8d1b3f50-2a6c-4e71-9b04-1c5d7e9a0f32", "toEventId": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16", "movedMemberUserIds": [ "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "c4e9f2a1-5d6b-4f0c-9e28-4a7b1d3c6f05" ] } }}{ "targetTrackId": "5c1f8a73-6d2b-4e90-a1c4-7b8e3f0d2a16"}| Field | Type | Required | Notes |
|---|---|---|---|
targetTrackId | string (UUID) | Yes | A track of the same super event. |
Add team member POST /super-events/:superEventId/team-management/teams/:teamId/members
{ "data": { "result": { "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "userId": "c4e9f2a1-5d6b-4f0c-9e28-4a7b1d3c6f05" } }}{ "userId": "c4e9f2a1-5d6b-4f0c-9e28-4a7b1d3c6f05", "role": "MEMBER", "replacementLeaderUserId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94"}| Field | Type | Required | Notes |
|---|---|---|---|
userId | string (UUID) | Yes | Must be a participant on this super event with an accepted registration. |
role | string (enum) | No | LEADER or MEMBER. Defaults to MEMBER. |
replacementLeaderUserId | string | null | No | Only if moving the participant off another team they led. |
Remove team member POST /super-events/:superEventId/team-management/teams/:teamId/members/:userId/remove
{ "data": { "result": { "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "userId": "c4e9f2a1-5d6b-4f0c-9e28-4a7b1d3c6f05", "actorUserId": "b3d8e1f0-2c5a-4e9b-8d17-3f6a0c2b5e94", "replacementLeaderUserId": "a1c3e5f7-9b2d-4f80-8c16-3e5a7c9b1d04" } }}Body optional; include replacementLeaderUserId if the removed member was the leader.
Transfer team leadership POST /super-events/:superEventId/team-management/teams/:teamId/transfer-leadership
{ "data": { "result": { "teamId": "7e3a0c92-1b5d-4f86-9c20-2d4a6b8e1f53", "newLeaderUserId": "c4e9f2a1-5d6b-4f0c-9e28-4a7b1d3c6f05" } }}{ "newLeaderUserId": "c4e9f2a1-5d6b-4f0c-9e28-4a7b1d3c6f05"}| Field | Type | Required | Notes |
|---|---|---|---|
newLeaderUserId | string (UUID) | Yes | Must already be an active member of the team. |
The new leader must already be an active member of the team.