mirror of https://github.com/tinyhumansai/openhuman.git synced 2026-07-27 21:08:00 +00:00

Files

T

Steven Enamakel 4a8c3265a9 Refactor API documentation and improve code formatting

- Simplified JSON formatting in `.mcp.json` for better readability.
- Updated API reference documentation for team management endpoints to use consistent JSON formatting.
- Enhanced code readability in various components by standardizing formatting and removing unnecessary line breaks.
- Improved user interface elements in TeamInvitesPanel and TeamManagementPanel for better clarity and consistency.

2026-02-10 22:34:34 +05:30

9.5 KiB

Raw Blame History

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

admin - Full team management permissions
billing_manager - Billing and subscription management
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.

9.5 KiB Raw Blame History

AlphaHuman Teams API Reference

Core Team Management

1. Create Team

2. List Teams

3. Get Team Details

4. Update Team Settings

5. Delete Team

6. Switch Active Team

Team Member Management

7. List Team Members

8. Remove Team Member

9. Change Member Role

10. Leave Team

Team Invite Management

11. Create Team Invite

12. List Team Invites

13. Revoke Team Invite

14. Join Team

Team Billing Management

15. Purchase Team Subscription

16. Get Team Subscription Plan

17. Create Billing Portal Session

Team Roles

Role Hierarchy

Permission Matrix

Team Plans & Limits

Plan Types

Usage Tracking

Error Handling

Common Error Responses

Authentication

Rate Limiting

9.5 KiB

Raw Blame History