Teams API

The Teams API allows you to list teams, get team details, and filter other resources by team. This is useful for multi-team organizations where resources need to be segmented by team membership.

Endpoints

List All Teams

Get a list of all teams you have access to.

GET /api/v1/teams

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Red Team",
      "description": "Offensive security team",
      "members_count": 8,
      "active_projects": 3,
      "created_at": "2024-01-15T10:30:00.000000Z"
    },
    {
      "id": 2,
      "name": "Blue Team",
      "description": "Defensive security team",
      "members_count": 12,
      "active_projects": 5,
      "created_at": "2024-01-20T14:20:00.000000Z"
    }
  ],
  "total": 2
}

Get My Teams

Get only the teams that the authenticated user is a member of.

GET /api/v1/teams/my

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Red Team",
      "description": "Offensive security team",
      "role": "member",
      "joined_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "total": 1
}

Get Teams (Paginated)

Get teams with pagination support for large organizations.

GET /api/v1/teams/paginated?page=1&per_page=10

Query Parameters:

page (integer) - Page number (default: 1)
per_page (integer) - Items per page (default: 15, max: 100)
search (string) - Search teams by name or description

Response:

{
  "success": true,
  "data": [
    // Team objects...
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 25,
    "last_page": 3
  }
}

Get Team Details

Get detailed information about a specific team.

GET /api/v1/teams/{team_id}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Red Team",
    "description": "Offensive security team specializing in penetration testing",
    "members_count": 8,
    "active_projects": 3,
    "completed_projects": 15,
    "total_findings": 247,
    "members": [
      {
        "id": 5,
        "name": "John Doe",
        "email": "john@company.com",
        "role": "team_lead",
        "joined_at": "2024-01-15T10:30:00.000000Z"
      },
      {
        "id": 8,
        "name": "Jane Smith",
        "email": "jane@company.com",
        "role": "member",
        "joined_at": "2024-02-01T09:15:00.000000Z"
      }
    ],
    "recent_projects": [
      {
        "id": 123,
        "uuid": "project-uuid-here",
        "name": "E-commerce Security Assessment",
        "status": "in_progress",
        "created_at": "2024-03-01T11:00:00.000000Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-03-15T16:45:00.000000Z"
  }
}

Get Team Statistics

Get statistical data for a team’s performance and activity.

GET /api/v1/teams/{team_id}/stats

Response:

{
  "success": true,
  "data": {
    "team_id": 1,
    "team_name": "Red Team",
    "time_period": "last_30_days",
    "statistics": {
      "projects": {
        "total": 18,
        "active": 3,
        "completed": 15,
        "avg_completion_time_days": 21
      },
      "findings": {
        "total": 247,
        "by_severity": {
          "critical": 12,
          "high": 45,
          "medium": 89,
          "low": 78,
          "informational": 23
        },
        "avg_per_project": 13.7
      },
      "activity": {
        "projects_created": 4,
        "findings_added": 67,
        "reports_generated": 8
      }
    },
    "generated_at": "2024-03-15T16:45:00.000000Z"
  }
}

Using Teams for Filtering

Most other API endpoints support filtering by team using the team_id parameter:

Filter Projects by Team

GET /api/v1/projects?team_id=1

Filter Findings by Team

GET /api/v1/findings?team_id=1

Examples

Get All Teams

curl -H "Authorization: Bearer your_api_key" \
     https://your-instance.pentestpad.com/api/v1/teams

Get Team with Statistics

curl -H "Authorization: Bearer your_api_key" \
     https://your-instance.pentestpad.com/api/v1/teams/1/stats

JavaScript Example

// Get teams and filter projects
const teams = await fetch('/api/v1/teams', {
  headers: { 'Authorization': 'Bearer your_api_key' }
}).then(r => r.json());

const redTeamProjects = await fetch(`/api/v1/projects?team_id=${teams.data[0].id}`, {
  headers: { 'Authorization': 'Bearer your_api_key' }
}).then(r => r.json());

Team Permissions

Error Responses

Team Not Found

{
  "success": false,
  "message": "Team not found."
}

Insufficient Permissions

{
  "success": false,
  "message": "You don't have permission to view this team."
}