# How to Integrate Pi-Web with External Systems: Complete HTTP API Guide

> Integrate Pi-Web with external systems using its complete HTTP API. Control sessions, send commands, and get real-time events easily without an SDK. Learn more.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-07-27

---

**Pi-Web exposes a complete JSON-over-HTTP RPC interface through Next.js API routes, allowing any external service to create sessions, send commands, and receive real-time events without requiring a specialized SDK.**

Pi-Web is a thin Next.js frontend that communicates with the local **Pi-Coding-Agent** SDK via standard HTTP endpoints. Because the architecture exposes all functionality as REST routes and Server-Sent Events (SSE) streams, you can integrate Pi-Web with CI/CD pipelines, custom orchestration tools, or third-party applications using any programming language capable of issuing HTTP requests.

## Core Integration Architecture

Pi-Web functions as an RPC bridge between external clients and the underlying agent SDK. In [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts), the `AgentSessionWrapper` class handles command routing, while [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) provides a thin wrapper (`sendAgentCommand`) that the frontend uses to POST JSON payloads to the API layer. This design means external systems can bypass the UI entirely and communicate directly with the same endpoints, receiving structured responses and real-time event streams.

## Key API Endpoints for Pi-Web Integration

### Session Lifecycle Management

Create and control agent sessions through two primary routes defined in [`app/api/agent/new/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/agent/new/route.ts) and `app/api/agent/[id]/route.ts`:

- **POST `/api/agent/new`** — Initializes a new session, optionally accepting a `cwd` (working directory) and tool allow-list. Returns a unique `sessionId` required for subsequent requests.
- **POST `/api/agent/{sessionId}`** — The core command endpoint. Accepts JSON payloads with `type` fields including `prompt`, `fork`, `steer`, `set_model`, and `navigate_tree`. The route forwards these to `AgentSessionWrapper.send()` in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts), which invokes corresponding SDK methods (`inner.prompt`, `inner.fork`, etc.).

### Real-Time Event Streaming

Long-running operations communicate results via **Server-Sent Events (SSE)** at `GET /api/agent/{sessionId}/events` (implemented in `app/api/agent/[id]/events/route.ts`). External services open an `EventSource` connection to receive push notifications for `agent_end`, `toolResult`, and `extension_ui_request` events without polling.

### Plugin Management API

The `/api/plugins` endpoint (defined in [`app/api/plugins/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/plugins/route.ts)) exposes CRUD operations for Pi-Web extensions. Services can programmatically install, update, disable, or query skills and themes by sending JSON actions (`install`, `remove`, `disable`, `enable`), making it possible to provision specific capabilities during automated deployments.

### Repository File Access

Read-only access to the underlying filesystem is available through `app/api/files/[...path]/route.ts` and `/api/file-index`. External linting tools or documentation generators can fetch source code directly via GET requests to `/api/files/{path}` without maintaining separate repository clones.

## Step-by-Step Pi-Web Integration Workflow

1. **Initialize the session** — POST to `/api/agent/new` with the target working directory. Persist the returned `sessionId`.
2. **Issue commands** — Send JSON-RPC style payloads to `/api/agent/{sessionId}` with the appropriate `type` and parameters.
3. **Consume events** — Establish an SSE connection to `/api/agent/{sessionId}/events` to capture asynchronous results and UI requests.
4. **Handle extensions** — Respond to `extension_ui_request` events by posting `extension_ui_response` messages back to the command endpoint, enabling headless automation of interactive workflows.
5. **Provision capabilities** — Use `/api/plugins` to install required skills before executing dependent prompts.

## Code Examples for Pi-Web Integration

### Node.js: Creating Sessions and Sending Prompts

The following snippet demonstrates session creation, command execution, and SSE consumption using standard `fetch` and `EventSource`:

```javascript
import fetch from 'node-fetch';

// 1️⃣ Create a new session
const newRes = await fetch('http://localhost:30141/api/agent/new', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ cwd: '/home/user/project' })
});
const { sessionId } = await newRes.json();

// 2️⃣ Send a prompt command
await fetch(`http://localhost:30141/api/agent/${sessionId}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    type: 'prompt', 
    message: 'Explain the MVC pattern.' 
  })
});

// 3️⃣ Listen for completion via SSE
const es = new EventSource(`http://localhost:30141/api/agent/${sessionId}/events`);
es.addEventListener('agent_end', e => {
  console.log('Assistant finished:', JSON.parse(e.data));
  es.close();
});

```

*Relevant source:* `sendAgentCommand` in [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts); RPC routing in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts).

### cURL: Programmatic Plugin Installation

Automate environment setup by installing skills directly via the plugins API:

```bash
curl -X POST http://localhost:30141/api/plugins \
     -H "Content-Type: application/json" \
     -d '{
           "action": "install",
           "source": "npm:my-pi-skill",
           "scope": "project",
           "cwd": "/home/user/project"
         }'

```

The response returns the updated plugin manifest, confirming availability for subsequent agent prompts.

*Relevant source:* Plugin handlers in [`app/api/plugins/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/plugins/route.ts).

### Python: Driving Pi-Web with SSE Streaming

This example uses the `requests` and `sseclient` libraries to fork a session and process streaming results:

```python
import requests, sseclient

SID = "c2b34f9e-..."  # Existing session ID

# 1️⃣ Fork the session to create a branch

fork_resp = requests.post(
    f'http://localhost:30141/api/agent/{SID}',
    json={'type': 'fork', 'entryId': 'root'}
).json()
new_sid = fork_resp['newSessionId']

# 2️⃣ Send a steered prompt

requests.post(
    f'http://localhost:30141/api/agent/{new_sid}',
    json={'type': 'steer', 'message': 'List all .ts files in the repo.'}
)

# 3️⃣ Consume the SSE event stream

stream = requests.get(
    f'http://localhost:30141/api/agent/{new_sid}/events',
    stream=True,
    headers={'Accept': 'text/event-stream'}
)
client = sseclient.SSEClient(stream)
for event in client.events():
    if event.event == 'agent_end':
        print('Result:', event.data)
        break

```

*Relevant source:* Command dispatch in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) (see `AgentSessionWrapper.send` switch cases for `"fork"` and `"steer"`).

## Advanced Integration: Extension UI Protocol

Pi-Web supports sophisticated automation through the **Extension UI API**. When extensions request user input (widgets, confirmations, or custom TUI components), they emit `extension_ui_request` events via the SSE stream. External systems can implement headless "extension runners" that intercept these requests in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) (specifically within `AgentSessionWrapper.createExtensionUiContext()`) and POST responses back to `/api/agent/{sessionId}` with `type: "extension_ui_response"`.

Additionally, the global `__piSessions` registry and `notifyRunningChange()` broadcast mechanism in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) enable external monitoring dashboards to track live session activity and resource utilization without polling individual endpoints.

## Summary

- **Pi-Web integration** relies entirely on standard HTTP routes and SSE streams—no proprietary SDK required.
- **Session management** flows through `/api/agent/new` and `/api/agent/{id}`, handled internally by `AgentSessionWrapper`.
- **Real-time communication** uses Server-Sent Events at `/api/agent/{id}/events` for asynchronous results.
- **Plugin automation** is available via `/api/plugins`, supporting CI/CD provisioning of skills and themes.
- **File system access** exposes read-only repository contents through `/api/files/[...path]` for external analysis tools.

## Frequently Asked Questions

### Can Pi-Web be integrated without using JavaScript?

Yes. Because Pi-Web exposes standard HTTP endpoints and SSE streams, any language capable of HTTP requests—including Python, Go, Ruby, or Bash—can integrate with the system. The API accepts and returns JSON, making it language-agnostic.

### What real-time capabilities does Pi-Web offer for integrations?

Pi-Web provides **Server-Sent Events (SSE)** through `/api/agent/{sessionId}/events`, allowing external services to receive instantaneous notifications for `agent_end`, `toolResult`, and `extension_ui_request` events. This eliminates the need for polling and enables reactive automation workflows.

### How do I automate plugin management in Pi-Web?

Use the **POST `/api/plugins`** endpoint with actions like `install`, `remove`, `enable`, or `disable`. You can specify package sources (e.g., `npm:package-name`) and scope (project or global), allowing automated provisioning of specific capabilities before executing agent prompts.

### Is it possible to monitor active Pi-Web sessions externally?

Yes. The global `__piSessions` registry and `notifyRunningChange()` function in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) broadcast session state changes. External monitoring tools can subscribe to these broadcasts or poll session endpoints to build dashboards showing which sessions are active, idle, or processing commands.