Skip to main content

​
Overview

Flows represent complete penetration testing sessions in PentAGI. Each flow manages an isolated execution environment with Docker containers, AI agents, and comprehensive logging.

​
Flow Type

type Flow {
  id: ID!
  title: String!
  status: StatusType!
  terminals: [Terminal!]
  provider: Provider!
  createdAt: Time!
  updatedAt: Time!
}

​
Fields

​
id
ID
required
Unique identifier for the flow
​
title
String
required
Human-readable title describing the flow objective
​
status
StatusType
required
Current execution status: created, running, waiting, finished, failed
​
terminals
[Terminal!]
Docker containers (terminals) associated with this flow
​
provider
Provider
required
LLM provider used for this flow (OpenAI, Anthropic, etc.)
​
createdAt
Time
required
Timestamp when the flow was created
​
updatedAt
Time
required
Timestamp of last flow update

​
Terminal Type

type Terminal {
  id: ID!
  type: TerminalType!
  name: String!
  image: String!
  connected: Boolean!
  createdAt: Time!
}
Terminals represent Docker containers where commands are executed.
​
type
TerminalType
required
Terminal type: primary or secondary
​
image
String
required
Docker image used for the container (e.g., vxcontrol/pentagi-kali)
​
connected
Boolean
required
Whether the container is currently running and accessible

​
Queries

​
List All Flows

Retrieve all flows accessible to the authenticated user. 
query {
  flows {
    id
    title
    status
    provider {
      name
      type
    }
    createdAt
    updatedAt
  }
}
Response: 
{
  "data": {
    "flows": [
      {
        "id": "1",
        "title": "Web Application Security Assessment",
        "status": "running",
        "provider": {
          "name": "default-openai",
          "type": "openai"
        },
        "createdAt": "2024-02-20T10:30:00Z",
        "updatedAt": "2024-02-20T10:45:00Z"
      }
    ]
  }
}

​
Get Single Flow

Retrieve detailed information about a specific flow. 
query GetFlow($id: ID!) {
  flow(flowId: $id) {
    id
    title
    status
    terminals {
      id
      type
      name
      image
      connected
      createdAt
    }
    provider {
      name
      type
    }
    createdAt
    updatedAt
  }
}
Variables: 
{
  "id": "1"
}
Response: 
{
  "data": {
    "flow": {
      "id": "1",
      "title": "Web Application Security Assessment",
      "status": "running",
      "terminals": [
        {
          "id": "term-001",
          "type": "primary",
          "name": "pentagi-kali-main",
          "image": "vxcontrol/pentagi-kali:latest",
          "connected": true,
          "createdAt": "2024-02-20T10:30:05Z"
        }
      ],
      "provider": {
        "name": "default-openai",
        "type": "openai"
      },
      "createdAt": "2024-02-20T10:30:00Z",
      "updatedAt": "2024-02-20T10:45:00Z"
    }
  }
}

​
Mutations

​
Create Flow

Create a new penetration testing flow. 
mutation CreateFlow($provider: String!, $input: String!) {
  createFlow(modelProvider: $provider, input: $input) {
    id
    title
    status
    terminals {
      id
      type
      name
      image
      connected
    }
    provider {
      name
      type
    }
    createdAt
  }
}
Parameters:
​
modelProvider
String
required
Name of the LLM provider configuration (e.g., “default-openai”, “my-anthropic”)
​
input
String
required
Initial task description for the penetration test
Variables: 
{
  "provider": "default-openai",
  "input": "Perform a comprehensive security assessment of the web application at https://example.com. Identify common vulnerabilities including SQL injection, XSS, and authentication issues."
}
Response: 
{
  "data": {
    "createFlow": {
      "id": "2",
      "title": "Security assessment of example.com",
      "status": "created",
      "terminals": [],
      "provider": {
        "name": "default-openai",
        "type": "openai"
      },
      "createdAt": "2024-02-20T11:00:00Z"
    }
  }
}

​
Provide User Input

Send user input to a flow that is waiting for input. 
mutation PutUserInput($flowId: ID!, $input: String!) {
  putUserInput(flowId: $flowId, input: $input)
}
Parameters:
​
flowId
ID
required
ID of the flow waiting for input
​
input
String
required
User’s response or additional information
Variables: 
{
  "flowId": "1",
  "input": "Yes, proceed with the SQL injection test on the login form."
}
Response: 
{
  "data": {
    "putUserInput": "success"
  }
}

​
Stop Flow

Gracefully stop a running flow. 
mutation StopFlow($flowId: ID!) {
  stopFlow(flowId: $flowId)
}
Variables: 
{
  "flowId": "1"
}

​
Finish Flow

Mark a flow as finished. 
mutation FinishFlow($flowId: ID!) {
  finishFlow(flowId: $flowId)
}

​
Delete Flow

Permanently delete a flow and all associated data. 
mutation DeleteFlow($flowId: ID!) {
  deleteFlow(flowId: $flowId)
}
This action cannot be undone. All tasks, logs, and results will be permanently deleted.

​
Subscriptions

​
Flow Created

Subscribe to new flow creation events. 
subscription {
  flowCreated {
    id
    title
    status
    terminals {
      id
      type
      name
    }
    provider {
      name
      type
    }
    createdAt
  }
}

​
Flow Updated

Receive real-time updates when a flow changes. 
subscription {
  flowUpdated {
    id
    title
    status
    terminals {
      id
      connected
    }
    updatedAt
  }
}

​
Flow Deleted

Be notified when a flow is deleted. 
subscription {
  flowDeleted {
    id
    status
    updatedAt
  }
}

​
Status Transitions

A flow in waiting status requires user input via putUserInput mutation.

Build docs developers (and LLMs) love

Get started for freeTalk to us