# Complete Guide to Pentagi API Endpoints: REST API Reference for Automation

> Explore Pentagi's comprehensive REST API endpoints for automation. Discover how to leverage our API for authentication penetration testing container orchestration and system administration.

- Repository: [VXControl/pentagi](https://github.com/vxcontrol/pentagi)
- Tags: api-reference
- Published: 2026-03-21

---

**Pentagi exposes a comprehensive REST API built on the Gin framework, with all endpoints mounted under `/api/v1` and defined centrally in [`backend/pkg/server/router.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/server/router.go), covering authentication, penetration testing flows, container orchestration, and system administration.**

The [vxcontrol/pentagi](https://github.com/vxcontrol/pentagi) repository implements a Go-based HTTP server that provides programmatic access to its AI-powered penetration testing engine. Understanding the Pentagi API endpoints enables security teams to automate workflow creation, extract execution artifacts, and integrate pentest results into external CI/CD pipelines.

## API Architecture and Base Configuration

Pentagi’s HTTP layer relies on the **Gin web framework** with centralized route registration located in [[`backend/pkg/server/router.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/server/router.go)](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go). All REST endpoints share a configurable **base URL** (defaulting to `/api/v1`) and are wrapped by middleware handling CORS, session management, request logging, and static file serving. The router organizes endpoints into functional groups—authentication, flows, containers, logs, and system resources—while the Swagger UI and OpenAPI specification remain available at `GET /swagger/*any` ([`router.go:203`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L203)).

## Authentication and Session Management

The `/auth` namespace handles identity verification via local credentials and OAuth2 providers. Session state is maintained through cookies and JWT tokens.

- **`GET /auth/info`** – Returns a minimal health-check payload confirming API availability ([`router.go:198`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L198)).
- **`POST /auth/login`** – Authenticates with username and password, issuing a session cookie and JWT ([`router.go:208`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L208)).
- **`GET /auth/logout`** – Terminates the current session and clears authentication cookies ([`router.go:209`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L209)).
- **`GET /auth/authorize`** – Initiates an OAuth2 authorization flow via external identity providers ([`router.go:210`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L210)).
- **`GET /auth/login-callback`** – OAuth2 callback handler for GET requests ([`router.go:211`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L211)).
- **`POST /auth/login-callback`** – OAuth2 callback handler for POST requests ([`router.go:212`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L212)).
- **`POST /auth/logout-callback`** – OAuth2 logout callback for provider sign-out flows ([`router.go:213`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L213)).
- **`PUT /auth/password`** – Updates the authenticated user’s password ([`router.go:193`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L193)).

## Flow Management and Task Orchestration

**Flows** represent the core penetration-testing objects in Pentagi. The API supports full CRUD operations, execution graph retrieval, and nested resource management for tasks and AI assistants.

- **`GET /flows/`** – Retrieves all penetration testing flows ([`router.go:362`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L362)).
- **`POST /flows/`** – Creates a new flow; accepts custom function definitions and target specifications in the request body ([`router.go:347`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L347)).
- **`GET /flows/:flowID`** – Fetches detailed metadata for a specific flow ([`router.go:363`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L363)).
- **`PUT /flows/:flowID`** – Partially updates an existing flow’s configuration ([`router.go:357`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L357)).
- **`GET /flows/:flowID/graph`** – Returns the flow’s execution graph in DOT or JSON format for visualization ([`router.go:364`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L364)).

### Tasks and Subtasks

- **`GET /flows/:flowID/subtasks/`** – Lists all subtasks belonging to a flow ([`router.go:325`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L325)).
- **`GET /flows/:flowID/tasks/`** – Retrieves high-level tasks for the flow ([`router.go:338`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L338)).
- **`GET /flows/:flowID/tasks/:taskID`** – Gets detailed information for a specific task ([`router.go:339`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L339)).
- **`GET /flows/:flowID/tasks/:taskID/graph`** – Returns the execution graph for an individual task ([`router.go:340`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L340)).

### AI Assistants

- **`POST /flows/:flowID/assistants`** – Creates a new AI assistant instance attached to the flow ([`router.go:384`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L384)).
- **`PUT /flows/:assistantID`** – Updates an existing assistant’s configuration ([`router.go:394`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L394)).
- **`GET /flows/:flowID/assistants/`** – Lists all assistants associated with the flow ([`router.go:399`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L399)).
- **`GET /flows/:assistantID`** – Retrieves a specific assistant by its unique identifier ([`router.go:400`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L400)).

## Provider Configuration

Pentagi integrates with external LLMs and search engines. The providers endpoint exposes current configuration without exposing secrets.

- **`GET /providers/`** – Lists all configured LLM and search providers ([`router.go:311`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L311)).

## Container and Sandbox Management

Docker containers provide isolated execution environments for Pentagi agents. Endpoints support both global and flow-scoped container queries.

- **`GET /containers/`** – Lists all running containers across the system ([`router.go:371`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L371)).
- **`GET /flows/:flowID/containers/`** – Retrieves containers specifically assigned to a flow ([`router.go:376`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L376)).
- **`GET /flows/:flowID/containers/:containerID`** – Fetches metadata for a specific container instance ([`router.go:377`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L377)).

## Logging and Observability

Pentagi maintains granular audit logs for agents, assistants, messages, and terminal sessions. All log endpoints support both global and flow-scoped retrieval.

### Agent and Assistant Logs

- **`GET /agentlogs/`** – System-wide agent activity logs ([`router.go:407`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L407)).
- **`GET /flows/:flowID/agentlogs/`** – Agent logs filtered to a specific flow ([`router.go:412`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L412)).
- **`GET /assistantlogs/`** – Global assistant interaction logs ([`router.go:419`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L419)).
- **`GET /flows/:flowID/assistantlogs/`** – Assistant logs scoped to a flow ([`router.go:424`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L424)).

### Communication and Search Logs

- **`GET /msglogs/`** – All message logs between agents and users ([`router.go:431`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L431)).
- **`GET /flows/:flowID/msglogs/`** – Message logs for a specific flow ([`router.go:436`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L436)).
- **`GET /searchlogs/`** – Global search engine query logs ([`router.go:443`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L443)).
- **`GET /flows/:flowID/searchlogs/`** – Search logs per flow ([`router.go:448`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L448)).

### Terminal and Screenshot Artifacts

- **`GET /termlogs/`** – Terminal interaction logs across all sessions ([`router.go:455`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L455)).
- **`GET /flows/:flowID/termlogs/`** – Terminal logs for a specific flow ([`router.go:460`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L460)).
- **`GET /screenshots/`** – Lists screenshot metadata globally ([`router.go:479`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L479)).
- **`GET /flows/:flowID/screenshots/`** – Screenshots belonging to a flow ([`router.go:484`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L484)).
- **`GET /flows/:flowID/screenshots/:screenshotID`** – Detailed metadata for a specific screenshot ([`router.go:485`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L485)).
- **`GET /flows/:flowID/screenshots/:screenshotID/file`** – Binary image download endpoint ([`router.go:486`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L486)).

## System Administration Resources

Administrators manage prompt templates, user accounts, roles, and API tokens through dedicated REST resources.

### Prompt Templates

- **`GET /prompts/`** – Lists all available prompt templates ([`router.go:493`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L493)).
- **`GET /prompts/:promptType`** – Retrieves a specific prompt template by type ([`router.go:494`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L494)).
- **`PUT /prompts/:promptType`** – Updates the content of a prompt template ([`router.go:499`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L499)).
- **`POST /prompts/:promptType/default`** – Resets a prompt to its default system value ([`router.go:500`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L500)).

### Roles and Users

- **`GET /roles/`** – Lists role definitions for access control ([`router.go:508`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L508)).
- **`GET /roles/:roleID`** – Retrieves a specific role by identifier ([`router.go:509`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L509)).
- **`GET /users/`** – Admin endpoint listing all users ([`router.go:531`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L531)).
- **`GET /users/:hash`** – Retrieves a user by their hash identifier ([`router.go:532`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L532)).
- **`POST /users/`** – Creates a new user account (admin only) ([`router.go:516`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L516)).
- **`PUT /users/:hash`** – Updates user fields and permissions ([`router.go:526`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L526)).

### Usage Analytics and Identity

- **`GET /me/`** (exposed as `/`) – Returns the current authenticated user profile and system settings ([`router.go:537`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L537)).
- **`GET /usage/`** – System-wide usage statistics ([`router.go:545`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L545)).
- **`GET /usage/:period`** – Usage metrics for a specific time period (e.g., `daily`, `weekly`) ([`router.go:546`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L546)).
- **`GET /flows/:flowID/usage/`** – Flow-specific usage analytics ([`router.go:552`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L552)).

### API Token Lifecycle

- **`GET /tokens/`** – Lists all API tokens for automation ([`router.go:560`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L560)).
- **`GET /tokens/:tokenID`** – Retrieves details for a specific token ([`router.go:561`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L561)).
- **`POST /tokens/`** – Creates a new API token with specified scopes ([`router.go:559`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L559)).
- **`PUT /tokens/:tokenID`** – Updates token state (enable, disable, or rotate) ([`router.go:562`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L562)).

## Developer Tools and Documentation

Pentagi exposes interactive documentation and debugging interfaces alongside the REST API.

- **`GET /graphql/playground`** – Serves the GraphQL Playground UI for debugging queries ([`router.go:202`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L202)).
- **`GET /swagger/*any`** – Serves the Swagger UI and OpenAPI JSON specification for the REST API ([`router.go:203`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L203)).

## Practical API Integration Examples

The following `curl` commands demonstrate common interactions with Pentagi API endpoints. Examples assume the server runs at `https://localhost:8443` with the default base path `/api/v1`.

### Authenticate and Persist Session

Store the session cookie after login for subsequent authenticated requests:

```bash
curl -i -c cookie.txt -X POST https://localhost:8443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourStrongPassword123!"}'

```

### Create a New Penetration Testing Flow

Initiate an automated security assessment targeting specific URLs:

```bash
curl -b cookie.txt -X POST https://localhost:8443/api/v1/flows/ \
  -H "Content-Type: application/json" \
  -d '{
        "name":"Automated Web Scan",
        "description":"Security assessment of example.com",
        "targets":["https://example.com"]
      }'

```

### Retrieve Execution Graphs

Download the DOT-formatted execution graph for flow ID `42` to visualize agent decision paths:

```bash
curl -b cookie.txt https://localhost:8443/api/v1/flows/42/graph

```

### Download Agent Screenshots

Fetch binary screenshot artifacts captured during automated testing:

```bash
curl -b cookie.txt -O \
  https://localhost:8443/api/v1/flows/42/screenshots/7/file

```

### Create API Tokens for CI/CD Automation

Generate a scoped token for non-interactive automation:

```bash
curl -b cookie.txt -X POST https://localhost:8443/api/v1/tokens/ \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-runner","scopes":["flow:read","flow:execute"]}'

```

### Reset Prompt Templates to Defaults

Restore the initial prompt configuration after customization:

```bash
curl -b cookie.txt -X POST https://localhost:8443/api/v1/prompts/initial/default

```

## Summary

- **Centralized Routing**: All Pentagi API endpoints are defined in [[`backend/pkg/server/router.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/server/router.go)](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go) using the Gin framework, mounted under `/api/v1`.
- **Authentication**: Supports local username/password sessions and OAuth2 flows via `/auth` endpoints, with session persistence via cookies and JWT.
- **Core Resources**: Flows, tasks, assistants, and containers form the primary pentesting object model, accessible via CRUD operations and graph retrieval endpoints.
- **Observability**: Comprehensive logging endpoints cover agent activity, terminal sessions, messages, search queries, and screenshots, available globally or per-flow.
- **Administration**: System configuration includes prompt template management, user/role administration, usage analytics, and API token lifecycle management.
- **Documentation**: Interactive Swagger UI and GraphQL Playground available at `/swagger` and `/graphql/playground` respectively.

## Frequently Asked Questions

### How do I authenticate with the Pentagi API?

Pentagi supports session-based authentication via `POST /auth/login` with username and password credentials, returning a session cookie and JWT token. For service-to-service automation, create long-lived API tokens via `POST /tokens/` and include them in the `Authorization: Bearer <token>` header or use session cookies as demonstrated in the practical examples.

### What is the base URL for all Pentagi API endpoints?

All REST endpoints are mounted under a configurable base path that defaults to `/api/v1`. The complete URL structure follows `https://<host>:<port>/api/v1/<resource>`, as defined in the router configuration within [[`backend/pkg/server/router.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/server/router.go)](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go).

### Can I retrieve execution artifacts like terminal logs and screenshots via the API?

Yes. Pentagi provides dedicated endpoints for observability data. Access terminal logs via `/flows/:flowID/termlogs/`, agent logs via `/flows/:flowID/agentlogs/`, and screenshot binaries via `/flows/:flowID/screenshots/:screenshotID/file`. All artifact endpoints support both global and flow-scoped retrieval patterns.

### Where can I find the complete OpenAPI specification for Pentagi?

The Swagger UI and underlying OpenAPI JSON specification are served at `GET /swagger/*any` ([`router.go:203`](https://github.com/vxcontrol/pentagi/blob/master/backend/pkg/server/router.go#L203)). This interactive documentation covers all available endpoints, request schemas, and response formats based on the annotations embedded in the Go source code.