mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-28 13:32:23 +00:00
Steven Enamakel
4bce89c5de
- Introduced detailed architecture documentation outlining the cross-platform capabilities and high-level design of AlphaHuman. - Added MVP specification for the Telegram-based Agent Assistant, detailing phased development plans and core functionalities. - Created a complete reference for the Teams API, covering team management, member management, invite management, and billing management endpoints. - Included a TODO file to track future enhancements and features for the project. - Removed outdated example skill files for better clarity and maintenance.
531 lines
9.5 KiB
Markdown
531 lines
9.5 KiB
Markdown
# 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:**
|
|
|
|
```json
|
|
{ "name": "string (required)", "magicWord": "string (optional)" }
|
|
```
|
|
|
|
**Response Schema:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{ "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:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{ "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):**
|
|
|
|
```json
|
|
{ "maxUses": "number (default: 1)", "expiresInDays": "number (default: 7)" }
|
|
```
|
|
|
|
**Response Schema:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{ "code": "string (required, e.g., T-1A2B3C4D5E6F)" }
|
|
```
|
|
|
|
**Response Schema:**
|
|
|
|
```json
|
|
{ "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:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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):**
|
|
|
|
```json
|
|
{ "returnUrl": "string" }
|
|
```
|
|
|
|
**Response Schema:**
|
|
|
|
```json
|
|
{ "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
|
|
|
|
```json
|
|
{ "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.
|