Teams API

HTTP reference for teams, members, invitations, roles and permissions, shared agents and pentests, and team usage.

All paths are relative to https://api.aleex-rank.ai/api/v2 and authenticate with X-API-Key: rk_... (see REST API). For the model behind teams, roles and the shared budget, read Teams & RBAC and Teams & tiers.

Teams

GET    /teams
POST   /teams
GET    /teams/mine
GET    /teams/{id}
PATCH  /teams/{id}
DELETE /teams/{id}

GET /teams/mine returns your teams with your role in each. Create a team (it starts on Business with billing status payment_pending until the owner pays — see Billing & usage API):

{"name": "Security Team", "description": "Internal red team"}

{
  "success": true,
  "data": {
    "id": 4,
    "name": "Security Team",
    "owner_id": 42,
    "tier_id": 4,
    "tier_name": "Business",
    "billing_status": "payment_pending",
    "team_usage_budget_usd": 20.00,
    "max_members": 10,
    "member_count": 1,
    "created_at": "2026-01-12 17:47:16"
  }
}

Ownership and membership actions

POST /teams/{id}/leave
POST /teams/{id}/transfer
GET  /teams/{id}/my-roles

leave removes you from the team. transfer hands ownership (and billing responsibility) to another member:

{"new_owner_id": 77}

Members

GET    /teams/{id}/members
DELETE /teams/{id}/members/{userId}
GET    /teams/{id}/members/{userId}/roles

{
  "success": true,
  "data": [
    {"user_id": 42, "username": "alice", "is_owner": true, "roles": [{"id": 1, "role_name": "Administrator"}]},
    {"user_id": 77, "username": "bob", "is_owner": false, "roles": [{"id": 2, "role_name": "Triager"}]}
  ]
}

Invitations

Owners and admins invite by email; invitees act on the invitation from their own account.

GET    /teams/{id}/invitations
POST   /teams/{id}/invitations
POST   /teams/{id}/invitations/{invId}/resend
DELETE /teams/{id}/invitations/{invId}

Create an invitation:

{"email": "new.member@example.com", "role_ids": [2]}

The invitee manages it through the user-level invitation endpoints:

GET  /invitations
GET  /invitations/{token}
POST /invitations/{token}/accept
POST /invitations/{token}/reject

GET /invitations/{token} is public (it shows the invitation details before sign-in); the rest require authentication.

Roles and permissions

Roles live inside a team and carry permissions. Members are granted roles.

GET    /teams/{id}/roles
POST   /teams/{id}/roles
GET    /teams/{id}/roles/{roleId}
PATCH  /teams/{id}/roles/{roleId}
DELETE /teams/{id}/roles/{roleId}
GET    /teams/{id}/roles/deleted
POST   /teams/{id}/roles/{roleId}/restore
DELETE /teams/{id}/roles/{roleId}/force

Create a role:

{"role_name": "Triager", "color": "#3B82F6"}

Role permissions

GET    /teams/{id}/roles/{roleId}/permissions
POST   /teams/{id}/roles/{roleId}/permissions
DELETE /teams/{id}/roles/{roleId}/permissions/{permId}

{"permission_ids": [280, 288, 296]}

Assign and remove roles

POST /teams/{id}/roles/assign
POST /teams/{id}/roles/remove

{"user_id": 77, "role_id": 2}

When a member calls an endpoint, the platform checks the team’s plan feature gate (does the tier include it) and then the role check (does a role grant it). The owner always passes the role check. Browse assignable permissions with:

GET /permissions
GET /permissions/{id}

GET /permissions is available to Enterprise teams and to users who hold the permission; only non-protected permissions are listed.

Shared agents and pentests

GET    /teams/{id}/agents
POST   /teams/{id}/agents
DELETE /teams/{id}/agents/{agentId}
GET    /teams/{id}/pentests

GET/POST /teams/{id}/agents lists and assigns agents owned by the team; GET /teams/{id}/pentests lists the team’s pentests (filter with status, type, page, per_page). Assign an existing agent to the team:

{"agent_id": 250}

Team usage

The team’s pooled AI budget is tracked under usage. Owner only.

GET   /teams/{id}/usage/summary
GET   /teams/{id}/usage/daily
GET   /teams/{id}/usage/members
GET   /teams/{id}/usage/members/{memberId}
GET   /teams/{id}/usage/history
PATCH /teams/{id}/usage/on-demand

summary accepts ?month=, ?from=&to=, ?date= and ?model_id=; daily accepts ?period=30d|7d|1d or ?date=; history is paginated.

{
  "team": {"id": 4, "name": "Security Team", "member_count": 5, "tier": {"id": 4, "name": "Business"}},
  "budget": {"total_pool_usd": 100.00, "total_cost_usd": 45.00, "budget_remaining_usd": 55.00},
  "usage": {"total_cost_usd": 45.00, "total_operations": 200, "pentests_count": 12}
}

Toggle on-demand for the team (Enterprise/Admin may also set budget_usd):

{"enabled": true, "limit_usd": 200.00}

The response shapes mirror the personal usage endpoints in Billing & usage API, with team and per-member context added.