openhuman/docs/teams-api-reference.md

AlphaHuman Teams API Reference

Complete reference for all teams-related API endpoints in the AlphaHuman platform.

Base URL: https://api.alphahuman.xyz Authentication: Bearer JWT token required for all endpoints Content-Type: application/json

---

Core Team Management

1. Create Team

POST /teams

Creates a new team with optional encryption.

Request Body:

{ "name": "string (required)", "magicWord": "string (optional)" }

Response Schema:

{
  "id": "string",
  "name": "string",
  "slug": "string",
  "magicWord": "string | null",
  "createdBy": "string",
  "isPersonal": "boolean",
  "subscription": {
    "hasActiveSubscription": "boolean",
    "plan": "FREE|BASIC|PRO",
    "planExpiry": "date-time | null",
    "stripeCustomerId": "string | null"
  },
  "usage": {
    "weeklyBudgetUsd": "number",
    "spentThisWeekUsd": "number",
    "weekStartDate": "date-time"
  },
  "inviteCode": "string | null",
  "maxMembers": "number",
  "createdAt": "date-time",
  "updatedAt": "date-time"
}

Status Codes:

• 200 - Team created successfully
• 401 - Unauthorized

---

2. List Teams

GET /teams

Retrieves all teams the authenticated user belongs to.

Response Schema:

{
  "success": true,
  "data": [
    {
      "team": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "isPersonal": "boolean",
        "subscription": { "hasActiveSubscription": "boolean", "plan": "FREE|BASIC|PRO" }
      },
      "role": "admin|billing_manager|member"
    }
  ]
}

Status Codes:

• 200 - Success
• 401 - Unauthorized

---

3. Get Team Details

GET /teams/{teamId}

Retrieves detailed information for a specific team.

Parameters:

• teamId (path, required) - Team identifier

Response Schema:

{
  "id": "string",
  "name": "string",
  "slug": "string",
  "magicWord": "string | null",
  "createdBy": "string",
  "isPersonal": "boolean",
  "subscription": {
    "hasActiveSubscription": "boolean",
    "plan": "FREE|BASIC|PRO",
    "planExpiry": "date-time | null",
    "stripeCustomerId": "string | null"
  },
  "usage": {
    "weeklyBudgetUsd": "number",
    "spentThisWeekUsd": "number",
    "weekStartDate": "date-time"
  },
  "inviteCode": "string | null",
  "maxMembers": "number",
  "createdAt": "date-time",
  "updatedAt": "date-time"
}

Status Codes:

• 200 - Success
• 403 - Not a member of the team
• 404 - Team not found

---

4. Update Team Settings

PUT /teams/{teamId}

Updates team settings. Admin only.

Parameters:

• teamId (path, required) - Team identifier

Request Body:

{ "name": "string (optional)", "maxMembers": "number (optional)" }

Status Codes:

• 200 - Team updated successfully
• 403 - Only admins can update team settings

---

5. Delete Team

DELETE /teams/{teamId}

Deletes a team. Admin only, non-personal teams only.

Parameters:

• teamId (path, required) - Team identifier

Status Codes:

• 200 - Team deleted successfully
• 400 - Cannot delete a personal team
• 403 - Only admins can delete a team

---

6. Switch Active Team

POST /teams/{teamId}/switch

Changes the user's active team.

Parameters:

• teamId (path, required) - Team identifier

Status Codes:

• 200 - Successfully switched active team
• 403 - Not a member of the specified team

---

Team Member Management

7. List Team Members

GET /teams/{teamId}/members

Lists all members of a team.

Parameters:

• teamId (path, required) - Team identifier

Response Schema:

{
  "success": true,
  "data": [{ "user": "string", "role": "admin|billing_manager|member", "joinedAt": "date-time" }]
}

Status Codes:

• 200 - Success
• 403 - Not a member of this team

---

8. Remove Team Member

DELETE /teams/{teamId}/members/{userId}

Removes a member from the team. Admin only.

Parameters:

• teamId (path, required) - Team identifier
• userId (path, required) - User identifier to remove

Status Codes:

• 200 - Member removed
• 403 - Only admins can remove members

---

9. Change Member Role

PUT /teams/{teamId}/members/{userId}/role

Changes a member's role within the team. Admin only.

Parameters:

• teamId (path, required) - Team identifier
• userId (path, required) - User identifier

Request Body:

{ "role": "admin|billing_manager|member" }

Status Codes:

• 200 - Role updated
• 403 - Only admins can change member roles

---

10. Leave Team

POST /teams/{teamId}/leave

Allows a user to leave a team.

Parameters:

• teamId (path, required) - Team identifier

Status Codes:

• 200 - Successfully left the team
• 400 - Cannot leave as the only admin

---

Team Invite Management

11. Create Team Invite

POST /teams/{teamId}/invites

Creates a new invite code for the team.

Parameters:

• teamId (path, required) - Team identifier

Request Body (Optional):

{ "maxUses": "number (default: 1)", "expiresInDays": "number (default: 7)" }

Response Schema:

{
  "success": true,
  "data": { "code": "string (e.g., T-1A2B3C4D5E6F)", "expiresAt": "date-time", "maxUses": "number" }
}

Status Codes:

• 200 - Invite created successfully
• 403 - Not a team member

---

12. List Team Invites

GET /teams/{teamId}/invites

Lists all invites for a team.

Parameters:

• teamId (path, required) - Team identifier

Status Codes:

• 200 - Success
• 403 - User is not a member of the team

---

13. Revoke Team Invite

DELETE /teams/{teamId}/invites/{inviteId}

Revokes a team invite. Admin or invite creator only.

Parameters:

• teamId (path, required) - Team identifier
• inviteId (path, required) - Invite identifier

Status Codes:

• 200 - Invite successfully revoked
• 403 - Only admins or invite creator can revoke
• 404 - Invite does not exist

---

14. Join Team

POST /teams/join

Joins a team using an invite code.

Request Body:

{ "code": "string (required, e.g., T-1A2B3C4D5E6F)" }

Response Schema:

{ "success": true, "data": { "team": "string", "membership": "string" } }

Status Codes:

• 200 - Joined the team successfully
• 400 - Invite expired, max uses reached, or already a team member
• 404 - Invite code not found

---

Team Billing Management

15. Purchase Team Subscription

POST /teams/{teamId}/billing/purchase

Purchases a subscription plan for the team. Admin or billing manager only.

Parameters:

• teamId (path, required) - Team identifier

Request Body:

{
  "plan": "BASIC_MONTHLY|BASIC_YEARLY|PRO_MONTHLY|PRO_YEARLY",
  "successUrl": "string (optional)",
  "cancelUrl": "string (optional)"
}

Status Codes:

• 200 - Checkout session created successfully
• 403 - Only admins or billing managers can purchase plans

---

16. Get Team Subscription Plan

GET /teams/{teamId}/billing/plan

Retrieves the team's current subscription information.

Parameters:

• teamId (path, required) - Team identifier

Response Schema:

{
  "success": true,
  "data": {
    "plan": "FREE|BASIC|PRO",
    "hasActiveSubscription": "boolean",
    "planExpiry": "date-time | null"
  }
}

Status Codes:

• 200 - Success
• 401 - Unauthorized

---

17. Create Billing Portal Session

POST /teams/{teamId}/billing/portal

Creates a Stripe billing portal session for subscription management. Admin or billing manager only.

Parameters:

• teamId (path, required) - Team identifier

Request Body (Optional):

{ "returnUrl": "string" }

Response Schema:

{ "success": true, "data": { "url": "string" } }

Status Codes:

• 200 - Portal session created successfully
• 403 - Only admins or billing managers can create portal session

---

Team Roles

Role Hierarchy

1. admin - Full team management permissions
2. billing_manager - Billing and subscription management
3. member - Basic team member access

Permission Matrix

Action	Admin	Billing Manager	Member
View team details	✅	✅	✅
Update team settings	✅	❌	❌
Delete team	✅	❌	❌
Add/remove members	✅	❌	❌
Change member roles	✅	❌	❌
Create invites	✅	✅	✅
Manage billing	✅	✅	❌
Leave team	✅*	✅	✅

*Admin cannot leave if they are the only admin

---

Team Plans & Limits

Plan Types

• FREE - Basic team functionality
• BASIC - Enhanced features and limits
• PRO - Full feature set and highest limits

Usage Tracking

Teams have usage limits tracked through:

• weeklyBudgetUsd - Weekly spending budget
• spentThisWeekUsd - Current week spending
• weekStartDate - When the current week started
• maxMembers - Maximum team size

---

Error Handling

Common Error Responses

{ "success": false, "error": "Error message description" }

Authentication

All endpoints require a Bearer JWT token:

Authorization: Bearer <your-jwt-token>

Rate Limiting

Standard API rate limits apply to all endpoints. Refer to main API documentation for specific limits.