### Start a session and check for results

Source: https://vorflux.com/docs/api/errors

Initiates a new session with an initial query.

```bash
curl -s -X POST "https://us1.vorflux.com/api/v1/sessions" \
  -H "Authorization: Bearer vfx_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"initialMessage": "What services have high error rates right now?"}'
```

--------------------------------

### Verify vorflux-agent installation

Source: https://vorflux.com/docs/acp

Check the installed version of the agent to ensure it is working correctly.

```bash
vorflux-agent --version
```

--------------------------------

### List Sessions Response

Source: https://vorflux.com/docs/api/sessions

Example response for the GET /api/v1/sessions endpoint.

```json
{
  "sessions": [
    {
      "sessionId": "abc123",
      "title": "Investigate API latency",
      "status": "ACTIVE",
      "sessionType": "GENERAL",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:05:00Z",
      "startedBy": "user@example.com",
      "parentSessionId": ""
    }
  ],
  "totalCount": 42
}
```

--------------------------------

### Get Session Response

Source: https://vorflux.com/docs/api/sessions

Example response for the GET /api/v1/sessions/{sessionId} endpoint.

```json
{
  "sessionId": "abc123",
  "title": "Investigate API latency",
  "status": "ACTIVE",
  "sessionType": "GENERAL",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:05:00Z",
  "startedBy": "user@example.com",
  "parentSessionId": ""
}
```

--------------------------------

### Run Interactive Configuration

Source: https://vorflux.com/docs/acp

Executes the interactive setup wizard to prompt for credentials and generate the configuration file.

```bash
vorflux-agent configure
```

--------------------------------

### Install vorflux-agent on Linux ARM64

Source: https://vorflux.com/docs/acp

Download and set executable permissions for the ARM-based Linux binary.

```bash
curl -fsSL https://us1.vorflux.com/api/v1/acp/download/linux-arm64 -o /usr/local/bin/vorflux-agent
chmod +x /usr/local/bin/vorflux-agent
```

--------------------------------

### Install vorflux-agent on macOS Intel

Source: https://vorflux.com/docs/acp

Download and set executable permissions for the Intel-based Mac binary.

```bash
curl -fsSL https://us1.vorflux.com/api/v1/acp/download/darwin-amd64 -o /usr/local/bin/vorflux-agent
chmod +x /usr/local/bin/vorflux-agent
```

--------------------------------

### GET /api/v1/models

Source: https://vorflux.com/docs/api/sessions

Retrieves the list of models available for session creation.

```APIDOC
## GET /api/v1/models

### Description
Returns the list of models available for session creation. Requires `sessions:read` permission.

### Method
GET

### Endpoint
/api/v1/models

### Response
#### Success Response (200)
- **models** (array) - List of available models
- **defaultModelKey** (string) - The key of the default model

#### Response Example
{
  "models": [
    {
      "modelKey": "claude-sonnet-4-6",
      "displayName": "Claude Sonnet 4.6",
      "description": "Fast and capable",
      "supportsThinking": true
    }
  ],
  "defaultModelKey": "claude-sonnet-4-6"
}
```

--------------------------------

### GET /api/v1/batch

Source: https://vorflux.com/docs/api/batch

Lists existing batch requests with pagination support.

```APIDOC
## GET /api/v1/batch

### Description
Retrieves a list of batch requests. Requires `batch:read` permission.

### Method
GET

### Endpoint
/api/v1/batch

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of requests to return (1–100), default 20
- **offset** (integer) - Optional - Pagination offset, default 0

### Response
#### Success Response (200)
- **requests** (array) - List of batch request objects
- **totalCount** (integer) - Total number of requests

#### Response Example
{
  "requests": [
    {
      "requestId": "batch_abc123",
      "status": "COMPLETED",
      "model": "claude-sonnet-4-6",
      "prompt": "Summarize the latest release notes",
      "resultPreview": "The release adds...",
      "resultUrl": "https://...",
      "createdAt": "2025-01-15T10:00:00Z",
      "completedAt": "2025-01-15T10:01:30Z"
    }
  ],
  "totalCount": 12
}
```

--------------------------------

### Install vorflux-agent on macOS Apple Silicon

Source: https://vorflux.com/docs/acp

Download and set executable permissions for the Apple Silicon binary.

```bash
curl -fsSL https://us1.vorflux.com/api/v1/acp/download/darwin-arm64 -o /usr/local/bin/vorflux-agent
chmod +x /usr/local/bin/vorflux-agent
```

--------------------------------

### Install vorflux-agent on Linux x86_64

Source: https://vorflux.com/docs/acp

Download and set executable permissions for the 64-bit Intel/AMD Linux binary.

```bash
curl -fsSL https://us1.vorflux.com/api/v1/acp/download/linux-amd64 -o /usr/local/bin/vorflux-agent
chmod +x /usr/local/bin/vorflux-agent
```

--------------------------------

### Stream Messages Event Format

Source: https://vorflux.com/docs/api/sessions

Example of the Server-Sent Events format for message notifications.

```text
event: message
data: {"type":"refresh"}
```

--------------------------------

### GET /api/v1/sessions/{sessionId}

Source: https://vorflux.com/docs/api/sessions

Retrieves details for a specific session.

```APIDOC
## GET /api/v1/sessions/{sessionId}

### Description
Retrieves details for a specific session. Requires `sessions:read` permission. Returns 404 if the session does not exist.

### Method
GET

### Endpoint
/api/v1/sessions/{sessionId}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to retrieve

### Response
#### Success Response (200)
- **sessionId** (string) - Session ID
- **title** (string) - Session title
- **status** (string) - Session status
- **sessionType** (string) - Session type
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Last update timestamp
- **startedBy** (string) - User who started the session
- **parentSessionId** (string) - Parent session ID

#### Response Example
{
  "sessionId": "abc123",
  "title": "Investigate API latency",
  "status": "ACTIVE",
  "sessionType": "GENERAL",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:05:00Z",
  "startedBy": "user@example.com",
  "parentSessionId": ""
}
```

--------------------------------

### GET /api/v1/sessions

Source: https://vorflux.com/docs/api/sessions

Retrieves a list of sessions based on optional filters.

```APIDOC
## GET /api/v1/sessions

### Description
Retrieves a list of sessions. Requires `sessions:read` permission.

### Method
GET

### Endpoint
/api/v1/sessions

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of sessions to return (Default: 20)
- **offset** (integer) - Optional - Pagination offset (Default: 0)
- **status** (string) - Optional - Filter: ACTIVE, AWAITING_INPUT, ARCHIVED
- **type** (string) - Optional - Filter: GENERAL, PLAN
- **search** (string) - Optional - Search query string

### Response
#### Success Response (200)
- **sessions** (array) - List of session objects
- **totalCount** (integer) - Total number of sessions

#### Response Example
{
  "sessions": [
    {
      "sessionId": "abc123",
      "title": "Investigate API latency",
      "status": "ACTIVE",
      "sessionType": "GENERAL",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:05:00Z",
      "startedBy": "user@example.com",
      "parentSessionId": ""
    }
  ],
  "totalCount": 42
}
```

--------------------------------

### GET /api/v1/batch/{requestId}

Source: https://vorflux.com/docs/api/batch

Retrieves the details and status of a specific batch request.

```APIDOC
## GET /api/v1/batch/{requestId}

### Description
Poll this endpoint to check status and retrieve the result of a specific batch request. Requires `batch:read` permission.

### Method
GET

### Endpoint
/api/v1/batch/{requestId}

### Parameters
#### Path Parameters
- **requestId** (string) - Required - The ID of the batch request

### Response
#### Success Response (200)
- **requestId** (string) - Request ID
- **status** (string) - Current status
- **model** (string) - Model used
- **prompt** (string) - Original prompt
- **resultPreview** (string) - Truncated result preview
- **resultUrl** (string) - URL to full result
- **errorMessage** (string) - Error message if failed
- **createdAt** (string) - Creation timestamp
- **completedAt** (string) - Completion timestamp

#### Response Example
{
  "requestId": "batch_abc123",
  "status": "COMPLETED",
  "model": "claude-sonnet-4-6",
  "prompt": "Summarize the latest release notes",
  "resultPreview": "The release adds...",
  "resultUrl": "https://...",
  "errorMessage": "",
  "createdAt": "2025-01-15T10:00:00Z",
  "completedAt": "2025-01-15T10:01:30Z"
}
```

--------------------------------

### Define a skill with YAML frontmatter

Source: https://vorflux.com/docs/skills

A skill file requires a name and description in the YAML frontmatter to guide agent matching, followed by the procedural playbook in markdown.

```markdown
---
name: deploy-to-staging
description: Deploy a service to the staging cluster. Covers
  the build, the deploy command, and post-deploy verification.
argument-hint: <service-name> (e.g., "api-server")
---

# Deploy to staging

1. Build the image: `make build SERVICE=$ARGUMENTS`
2. Deploy: `./tools/deploy.sh staging $ARGUMENTS`
3. Verify: check /healthz returns 200 before reporting done.
Never deploy on Fridays after 3pm.
```

--------------------------------

### Get Session Plan Response

Source: https://vorflux.com/docs/api/sessions

Retrieves the current plan for a session. Returns a 404 status if no plan exists.

```json
{
  "planId": "42",
  "sessionId": "abc123",
  "status": "UNDER_REVIEW",
  "summary": "Fix the authentication flow",
  "tasks": [
    {
      "taskId": "1",
      "description": "Update the OAuth callback handler",
      "status": "TODO"
    },
    {
      "taskId": "2",
      "description": "Add refresh token rotation",
      "status": "IN_PROGRESS"
    }
  ]
}
```

--------------------------------

### Cancel Session Response

Source: https://vorflux.com/docs/api/sessions

Example response for the POST /api/v1/sessions/{sessionId}/cancel endpoint.

```json
{
  "success": true,
  "message": "session cancelled"
}
```

--------------------------------

### Get messages from a session

Source: https://vorflux.com/docs/api/errors

Retrieves the message history for a specific session ID.

```bash
curl -s "https://us1.vorflux.com/api/v1/sessions/SESSION_ID/messages" \
  -H "Authorization: Bearer vfx_sk_YOUR_API_KEY"
```

--------------------------------

### GET /api/v1/sessions/{sessionId}/plan

Source: https://vorflux.com/docs/api/sessions

Retrieves the execution plan for a specific session. Requires sessions:read permission.

```APIDOC
## GET /api/v1/sessions/{sessionId}/plan

### Description
Returns the plan associated with the session. Returns 404 if no plan exists.

### Method
GET

### Endpoint
/api/v1/sessions/{sessionId}/plan

### Response
#### Success Response (200)
- **planId** (string) - Unique identifier for the plan.
- **sessionId** (string) - The session ID.
- **status** (string) - Current status of the plan.
- **summary** (string) - Brief summary of the plan.
- **tasks** (array) - List of tasks in the plan.

#### Response Example
{
  "planId": "42",
  "sessionId": "abc123",
  "status": "UNDER_REVIEW",
  "summary": "Fix the authentication flow",
  "tasks": [
    {
      "taskId": "1",
      "description": "Update the OAuth callback handler",
      "status": "TODO"
    },
    {
      "taskId": "2",
      "description": "Add refresh token rotation",
      "status": "IN_PROGRESS"
    }
  ]
}
```

--------------------------------

### Archive Session Request and Response

Source: https://vorflux.com/docs/api/sessions

Example request body and response for the POST /api/v1/sessions/{sessionId}/archive endpoint.

```json
{
  "prUrlsToClose": [
    "https://github.com/acme/backend/pull/42"
  ]
}
```

```json
{
  "success": true,
  "failedPrUrls": []
}
```

--------------------------------

### GET /api/v1/harnesses/{harnessId}/capabilities

Source: https://vorflux.com/docs/api/sessions

Retrieves the resolved capability flags for a specific harness.

```APIDOC
## GET /api/v1/harnesses/{harnessId}/capabilities

### Description
Returns the resolved capability flags for a harness (built-in or custom), so callers can tell which behaviors a session created with that harness will have. Requires `sessions:read` permission.

### Method
GET

### Endpoint
/api/v1/harnesses/{harnessId}/capabilities

### Parameters
#### Path Parameters
- **harnessId** (string) - Required - The ID of the harness.

### Response
#### Success Response (200)
- **harnessId** (string) - The ID of the harness
- **fastMode** (boolean) - Indicates if fast mode is enabled
- **simplifyReviewDisabled** (boolean) - Indicates if simplify/review is disabled
- **testingDisabled** (boolean) - Indicates if testing is disabled

#### Response Example
{
  "harnessId": "harness_abc123",
  "fastMode": false,
  "simplifyReviewDisabled": false,
  "testingDisabled": false
}
```

--------------------------------

### Get Messages Response

Source: https://vorflux.com/docs/api/sessions

Successful response body containing a list of session messages.

```json
{
  "messages": [
    {
      "id": "1",
      "sessionId": "abc123",
      "sentAt": "2025-01-15T10:00:00Z",
      "sentBy": "user@example.com",
      "messageType": "input",
      "content": "Investigate the spike in API latency"
    },
    {
      "id": "2",
      "sessionId": "abc123",
      "sentAt": "2025-01-15T10:00:05Z",
      "agentType": "PLANNER",
      "messageType": "text",
      "content": "I'll investigate the API latency spike..."
    }
  ],
  "hasMore": false
}
```

--------------------------------

### GET /api/v1/session-groups

Source: https://vorflux.com/docs/api/session-groups

Retrieves the current user's session groups, ordered by their position.

```APIDOC
## GET /api/v1/session-groups

### Description
Returns the current user's groups ordered by position. Requires `sessions:read` permission.

### Method
GET

### Endpoint
/api/v1/session-groups

### Response
#### Success Response (200)
- **groups** (array) - List of session group objects.

#### Response Example
{
  "groups": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Work",
      "position": 0,
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-02T12:00:00Z"
    }
  ]
}
```

--------------------------------

### GET /api/v1/sessions/{sessionId}/artifacts

Source: https://vorflux.com/docs/api/sessions

Retrieves a list of artifacts produced by a session. Requires sessions:read permission.

```APIDOC
## GET /api/v1/sessions/{sessionId}/artifacts

### Description
Returns artifacts like pull requests, plans, and files produced by the session.

### Method
GET

### Endpoint
/api/v1/sessions/{sessionId}/artifacts

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **artifacts** (array) - List of artifacts associated with the session.

#### Response Example
{
  "artifacts": [
    {
      "id": 1,
      "artifactId": "pr-123",
      "sessionId": "abc123",
      "artifactType": "PULL_REQUEST",
      "createdAt": "2025-01-15T10:10:00Z",
      "approvalStatus": "PENDING"
    }
  ]
}
```

--------------------------------

### Get Harness Capabilities Response

Source: https://vorflux.com/docs/api/sessions

Returns resolved capability flags for a specific harness, indicating enabled or disabled features.

```json
{
  "harnessId": "harness_abc123",
  "fastMode": false,
  "simplifyReviewDisabled": false,
  "testingDisabled": false
}
```

--------------------------------

### GET /api/v1/sessions/{sessionId}/messages

Source: https://vorflux.com/docs/api/sessions

Retrieves a list of messages for a session. Requires sessions:read permission.

```APIDOC
## GET /api/v1/sessions/{sessionId}/messages

### Description
Retrieves messages associated with a session, supporting pagination and filtering.

### Method
GET

### Endpoint
/api/v1/sessions/{sessionId}/messages

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

#### Query Parameters
- **limit** (integer) - Optional - Number of messages to return (Default: 50).
- **beforeId** (string) - Optional - Return messages before this ID (cursor pagination).
- **planId** (string) - Optional - Filter messages by plan ID.
- **taskId** (string) - Optional - Filter messages by task ID.

### Response
#### Success Response (200)
- **messages** (array) - List of message objects.
- **hasMore** (boolean) - Indicates if more messages are available.

#### Response Example
{
  "messages": [
    {
      "id": "1",
      "sessionId": "abc123",
      "sentAt": "2025-01-15T10:00:00Z",
      "sentBy": "user@example.com",
      "messageType": "input",
      "content": "Investigate the spike in API latency"
    }
  ],
  "hasMore": false
}
```

--------------------------------

### Get Open Decisions Response

Source: https://vorflux.com/docs/api/sessions

Returns a list of pending decisions for a specific session. Returns an empty list if no decisions are currently open.

```json
{
  "decisions": [
    {
      "decisionId": "789",
      "status": "PENDING",
      "question": "Which auth strategy should I use?",
      "rationale": "Both approaches are viable for your stack.",
      "options": [
        { "value": "jwt", "label": "JWT", "description": "Stateless tokens" },
        { "value": "session", "label": "Session", "description": "Server-side sessions" }
      ]
    }
  ]
}
```

--------------------------------

### GET /api/v1/sessions/{parentSessionId}/subsessions

Source: https://vorflux.com/docs/api/sessions

Retrieves a list of sub-sessions associated with a specific parent session.

```APIDOC
## GET /api/v1/sessions/{parentSessionId}/subsessions

### Description
Retrieves a list of sub-sessions associated with a specific parent session. Requires `sessions:read` permission.

### Method
GET

### Endpoint
/api/v1/sessions/{parentSessionId}/subsessions

### Parameters
#### Path Parameters
- **parentSessionId** (string) - Required - The ID of the parent session.

#### Query Parameters
- **limit** (integer) - Optional - Number of sub-sessions to return (Default: 20)
- **offset** (integer) - Optional - Pagination offset (Default: 0)

### Response
#### Success Response (200)
- **sessions** (array) - List of sub-session objects
- **totalCount** (integer) - Total number of sub-sessions

#### Response Example
{
  "sessions": [
    {
      "sessionId": "sub456",
      "title": "Fix failing auth tests",
      "status": "ACTIVE",
      "sessionType": "GENERAL",
      "createdAt": "2025-01-15T10:15:00Z",
      "parentSessionId": "abc123"
    }
  ],
  "totalCount": 3
}
```

--------------------------------

### GET /api/v1/sessions/{sessionId}/decisions/open

Source: https://vorflux.com/docs/api/sessions

Retrieves pending decisions for a specific session. Requires sessions:read permission.

```APIDOC
## GET /api/v1/sessions/{sessionId}/decisions/open

### Description
Returns the pending decisions the agent is currently waiting on for this session. Returns an empty list when none are open.

### Method
GET

### Endpoint
/api/v1/sessions/{sessionId}/decisions/open

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - How many of the most recent messages to scan for open decisions (1–100).

### Response
#### Success Response (200)
- **decisions** (array) - List of pending decisions.

#### Response Example
{
  "decisions": [
    {
      "decisionId": "789",
      "status": "PENDING",
      "question": "Which auth strategy should I use?",
      "rationale": "Both approaches are viable for your stack.",
      "options": [
        { "value": "jwt", "label": "JWT", "description": "Stateless tokens" },
        { "value": "session", "label": "Session", "description": "Server-side sessions" }
      ]
    }
  ]
}
```

--------------------------------

### GET /api/v1/sessions/{sessionId}/messages/stream

Source: https://vorflux.com/docs/api/sessions

Opens a Server-Sent Events stream for real-time message notifications. Requires sessions:read permission.

```APIDOC
## GET /api/v1/sessions/{sessionId}/messages/stream

### Description
Opens a Server-Sent Events (SSE) stream that notifies the client when new messages are available. When a refresh event is received, the client should call the Get Messages endpoint.

### Method
GET

### Endpoint
/api/v1/sessions/{sessionId}/messages/stream

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

#### Query Parameters
- **lastId** (string) - Optional - Only stream events for messages after this ID (Default: 0).

### Response
#### Success Response (200)
- **Event Format** - event: message, data: {"type":"refresh"}
```

--------------------------------

### Get a Batch Request

Source: https://vorflux.com/docs/api/batch

Poll this endpoint to check the status of a specific request and retrieve results. Requires batch:read permission.

```json
{
  "requestId": "batch_abc123",
  "status": "COMPLETED",
  "model": "claude-sonnet-4-6",
  "prompt": "Summarize the latest release notes",
  "resultPreview": "The release adds...",
  "resultUrl": "https://...",
  "errorMessage": "",
  "createdAt": "2025-01-15T10:00:00Z",
  "completedAt": "2025-01-15T10:01:30Z"
}
```

--------------------------------

### Make binary executable

Source: https://vorflux.com/docs/acp

Ensure the agent binary has the necessary permissions to run on your system.

```bash
chmod +x /usr/local/bin/vorflux-agent
```

--------------------------------

### Create and approve a plan

Source: https://vorflux.com/docs/api/errors

Workflow for initiating a planning session and subsequently approving the generated plan.

```bash
# Start a plan session
curl -s -X POST "https://us1.vorflux.com/api/v1/sessions" \
  -H "Authorization: Bearer vfx_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"initialMessage": "Refactor the auth module to use JWT", "sessionType": "PLAN"}'
```

```bash
# Approve the plan
curl -s -X POST "https://us1.vorflux.com/api/v1/sessions/SESSION_ID/plan/approve" \
  -H "Authorization: Bearer vfx_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

--------------------------------

### Create a Session via REST API

Source: https://vorflux.com/docs

Initiate a new development session by sending a POST request to the Vorflux API with an initial task description.

```bash
$ curl -X POST https://us1.vorflux.com/api/v1/sessions \
-H "Authorization: Bearer vfx_sk_..." \
-d '{"initialMessage": "Fix the flaky checkout test"}'
```

```json
{ "sessionId": "abc123", "status": "ACTIVE" }
```

--------------------------------

### Create a Session Request

Source: https://vorflux.com/docs/api/sessions

Sends a POST request to initialize a new session with specific configuration parameters.

```json
{
  "initialMessage": "Investigate the spike in API latency",
  "sessionType": "GENERAL",
  "sourceType": "MANUAL",
  "harnessId": "harness_abc123",
  "modelConfiguration": {
    "modelKey": "claude-sonnet-4-6"
  }
}
```

--------------------------------

### Create an Agent Session

Source: https://vorflux.com/docs/api

Initiates a new agent session by sending an initial message to the sessions endpoint.

```bash
curl https://us1.vorflux.com/api/v1/sessions \
  -H "Authorization: Bearer vfx_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"initialMessage": "What services have high error rates right now?"}'
```

--------------------------------

### List Available Models Response

Source: https://vorflux.com/docs/api/sessions

Returns a list of models available for session creation and the default model key.

```json
{
  "models": [
    {
      "modelKey": "claude-sonnet-4-6",
      "displayName": "Claude Sonnet 4.6",
      "description": "Fast and capable",
      "supportsThinking": true
    }
  ],
  "defaultModelKey": "claude-sonnet-4-6"
}
```

--------------------------------

### Create a Batch Request

Source: https://vorflux.com/docs/api/batch

Submit a prompt and model to initiate a batch request. Requires batch:write permission.

```json
{
  "prompt": "Summarize the latest release notes",
  "model": "claude-sonnet-4-6"
}
```

```json
{
  "requestId": "batch_abc123",
  "status": "PENDING",
  "createdAt": "2025-01-15T10:00:00Z"
}
```

--------------------------------

### Verify binary location

Source: https://vorflux.com/docs/acp

Check if the agent binary is correctly located in your system PATH.

```bash
which vorflux-agent
```

--------------------------------

### POST /sessions

Source: https://vorflux.com/docs/api

Creates a new agent session by sending an initial message to the Vorflux platform.

```APIDOC
## POST /sessions

### Description
Creates a new agent session and initiates interaction with the agent.

### Method
POST

### Endpoint
https://us1.vorflux.com/api/v1/sessions

### Request Body
- **initialMessage** (string) - Required - The initial prompt or message to start the session.
```

--------------------------------

### POST /api/v1/batch

Source: https://vorflux.com/docs/api/batch

Creates a new batch request to run a prompt against a specified model.

```APIDOC
## POST /api/v1/batch

### Description
Creates a new batch request. Requires `batch:write` permission.

### Method
POST

### Endpoint
/api/v1/batch

### Request Body
- **prompt** (string) - Required - The prompt to process
- **model** (string) - Required - The model to use

### Request Example
{
  "prompt": "Summarize the latest release notes",
  "model": "claude-sonnet-4-6"
}

### Response
#### Success Response (201)
- **requestId** (string) - Unique identifier for the request
- **status** (string) - Current status (e.g., PENDING)
- **createdAt** (string) - Timestamp of creation

#### Response Example
{
  "requestId": "batch_abc123",
  "status": "PENDING",
  "createdAt": "2025-01-15T10:00:00Z"
}
```

--------------------------------

### POST /api/v1/sessions/{sessionId}/plan/approve

Source: https://vorflux.com/docs/api/sessions

Approves a plan for a specific session. Requires sessions:write permission.

```APIDOC
## POST /api/v1/sessions/{sessionId}/plan/approve

### Description
Approves a plan for a specific session. If planId is omitted, the plan is looked up by session ID automatically.

### Method
POST

### Endpoint
/api/v1/sessions/{sessionId}/plan/approve

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

#### Request Body
- **planId** (string) - Optional - The ID of the plan to approve.

### Request Example
{
  "planId": "42"
}

### Response
#### Success Response (200)
- **planId** (string) - The ID of the approved plan.
- **sessionId** (string) - The ID of the session.
- **status** (string) - The status of the plan.
- **summary** (string) - A summary of the plan.
- **tasks** (array) - List of tasks associated with the plan.

#### Response Example
{
  "planId": "42",
  "sessionId": "abc123",
  "status": "APPROVED",
  "summary": "Fix the authentication flow",
  "tasks": []
}
```

--------------------------------

### Send a follow-up message

Source: https://vorflux.com/docs/api/errors

Sends an additional message to an existing session.

```bash
curl -s -X POST "https://us1.vorflux.com/api/v1/sessions/SESSION_ID/messages" \
  -H "Authorization: Bearer vfx_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Focus on the payment service first"}'
```

--------------------------------

### POST /api/v1/sessions

Source: https://vorflux.com/docs/api/sessions

Creates a new session. Requires the 'sessions:write' permission.

```APIDOC
## POST /api/v1/sessions

### Description
Creates a new session. Requires `sessions:write` permission.

### Method
POST

### Endpoint
/api/v1/sessions

### Parameters
#### Request Body
- **initialMessage** (string) - Optional - First message sent to the agent.
- **sessionType** (string) - Optional - Either `GENERAL` or `PLAN`.
- **sourceType** (string) - Optional - Origin of the session.
- **harnessId** (string) - Optional - Harness configuration the session runs with.
- **modelConfiguration** (object) - Optional - Optional model override.
- **startedByUserEmail** (string) - Optional - Attribute the session to another user in your account.
- **forkedFromSessionId** (string) - Optional - Fork the new session from an existing session’s state.
- **initialRepositoryUrls** (array) - Optional - Repository URLs to attach to the session at creation.

### Request Example
{
  "initialMessage": "Investigate the spike in API latency",
  "sessionType": "GENERAL",
  "sourceType": "MANUAL",
  "harnessId": "harness_abc123",
  "modelConfiguration": {
    "modelKey": "claude-sonnet-4-6"
  }
}

### Response
#### Success Response (201)
- **sessionId** (string) - The unique identifier for the session.
- **status** (string) - The current status of the session.
- **sessionType** (string) - The type of the session.
- **createdAt** (string) - The timestamp when the session was created.

#### Response Example
{
  "sessionId": "abc123",
  "status": "ACTIVE",
  "sessionType": "GENERAL",
  "createdAt": "2025-01-15T10:00:00Z"
}
```

--------------------------------

### Create a Sub-Session

Source: https://vorflux.com/docs/api/sessions

Creates a child session under a parent session. Requires sessions:write permission and an initial message.

```json
{
  "initialMessage": "Fix the failing unit tests in auth module",
  "sessionType": "GENERAL",
  "modelConfiguration": {
    "modelKey": "claude-sonnet-4-6"
  }
}
```

```json
{
  "sessionId": "sub456",
  "status": "ACTIVE",
  "sessionType": "GENERAL",
  "createdAt": "2025-01-15T10:15:00Z",
  "parentSessionId": "abc123"
}
```

--------------------------------

### Create a Session Group Request and Response

Source: https://vorflux.com/docs/api/session-groups

Creates a new group with a unique name. Returns 409 Conflict if the name already exists.

```json
{
  "name": "Work"
}
```

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Work",
      "position": 0,
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-01T12:00:00Z"
}
```

--------------------------------

### List Batch Requests

Source: https://vorflux.com/docs/api/batch

Retrieve a list of batch requests with pagination support. Requires batch:read permission.

```json
{
  "requests": [
    {
      "requestId": "batch_abc123",
      "status": "COMPLETED",
      "model": "claude-sonnet-4-6",
      "prompt": "Summarize the latest release notes",
      "resultPreview": "The release adds...",
      "resultUrl": "https://...",
      "createdAt": "2025-01-15T10:00:00Z",
      "completedAt": "2025-01-15T10:01:30Z"
    }
  ],
  "totalCount": 12
}
```

--------------------------------

### Configure Zed Editor for Vorflux

Source: https://vorflux.com/docs/acp

Adds the Vorflux agent profile to the Zed settings.json file to enable the agent integration.

```json
{
  "agent": {
    "profiles": {
      "vorflux": {
        "provider": "acp",
        "binary": "/usr/local/bin/vorflux-agent",
        "args": ["--stdio"]
      }
    },
    "default_profile": "vorflux"
  }
}
```

--------------------------------

### POST /api/v1/sessions/{parentSessionId}/subsessions

Source: https://vorflux.com/docs/api/sessions

Creates a child session under an existing parent session. Requires sessions:write permission.

```APIDOC
## POST /api/v1/sessions/{parentSessionId}/subsessions

### Description
Creates a child session under an existing parent session. initialMessage is required.

### Method
POST

### Endpoint
/api/v1/sessions/{parentSessionId}/subsessions

### Parameters
#### Path Parameters
- **parentSessionId** (string) - Required - The ID of the parent session.

#### Request Body
- **initialMessage** (string) - Required - The initial message for the sub-session.
- **sessionType** (string) - Optional - The type of session.
- **modelConfiguration** (object) - Optional - Configuration for the model.

### Request Example
{
  "initialMessage": "Fix the failing unit tests in auth module",
  "sessionType": "GENERAL",
  "modelConfiguration": {
    "modelKey": "claude-sonnet-4-6"
  }
}

### Response
#### Success Response (201)
- **sessionId** (string) - The ID of the new sub-session.
- **status** (string) - The status of the session.
- **sessionType** (string) - The type of session.
- **createdAt** (string) - Creation timestamp.
- **parentSessionId** (string) - The ID of the parent session.

#### Response Example
{
  "sessionId": "sub456",
  "status": "ACTIVE",
  "sessionType": "GENERAL",
  "createdAt": "2025-01-15T10:15:00Z",
  "parentSessionId": "abc123"
}
```

--------------------------------

### Approve a Session Plan

Source: https://vorflux.com/docs/api/sessions

Approves a plan for a specific session. Requires sessions:write permission.

```json
{
  "planId": "42"
}
```

```json
{
  "planId": "42",
  "sessionId": "abc123",
  "status": "APPROVED",
  "summary": "Fix the authentication flow",
  "tasks": [...]
}
```

--------------------------------

### Vorflux Configuration File Format

Source: https://vorflux.com/docs/acp

The JSON structure for the configuration file located at ~/.vorflux/config.json.

```json
{
  "apiKey": "vfx_sk_...",
  "apiUrl": "https://us1.vorflux.com"
}
```

--------------------------------

### Create a Session Response

Source: https://vorflux.com/docs/api/sessions

The successful response returned after creating a session, containing the unique session identifier.

```json
{
  "sessionId": "abc123",
  "status": "ACTIVE",
  "sessionType": "GENERAL",
  "createdAt": "2025-01-15T10:00:00Z"
}
```

--------------------------------

### List Session Artifacts

Source: https://vorflux.com/docs/api/sessions

Retrieves a list of artifacts associated with a session, such as pull requests or plans. Requires sessions:read permission.

```json
{
  "artifacts": [
    {
      "id": 1,
      "artifactId": "pr-123",
      "sessionId": "abc123",
      "artifactType": "PULL_REQUEST",
      "createdAt": "2025-01-15T10:10:00Z",
      "approvalStatus": "PENDING"
    }
  ]
}
```

--------------------------------

### POST /api/v1/session-groups

Source: https://vorflux.com/docs/api/session-groups

Creates a new session group for the user.

```APIDOC
## POST /api/v1/session-groups

### Description
Creates a new session group. Requires `sessions:write` permission. Group names must be unique per user and limited to 60 characters.

### Method
POST

### Endpoint
/api/v1/session-groups

### Parameters
#### Request Body
- **name** (string) - Required - Display name for the group.

### Request Example
{
  "name": "Work"
}

### Response
#### Success Response (201)
- **id** (string) - Unique identifier of the group.
- **name** (string) - Name of the group.
- **position** (integer) - Position index.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.

#### Response Example
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Work",
  "position": 0,
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z"
}
```

--------------------------------

### POST /api/v1/sessions/{sessionId}/decisions

Source: https://vorflux.com/docs/api/sessions

Submits answers for one or more open decisions. Requires sessions:write permission.

```APIDOC
## POST /api/v1/sessions/{sessionId}/decisions

### Description
Answers one or more open decisions so the agent can continue. Each submission requires a non-empty decisionId and response.

### Method
POST

### Endpoint
/api/v1/sessions/{sessionId}/decisions

### Request Body
- **decisions** (array) - Required - List of decision objects containing decisionId and response.

### Request Example
{
  "decisions": [
    {
      "decisionId": "789",
      "response": "jwt"
    }
  ]
}

### Response
#### Success Response (200)
- **submitted** (boolean) - Confirmation of submission.

#### Response Example
{
  "submitted": true
}
```

--------------------------------

### POST /api/v1/sessions/{sessionId}/archive

Source: https://vorflux.com/docs/api/sessions

Archives a session, optionally closing associated pull requests.

```APIDOC
## POST /api/v1/sessions/{sessionId}/archive

### Description
Archives a session. Requires `sessions:write` permission.

### Method
POST

### Endpoint
/api/v1/sessions/{sessionId}/archive

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to archive

#### Request Body
- **prUrlsToClose** (array) - Optional - List of PR URLs to close upon archiving

### Request Example
{
  "prUrlsToClose": [
    "https://github.com/acme/backend/pull/42"
  ]
}

### Response
#### Success Response (200)
- **success** (boolean) - Operation status
- **failedPrUrls** (array) - List of PR URLs that could not be closed

#### Response Example
{
  "success": true,
  "failedPrUrls": []
}
```

--------------------------------

### Authenticate API Requests

Source: https://vorflux.com/docs/api

Standard header format for including the API key in request headers.

```http
Authorization: Bearer vfx_sk_YOUR_API_KEY
```

--------------------------------

### List Session Groups Response

Source: https://vorflux.com/docs/api/session-groups

Returns the current user's groups ordered by position.

```json
{
  "groups": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Work",
      "position": 0,
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-02T12:00:00Z"
    }
  ]
}
```

--------------------------------

### Redirect stderr to log file

Source: https://vorflux.com/docs/acp

Use this to capture diagnostic information from the agent for debugging purposes.

```bash
vorflux-agent 2>/tmp/vorflux-agent.log
```

--------------------------------

### Send a Message Response

Source: https://vorflux.com/docs/api/sessions

Successful response body after creating a new message.

```json
{
  "messageId": "456",
  "sessionId": "abc123"
}
```

--------------------------------

### List Sub-Sessions Response

Source: https://vorflux.com/docs/api/sessions

Returns a paginated list of sub-sessions associated with a parent session ID.

```json
{
  "sessions": [
    {
      "sessionId": "sub456",
      "title": "Fix failing auth tests",
      "status": "ACTIVE",
      "sessionType": "GENERAL",
      "createdAt": "2025-01-15T10:15:00Z",
      "parentSessionId": "abc123"
    }
  ],
  "totalCount": 3
}
```

--------------------------------

### POST /api/v1/sessions/{sessionId}/cancel

Source: https://vorflux.com/docs/api/sessions

Cancels an existing session.

```APIDOC
## POST /api/v1/sessions/{sessionId}/cancel

### Description
Cancels a session. Requires `sessions:write` permission.

### Method
POST

### Endpoint
/api/v1/sessions/{sessionId}/cancel

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to cancel

### Response
#### Success Response (200)
- **success** (boolean) - Operation status
- **message** (string) - Status message

#### Response Example
{
  "success": true,
  "message": "session cancelled"
}
```

--------------------------------

### Reorder Session Groups Request and Response

Source: https://vorflux.com/docs/api/session-groups

Updates the display order of all user groups. Requires the full set of group IDs.

```json
{
  "orderedGroupIds": [
    "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ]
}
```

```json
{
  "success": true
}
```

--------------------------------

### Submit Decisions Request and Response

Source: https://vorflux.com/docs/api/sessions

Submits answers for one or more open decisions. Requires a non-empty decisionId and response.

```json
{
  "decisions": [
    {
      "decisionId": "789",
      "response": "jwt"
    }
  ]
}
```

```json
{
  "submitted": true
}
```

--------------------------------

### POST /api/v1/sessions/{sessionId}/messages

Source: https://vorflux.com/docs/api/sessions

Sends a new message to a specific session. Requires sessions:write permission.

```APIDOC
## POST /api/v1/sessions/{sessionId}/messages

### Description
Sends a new message to the specified session. At least one of content or imageIds is required.

### Method
POST

### Endpoint
/api/v1/sessions/{sessionId}/messages

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

#### Request Body
- **content** (string) - Optional - The text content of the message.
- **imageIds** (array) - Optional - A list of image identifiers.

### Request Example
{
  "content": "Can you also check the database connection pool?",
  "imageIds": []
}

### Response
#### Success Response (201)
- **messageId** (string) - The ID of the created message.
- **sessionId** (string) - The ID of the session.

#### Response Example
{
  "messageId": "456",
  "sessionId": "abc123"
}
```

--------------------------------

### Add a Session to a Group Request and Response

Source: https://vorflux.com/docs/api/session-groups

Adds a session to a specific group. Archived sessions cannot be added.

```json
{
  "sessionId": "abc123"
}
```

```json
{
  "success": true
}
```

--------------------------------

### Test Report Markdown Format

Source: https://vorflux.com/docs/testing

The structure of the test report generated after a test run, detailing status, checks performed, and evidence links.

```markdown
Status: Passed · 6/6 checks

## What was tested
- Sign-in with valid credentials → lands on /dashboard
- Password reset end-to-end (email link → new password → sign-in)
- Expired session redirects to /login with a toast

## Evidence
- login-flow.webm (0:42) — full click-through recording
- 3 screenshots attached in Artifacts
```