Projects API

The Projects API provides full CRUD operations for managing penetration testing projects. You can create, read, update, delete, clone, and manage project status through these endpoints.

Endpoints

List Projects

Get a list of projects with optional filtering and search.

GET /api/v1/projects

Query Parameters:

search (string) - Search projects by name or description
status (string) - Filter by status: not_started, in_progress, completed, cancelled
team_id (integer) - Filter by team ID
with_trashed (boolean) - Include soft-deleted projects

Response:

{
  "success": true,
  "data": [
    {
      "id": 123,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "E-commerce Security Assessment",
      "description": "Comprehensive security testing of the new e-commerce platform",
      "status": "in_progress",
      "client": {
        "id": 1,
        "name": "Acme Corporation"
      },
      "team": {
        "id": 1,
        "name": "Red Team"
      },
      "project_type": {
        "id": 1,
        "name": "Web Application"
      },
      "start_date": "2024-03-01",
      "end_date": "2024-03-31",
      "findings_count": 15,
      "created_at": "2024-02-15T10:30:00Z",
      "updated_at": "2024-03-10T14:20:00Z"
    }
  ],
  "total": 1
}

Get Project

Get detailed information about a specific project.

GET /api/v1/projects/{project_uuid}

Response:

{
  "success": true,
  "data": {
    "id": 123,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "E-commerce Security Assessment",
    "description": "Comprehensive security testing of the new e-commerce platform",
    "status": "in_progress",
    "client": {
      "id": 1,
      "name": "Acme Corporation",
      "contact_email": "security@acme.com"
    },
    "team": {
      "id": 1,
      "name": "Red Team",
      "lead": {
        "id": 5,
        "name": "John Doe",
        "email": "john@company.com"
      }
    },
    "project_type": {
      "id": 1,
      "name": "Web Application",
      "description": "Web application penetration testing"
    },
    "scope": {
      "in_scope": [
        "https://shop.acme.com",
        "https://api.acme.com"
      ],
      "out_of_scope": [
        "https://blog.acme.com"
      ]
    },
    "attachments": [
      {
        "id": 1,
        "name": "scope_document.pdf",
        "size": 2048576,
        "uploaded_at": "2024-02-15T10:30:00Z"
      }
    ],
    "start_date": "2024-03-01",
    "end_date": "2024-03-31",
    "findings_count": 15,
    "findings_by_severity": {
      "critical": 2,
      "high": 5,
      "medium": 6,
      "low": 2,
      "informational": 0
    },
    "created_at": "2024-02-15T10:30:00Z",
    "updated_at": "2024-03-10T14:20:00Z"
  }
}

Create Project

Create a new project.

POST /api/v1/projects

Request Body:

{
  "name": "Mobile App Security Assessment",
  "description": "Security testing of iOS and Android mobile applications",
  "client_id": 1,
  "team_id": 1,
  "type_id": 2,
  "status": "not_started",
  "start_date": "2024-04-01",
  "end_date": "2024-04-30",
  "scope": {
    "in_scope": [
      "iOS App v2.1.0",
      "Android App v2.1.0"
    ],
    "out_of_scope": [
      "Legacy iOS App v1.x"
    ]
  }
}

Response:

{
  "success": true,
  "message": "Project created successfully.",
  "data": {
    "id": 124,
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Mobile App Security Assessment",
    // ... full project details
  }
}

Update Project

Update an existing project.

PUT /api/v1/projects/{project_uuid}
PATCH /api/v1/projects/{project_uuid}

Request Body (partial update with PATCH):

{
  "name": "Updated Project Name",
  "description": "Updated description",
  "end_date": "2024-05-15"
}

Delete Project

Soft delete a project.

DELETE /api/v1/projects/{project_uuid}

Response:

{
  "success": true,
  "message": "Project deleted successfully."
}

Change Project Status

Update the status of a project.

POST /api/v1/projects/{project_uuid}/status

Request Body:

{
  "status": "completed"
}

Valid Statuses:

not_started
in_progress
completed
cancelled

Clone Project

Create a copy of an existing project.

POST /api/v1/projects/{project_uuid}/clone

Request Body:

{
  "name": "Cloned Project Name",
  "client_id": 2,
  "clone_findings": true,
  "clone_attachments": false
}

Response:

{
  "success": true,
  "message": "Project cloned successfully.",
  "data": {
    "id": 125,
    "uuid": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Cloned Project Name",
    // ... cloned project details
  }
}

Restore Deleted Project

Restore a soft-deleted project.

POST /api/v1/projects/{project_uuid}/restore

Response:

{
  "success": true,
  "message": "Project restored successfully."
}

Examples

Create a New Project

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Security Test",
    "description": "Testing REST API security",
    "client_id": 1,
    "team_id": 1,
    "type_id": 1,
    "status": "not_started",
    "start_date": "2024-04-01",
    "end_date": "2024-04-15"
  }' \
  https://your-instance.pentestpad.com/api/v1/projects

List Projects with Filtering

curl -H "Authorization: Bearer your_api_key" \
     "https://your-instance.pentestpad.com/api/v1/projects?status=in_progress&team_id=1"

JavaScript Example

// Create a new project
const newProject = await fetch('/api/v1/projects', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Web App Security Review',
    description: 'Security assessment of customer portal',
    client_id: 1,
    team_id: 1,
    type_id: 1,
    status: 'not_started',
    start_date: '2024-04-01',
    end_date: '2024-04-30'
  })
}).then(r => r.json());

// Update project status
const statusUpdate = await fetch(`/api/v1/projects/${newProject.data.uuid}/status`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ status: 'in_progress' })
}).then(r => r.json());

Permissions

Project Types

Common project types include:

Web Application Testing
Mobile Application Testing
Network Penetration Testing
Wireless Security Assessment
Physical Security Assessment
Social Engineering Assessment

Contact your administrator to set up custom project types.

Error Responses

Project Not Found

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

Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "client_id": ["The selected client id is invalid."]
  }
}

Insufficient Permissions

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