API Documentation — PentestAI

Overview

The PentestAI backend exposes a REST API that powers the Control Center. It is designed around the principle of least privilege: every request must present valid credentials, and actions are further gated by device pairing and the Guardian approval queue.

Base URL

https://api.pentestai.ca/v1

Backend endpoint provided after early access onboarding. Do not expose your real backend IP in public docs.

Authentication

All API requests require two layers of authentication:

API Key — issued during device pairing. Pass it in the X-API-Key header.
Session Token — obtained after pairing. Pass it in the Authorization header as a Bearer token.

GET /api/v1/status
X-API-Key: your_api_key_here
Authorization: Bearer your_session_token_here

Endpoints

Method	Endpoint	Description
GET	/status	Check backend and authentication health.
POST	/devices/pair	Pair a new device and receive a session token.
GET	/metrics	Retrieve live system metrics (CPU, RAM, disk, uptime).
POST	/agent/ask	Send a natural‑language request to the AI Agent.
POST	/commands/queue	Queue a shell command for Guardian approval.
GET	/commands/queue	List commands awaiting approval.
POST	/commands/{id}/approve	Approve and execute a queued command.
POST	/commands/{id}/deny	Reject a queued command.
GET	/reports	List generated security reports.
POST	/reports/generate	Generate a new client‑ready security report.

Examples

Check system status

curl -X GET https://api.pentestai.ca/v1/status \
  -H "X-API-Key: your_api_key" \
  -H "Authorization: Bearer your_session_token"

Sample response

{
  "status": "ok",
  "authenticated": true,
  "paired": true,
  "version": "28",
  "timestamp": "2025-01-15T14:32:00Z"
}

Error Handling

The API returns standard HTTP status codes. Error responses include a JSON body with a detail field.

Code	Meaning
401	Unauthorized — missing or invalid API key / session token.
403	Forbidden — device is not paired or lacks permission.
422	Unprocessable Entity — command blocked by Safe Mode.
429	Too Many Requests — rate limit exceeded.
500	Internal Server Error — please contact support.

PentestAI API Reference