# Create a new channel (agent)
Source: https://docs.placet.io/api-reference/agents/create-a-new-channel-agent

/openapi.json post /api/v1/agents



# List channels (agents) accessible by this API key
Source: https://docs.placet.io/api-reference/agents/list-channels-agents-accessible-by-this-api-key

/openapi.json get /api/v1/agents



# Remove webhook URL from a channel
Source: https://docs.placet.io/api-reference/agents/remove-webhook-url-from-a-channel

/openapi.json post /api/v1/agents/deleteWebhook
Removes the currently configured webhook so no more events are delivered via HTTP callback.



# Set webhook URL for a channel
Source: https://docs.placet.io/api-reference/agents/set-webhook-url-for-a-channel

/openapi.json post /api/v1/agents/setWebhook
Register a webhook URL that will receive events (message:created, review:responded) for the given channel. Replaces any previously configured webhook.



# Download file directly by attachment ID
Source: https://docs.placet.io/api-reference/files/download-file-directly-by-attachment-id

/openapi.json get /api/v1/files/{id}/download



# List all files in a channel
Source: https://docs.placet.io/api-reference/files/list-all-files-in-a-channel

/openapi.json get /api/v1/files



# Store a file without creating a message
Source: https://docs.placet.io/api-reference/files/store-a-file-without-creating-a-message

/openapi.json post /api/v1/files/store



# Store text content as a file without creating a message
Source: https://docs.placet.io/api-reference/files/store-text-content-as-a-file-without-creating-a-message

/openapi.json post /api/v1/files/store-text



# Upload a file
Source: https://docs.placet.io/api-reference/files/upload-a-file

/openapi.json post /api/v1/files/upload



# Acknowledge receipt of a message
Source: https://docs.placet.io/api-reference/messages/acknowledge-receipt-of-a-message

/openapi.json post /api/v1/messages/{id}/ack



# Delete (retract) a message
Source: https://docs.placet.io/api-reference/messages/delete-retract-a-message

/openapi.json delete /api/v1/messages/{id}



# Get a single message + review status
Source: https://docs.placet.io/api-reference/messages/get-a-single-message-+-review-status

/openapi.json get /api/v1/messages/{id}



# Get all messages in an iteration chain
Source: https://docs.placet.io/api-reference/messages/get-all-messages-in-an-iteration-chain

/openapi.json get /api/v1/messages/iterations/{id}



# List messages for a channel (chat-as-storage)
Source: https://docs.placet.io/api-reference/messages/list-messages-for-a-channel-chat-as-storage

/openapi.json get /api/v1/messages



# Send a message to a channel (channelId in body)
Source: https://docs.placet.io/api-reference/messages/send-a-message-to-a-channel-channelid-in-body

/openapi.json post /api/v1/messages



# Get plugin details
Source: https://docs.placet.io/api-reference/plugins/get-plugin-details

/openapi.json get /api/v1/plugins/{name}



# List installed plugins
Source: https://docs.placet.io/api-reference/plugins/list-installed-plugins

/openapi.json get /api/v1/plugins



# Get a specific review by message ID
Source: https://docs.placet.io/api-reference/reviews/get-a-specific-review-by-message-id

/openapi.json get /api/v1/reviews/{id}



# List all pending reviews for a channel
Source: https://docs.placet.io/api-reference/reviews/list-all-pending-reviews-for-a-channel

/openapi.json get /api/v1/reviews/pending



# Long-poll for review response (max 30s)
Source: https://docs.placet.io/api-reference/reviews/long-poll-for-review-response-max-30s

/openapi.json get /api/v1/reviews/{id}/wait



# Report agent status (heartbeat)
Source: https://docs.placet.io/api-reference/status/report-agent-status-heartbeat

/openapi.json post /api/v1/status/ping



# WebSocket
Source: https://docs.placet.io/api-reference/websocket

Real-time events via Socket.IO for agent integrations.

Placet exposes a [Socket.IO](https://socket.io/) WebSocket gateway on the `/ws` namespace. Agents can connect to receive real-time events such as new messages, review responses, and status changes.

## Authentication

Agents authenticate by passing their API key in the Socket.IO `auth` object:

```typescript theme={null}
import { io } from 'socket.io-client';

const socket = io('https://your-placet-instance.com/ws', {
  auth: { apiKey: 'hp_your-api-key' },
  transports: ['websocket'],
});
```

```python theme={null}
import socketio

sio = socketio.Client()
sio.connect(
    "https://your-placet-instance.com",
    namespaces=["/ws"],
    auth={"apiKey": "hp_your-api-key"},
    transports=["websocket"],
)
```

The server validates the API key on connection. If the key is invalid or missing, the connection is rejected before it is established — clients receive a Socket.IO `connect_error` (not a post-`connect` `disconnect`).

## Channel Subscription

After connecting, subscribe to a channel to receive its events:

```typescript theme={null}
socket.on('connect', () => {
  socket.emit('subscribe:channel', 'your-agent-id');
});
```

You can subscribe to multiple channels on the same connection. To unsubscribe:

```typescript theme={null}
socket.emit('unsubscribe:channel', 'your-agent-id');
```

<Note>
  The server verifies that the API key owner also owns the channel. Subscribing to a channel you
  don't own silently fails.
</Note>

## Events

All events are received on the `/ws` namespace.

### `message:created`

Emitted when a new message is posted in a subscribed channel (by a user or another agent).

```json theme={null}
{
  "id": "clxyz111",
  "channelId": "clxyz456",
  "senderType": "user",
  "senderId": "user_abc",
  "text": "Looks good, ship it!",
  "status": null,
  "review": null,
  "metadata": null,
  "createdAt": "2025-06-15T14:30:00.000Z",
  "attachments": []
}
```

### `review:responded`

Emitted when a human completes a review (approval, selection, form, etc.). The full message record is emitted, including attachments.

```json theme={null}
{
  "id": "clxyz111",
  "channelId": "clxyz456",
  "senderType": "agent",
  "senderId": "clxyz456",
  "text": "Deploy to production?",
  "status": null,
  "review": {
    "type": "approval",
    "status": "completed",
    "payload": {
      "options": [
        { "id": "approve", "label": "Approve", "style": "primary" },
        { "id": "reject", "label": "Reject", "style": "danger" }
      ]
    },
    "response": {
      "selectedOption": "approve",
      "comment": "Go ahead"
    },
    "completed_at": "2025-06-15T14:32:00.000Z"
  },
  "metadata": null,
  "createdAt": "2025-06-15T14:30:00.000Z",
  "attachments": []
}
```

Use the `review.response` field to determine what the human chose:

* **Approval**: `response.selectedOption` (`"approve"` or `"reject"`) + optional `response.comment`
* **Selection**: `response.selectedIds` (array of selected item IDs)
* **Form**: `response.{fieldName}` (key-value pairs for each form field)

### `review:expired`

Emitted when a review expires without a response (default: 24 hours).

```json theme={null}
{
  "messageId": "clxyz111"
}
```

### `message:delivery`

Emitted when a message's delivery status changes (webhook delivered, agent acknowledged, etc.).

```json theme={null}
{
  "messageId": "clxyz111",
  "deliveryStatus": "webhook_delivered"
}
```

| Status              | Meaning                               |
| ------------------- | ------------------------------------- |
| `sent`              | Message stored, webhook not yet sent  |
| `webhook_delivered` | Webhook received 2xx response         |
| `webhook_failed`    | Webhook delivery failed               |
| `agent_received`    | Agent explicitly acknowledged receipt |

### `agent:status`

Emitted when an agent's ping status changes.

```json theme={null}
{
  "agentId": "clxyz456",
  "status": "active",
  "statusMessage": null,
  "statusSince": "2025-06-15T14:00:00.000Z"
}
```

### `ping` / `pong`

Send a `ping` event to check the connection is alive. The server responds with `pong`.

```typescript theme={null}
socket.emit('ping');
socket.on('pong', () => console.log('Connection alive'));
```

## Full Example

A complete agent that listens for user messages and review responses:

```typescript theme={null}
import { io } from 'socket.io-client';

const BASE_URL = 'https://your-placet-instance.com';
const API_KEY = 'hp_your-api-key';
const CHANNEL = 'your-agent-id';

const socket = io(`${BASE_URL}/ws`, {
  auth: { apiKey: API_KEY },
  transports: ['websocket'],
});

socket.on('connect', () => {
  console.log('Connected');
  socket.emit('subscribe:channel', CHANNEL);
});

socket.on('message:created', (data) => {
  if (data.senderType === 'user') {
    console.log(`User said: ${data.text}`);
    // Process the message and respond via REST API
  }
});

socket.on('review:responded', (data) => {
  const response = data.review?.response;
  if (response?.selectedOption) {
    console.log(`Review decision: ${response.selectedOption}`);
  }
});

socket.on('review:expired', (data) => {
  console.log(`Review ${data.messageId} expired`);
});

socket.on('disconnect', () => {
  console.log('Disconnected');
});
```

<Tip>
  WebSocket is best for **interactive agents** that need to react to user input immediately. For
  background automations, consider [Webhooks](/connections/connection-types#webhooks) or
  [Long-Polling](/connections/connection-types#long-polling) instead.
</Tip>


# Agents
Source: https://docs.placet.io/concepts/agents

How agents connect to and interact with Placet.

## What is an Agent?

An **agent** in Placet represents an external AI system, automation workflow, or no-code tool that sends messages to humans for review. Each agent gets its own chat channel in the inbox.

## Creating an Agent

Agents are created from the **inbox sidebar** (click **+ New Agent**), or via the API.

Each agent has:

* **Name**: displayed in the inbox sidebar
* **Description**: optional context about the agent's purpose
* **Avatar**: optional visual identifier

## Authentication

Agents authenticate via **API Keys**, created in **Settings → API Keys**. API keys are prefixed with `hp_` for easy identification.

```bash theme={null}
curl -X POST http://localhost:3001/api/v1/messages \
  -H "x-api-key: hp_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from my agent!"}'
```

## Message Types

Agents can send different types of messages:

### Plain text

```json theme={null}
{
  "text": "Deployment completed successfully.",
  "status": "success"
}
```

### With review (approval buttons)

```json theme={null}
{
  "text": "Deploy v2.1 to production?",
  "review": {
    "type": "approval",
    "payload": {
      "options": [
        { "id": "approve", "label": "Approve", "style": "primary" },
        { "id": "reject", "label": "Reject", "style": "danger" }
      ]
    }
  }
}
```

### With plugin rendering

```json theme={null}
{
  "text": "Form submission required",
  "metadata": {
    "plugin": "form-submit",
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

## Review Types

Agents can request human input by adding a `review` object to any message. Each review type renders a different interactive UI.

### Approval

Presents styled buttons for a yes/no or go/no-go decision. Optionally allows a comment.

```json theme={null}
{
  "type": "approval",
  "payload": {
    "options": [
      { "id": "approve", "label": "Approve", "style": "primary" },
      { "id": "reject", "label": "Reject", "style": "danger" }
    ],
    "allowComment": true
  }
}
```

Button styles: `primary`, `danger`, `secondary`, `ghost`. Response: `{ "selectedOption": "approve", "comment": "Looks good" }`.

### Selection

Shows radio buttons (single) or checkboxes (multi) for the user to choose from.

```json theme={null}
{
  "type": "selection",
  "payload": {
    "mode": "single",
    "items": [
      { "id": "option_a", "label": "Option A", "description": "First choice" },
      { "id": "option_b", "label": "Option B", "description": "Second choice" }
    ]
  }
}
```

Response: `{ "selectedIds": ["option_a"] }`.

### Form

Renders a dynamic form with multiple field types. Supports 12 field types: `text`, `number`, `email`, `url`, `textarea`, `select`, `checkbox`, `date`, `time`, `datetime`, `range`, `password`.

```json theme={null}
{
  "type": "form",
  "payload": {
    "fields": [
      {
        "name": "environment",
        "type": "select",
        "label": "Environment",
        "required": true,
        "options": [
          { "value": "staging", "label": "Staging" },
          { "value": "prod", "label": "Production" }
        ]
      },
      { "name": "version", "type": "text", "label": "Version", "placeholder": "e.g. 2.1.0" },
      { "name": "notify", "type": "checkbox", "label": "Send notification" }
    ],
    "submitLabel": "Deploy"
  }
}
```

Response: `{ "environment": "prod", "version": "2.1.0", "notify": true }`.

### Text Input

Shows a textarea for free-text responses. Supports markdown preview and character limits.

```json theme={null}
{
  "type": "text-input",
  "payload": {
    "placeholder": "Describe the issue...",
    "markdown": true,
    "minLength": 10,
    "maxLength": 2000
  }
}
```

Response: `{ "text": "The deployment failed because..." }`.

### Freeform

Accepts any JSON response. Used primarily with plugins that define their own response UI.

```json theme={null}
{
  "type": "freeform",
  "payload": {}
}
```

Response: any JSON object.

### Review Options

All review types support optional fields:

| Field              | Description                                        |
| ------------------ | -------------------------------------------------- |
| `expiresInSeconds` | Auto-expire after N seconds (default: 86400 / 24h) |
| `expiresAt`        | Expire at a specific ISO timestamp (max: 36h)      |
| `callback`         | Legacy inline webhook `{ url, method?, headers? }` |

## Message Status

Each message can carry a `status` that controls its visual appearance in the chat:

| Status    | Use case                            |
| --------- | ----------------------------------- |
| `info`    | Neutral status update (default)     |
| `success` | Task completed successfully         |
| `warning` | Needs attention or pending decision |
| `error`   | Something went wrong                |

## File Attachments

Agents can upload files and attach them to messages. Upload a file first, then reference it by ID:

```json theme={null}
{
  "text": "Please review the attached report.",
  "attachmentIds": ["file-id-from-upload"],
  "review": { "type": "approval", "payload": { "options": [...] } }
}
```

Files are previewed inline in the chat. Supported formats include images, PDFs, video, audio, Office documents, spreadsheets, code files, and more. Users can annotate images directly in the preview.

### Inline HTML Attachments

When a message contains a single `text/html` attachment and **Inline HTML rendering** is enabled in chat settings, Placet renders that file inside a sandboxed iframe.

This is useful for lightweight interactive demos, status panels, or self-contained UI mockups, but the iframe has important limits:

* Use `addEventListener()` instead of inline event attributes like `onclick`
* Do not rely on `<form>` submission
* Do not rely on `alert()`, `confirm()`, or `prompt()`
* Do not rely on `window.open()` or popup flows
* Regular CSS, DOM manipulation, and `<script>` tags work

In practice, inline HTML attachments should be written as self-contained HTML/CSS/JS pages that do all interaction inside the document itself.

## Agent Status

Agents can report their operational status via the heartbeat endpoint:

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/status/ping" \
  -H "x-api-key: $PLACET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "your-agent-id", "status": "active", "message": "Processing 42 tasks"}'
```

| Status    | Description                |
| --------- | -------------------------- |
| `active`  | Agent is running normally  |
| `busy`    | Agent is processing a task |
| `error`   | Agent encountered an error |
| `offline` | Agent is not connected     |

The status is displayed in the chat sidebar and on a dedicated **Status** page that shows all agents with uptime, message statistics, and a status history timeline.


# Channels
Source: https://docs.placet.io/concepts/channels

Communication channels between agents and the Placet platform.

## Overview

Every agent in Placet gets a dedicated **channel**, a chat-like conversation thread. Channels provide an organized inbox where humans can review and respond to agent messages.

## Real-Time Updates

Channels deliver messages in **real-time**. When an agent sends a message via the API, it instantly appears for all users viewing that channel. The sidebar updates with the latest message preview, timestamp, and unread count.

## File Storage

Each channel has its own file storage. Agents upload files via the API and attach them to messages. All files are stored in S3-compatible storage (MinIO) and can be:

* **Previewed inline**: images, PDFs, video, audio, Office documents, spreadsheets, code files
* **Annotated**: draw on images with pen, arrow, rectangle, and text tools
* **Shared**: generate public download links (1h expiry)
* **Browsed**: searchable file gallery with type filters across all channels

## Agent Status

Agents can report their operational status, which is displayed in the channel sidebar and on the dedicated Status page:

| Status    | Description                |
| --------- | -------------------------- |
| `active`  | Agent is running normally  |
| `busy`    | Agent is processing a task |
| `error`   | Agent encountered an error |
| `offline` | Agent is not connected     |

The Status page shows all agents with live status indicators, uptime, message statistics (total, inbound/outbound, success/error), and a status history timeline.

## Reviews

When an agent sends a message with a `review`, the user sees an interactive UI to respond. Placet supports 5 review types: approval buttons, single/multi selection, dynamic forms, free-text input, and freeform JSON. See [Agents](/concepts/agents#review-types) for details on each type.

## Webhooks

Agents can register **webhook URLs** to receive asynchronous notifications when humans respond to their messages. This enables fire-and-forget patterns where the agent doesn't need to maintain a persistent connection. Webhooks can be configured per-message or per-agent in the chat settings.

## Push Notifications

Users receive browser push notifications when agents send messages, even when the tab is in the background. Notifications link directly to the relevant channel. Push notifications can be enabled in **Settings > Appearance**.

## Message Flow

```mermaid theme={null}
sequenceDiagram
    participant Agent as 🤖 Agent
    participant API as Placet API
    participant UI as 👤 Chat UI

    Agent->>API: 1. POST /api/v1/messages
    API->>UI: 2. Appears in chat (+ push notification)
    UI->>API: 3. Human responds
    alt Webhook configured
        API-->>Agent: 4a. POST webhookUrl
    else Polling
        Agent->>API: 4b. GET /api/v1/reviews/{id}/wait
        API-->>Agent: Review response
    end
```

## Chat Settings

Each channel can be configured individually:

* **Rename agent** and customize avatar
* **Webhook URL** with custom headers and basic auth
* **Notification preferences** per user


# Overview
Source: https://docs.placet.io/concepts/connection-types

Choose how your agent connects to Placet — MCP, REST API, WebSocket, or Webhooks.

Placet supports four connection types for agent integration. You can use them independently or combine them.

```mermaid theme={null}
flowchart LR
    Human["👤 Human"] <--> Backend["Placet Backend"]
    Backend <--> MCP["MCP"]
    Backend <--> REST["REST API"]
    Backend <--> WS["WebSocket"]
    Backend --> WH["Webhook"]
    MCP --> IDE["IDE / AI Agent"]
    REST --> Script["Script / App"]
    WS --> Server["Agent Server"]
    WH --> Server

    style MCP fill:#7c9cb5,color:#fff
    style REST fill:#8faec8,color:#fff
    style WS fill:#5a7d96,color:#fff
    style WH fill:#6b8fa8,color:#fff
```

## Comparison

| Feature                    | [MCP](/connections/mcp) | [REST API](/connections/rest-api) | [WebSocket](/connections/websocket) | [Webhooks](/connections/webhooks) |
| -------------------------- | ----------------------- | --------------------------------- | ----------------------------------- | --------------------------------- |
| **Best for**               | AI coding agents        | Scripts & apps                    | Persistent agents                   | Background jobs                   |
| **Latency**                | Real-time (poll)        | Up to 30s (poll)                  | Real-time (push)                    | Near real-time (push)             |
| **Persistent connection**  | Per-session             | No                                | Yes                                 | No                                |
| **Agent needs public URL** | No                      | No                                | No                                  | Yes                               |
| **Protocol**               | MCP over HTTP/stdio     | HTTP REST                         | Socket.IO                           | HTTP callback                     |

***

## Choosing a Connection

<AccordionGroup>
  <Accordion title="I'm using an AI coding agent (Claude Code, Copilot, Cursor)">
    Use **[MCP](/connections/mcp)**. The Placet MCP server exposes all capabilities as tools that AI assistants can call directly. Configure your IDE with a one-line config.
  </Accordion>

  <Accordion title="I'm writing a script or simple integration">
    Use the **[REST API](/connections/rest-api)**. Send messages via HTTP, poll for responses with
    long-polling. Works from any language with zero dependencies.
  </Accordion>

  <Accordion title="I'm building a persistent agent that reacts in real-time">
    Use **[WebSocket](/connections/websocket)**. Connect via Socket.IO, subscribe to channels, and
    receive instant push events when humans respond.
  </Accordion>

  <Accordion title="I'm running background automations (CI/CD, cron)">
    Use **[Webhooks](/connections/webhooks)**. Set a webhook URL and let Placet push responses to your
    server — your automation doesn't block while waiting.
  </Accordion>

  <Accordion title="I just want to send notifications without waiting">
    Use **fire-and-forget** via the [REST API](/connections/rest-api): `POST /api/v1/messages` without a `review` field. No response mechanism needed.
  </Accordion>
</AccordionGroup>

***

## Push Notifications

All connection types benefit from **browser push notifications**. When an agent sends a message, users receive a notification even when the browser tab is in the background. Push notifications are powered by the Web Push API (VAPID) and can be enabled per user in **Settings > Appearance**.


# How It Works
Source: https://docs.placet.io/concepts/how-it-works

Understand how Placet connects agents and humans.

## Overview

Placet consists of three main components:

* **Web App**: the inbox where humans review and respond to messages
* **API**: the REST endpoint agents and automations use to send messages and receive responses
* **Plugin System**: extensible message rendering via sandboxed plugins

```mermaid theme={null}
flowchart LR
    Agent["🤖 Your Agent"] -->|REST API| API["Placet API"]
    API <-->|Real-time| Web["📱 Web App"]
    Web --> Human["👤 Human"]
    Human --> Web
    API -->|Webhook / Poll| Agent
    Plugins["🧩 Plugins"] --> Web

    style API fill:#7c9cb5,color:#fff
    style Web fill:#5a7d96,color:#fff
    style Plugins fill:#8faec8,color:#fff
```

## Agent Communication

Agents interact with Placet through the **Agent API** (`/api/v1/*`), authenticated with API keys:

```mermaid theme={null}
sequenceDiagram
    participant Agent as 🤖 Agent
    participant API as Placet API
    participant UI as 👤 Web App

    Agent->>API: POST /api/v1/messages
    API->>UI: Real-time update
    UI->>API: Human responds
    API-->>Agent: Webhook / Poll response
```

### Supported patterns

| Pattern           | Use Case                                                         |
| ----------------- | ---------------------------------------------------------------- |
| **Fire & forget** | Agent sends a message, no response needed                        |
| **Webhook**       | Agent registers a webhook URL, receives responses asynchronously |
| **Polling**       | Agent polls for review responses via the API                     |
| **WebSocket**     | Real-time bidirectional communication                            |

For a detailed comparison, see [Connection Types](/concepts/connection-types).

## Review System

Agents can request human input by attaching a `review` to any message. Placet supports 5 built-in review types:

| Type           | Agent sends                               | User sees                            |
| -------------- | ----------------------------------------- | ------------------------------------ |
| **Approval**   | `options: [{id, label, style}]`           | Styled buttons with optional comment |
| **Selection**  | `mode: "single"\|"multi", items: [...]`   | Radio buttons or checkboxes          |
| **Form**       | `fields: [{name, type, label, required}]` | Dynamic form (12 field types)        |
| **Text Input** | `placeholder?, markdown?`                 | Textarea with optional markdown      |
| **Freeform**   | `{}`                                      | JSON editor (for plugin UIs)         |

Reviews support expiry (default 24h, max 36h), webhook callbacks, and long-polling. See [Agents](/concepts/agents) for payload examples.

## File Storage

Agents can upload and attach files to messages via the API. The web app renders inline previews for many formats:

| Category          | Formats                                |
| ----------------- | -------------------------------------- |
| **Images**        | JPG, PNG, GIF, WebP, SVG               |
| **Video**         | MP4, WebM, MOV                         |
| **Audio**         | MP3, WAV, OGG, M4A                     |
| **Documents**     | PDF, DOCX, ODT                         |
| **Spreadsheets**  | XLSX, XLS, ODS, CSV                    |
| **Presentations** | PPTX                                   |
| **Code**          | 40+ languages with syntax highlighting |
| **Markdown**      | Rendered with GFM support              |

Additional file features:

* **Canvas annotations**: draw on images with pen, arrow, rectangle, and text tools
* **Share links**: JWT-based public download links (1h expiry)
* **Bulk operations**: download as ZIP or delete multiple files
* **File browser**: searchable gallery with type filters across all channels

## Agent Status

Agents report their status via a heartbeat endpoint (`POST /api/v1/status/ping`). The frontend provides a dedicated **Status** page showing all agents with:

* Live status indicator (active, busy, error, offline)
* Uptime since last status change
* Message statistics (total, inbound/outbound, success/error)
* Status history timeline

## Push Notifications

Placet supports browser push notifications via VAPID/Web Push. When an agent sends a message, users receive a notification even when the browser tab is in the background. Clicking the notification navigates directly to the agent's chat.


# Iterations & Versioning
Source: https://docs.placet.io/concepts/iterations

Build revision workflows where agents iterate on content based on human feedback.

## Overview

Placet's **iteration system** turns one-shot reviews into multi-round revision workflows. An agent sends content, a human provides feedback, the agent revises, and the human reviews again — as many rounds as needed.

All iterations of the same task are linked into an **iteration chain**, enabling diff views, feedback history, and progress tracking across revisions.

```mermaid theme={null}
sequenceDiagram
    participant Agent as 🤖 Agent
    participant API as Placet API
    participant Human as 👤 Human

    Agent->>API: Send draft (iteration #1)
    API->>Human: Review request
    Human->>API: Respond with feedback
    API-->>Agent: status: completed + feedback
    Note over Agent: Agent decides to revise
    Agent->>API: Send revision (iterationOf: msg1)
    Note over API: Linked as iteration #2
    API->>Human: Re-review with diff
    Human->>API: Approve ✓
    API-->>Agent: status: completed
```

## When to Use Iterations

| Scenario               | Without iterations                          | With iterations                                |
| ---------------------- | ------------------------------------------- | ---------------------------------------------- |
| **Content generation** | Agent sends once, human approves or rejects | Human requests specific changes, agent revises |
| **Report review**      | Binary approve/reject, agent starts over    | Feedback loop until quality met                |
| **Code review**        | Human re-explains issues each time          | Previous feedback visible in context           |
| **Image generation**   | No connection between attempts              | Side-by-side comparison with previous version  |

## How It Works

### Data Model

Iterations are tracked with two fields on the `Message` model — no new tables:

| Field              | Type      | Description                                                                    |
| ------------------ | --------- | ------------------------------------------------------------------------------ |
| `iterationGroupId` | `string?` | Points to the root message ID of the chain. `null` for standalone messages.    |
| `iteration`        | `int?`    | Counter within the group. `1` = root, `2`+ = revisions. `null` for standalone. |

A unique constraint on `(iterationGroupId, iteration)` prevents race conditions.

```mermaid theme={null}
flowchart LR
    M1["Message #1<br/>iteration: 1<br/>iterationGroupId: msg1<br/>status: completed"]
    M2["Message #2<br/>iteration: 2<br/>iterationGroupId: msg1<br/>status: completed"]
    M3["Message #3<br/>iteration: 3<br/>iterationGroupId: msg1<br/>status: completed ✓"]

    M1 -->|feedback| M2 -->|feedback| M3

    style M1 fill:#6b7280,color:#fff
    style M2 fill:#6b7280,color:#fff
    style M3 fill:#22c55e,color:#fff
```

### Review Statuses

| Status      | Meaning                 | Wait endpoint behavior |
| ----------- | ----------------------- | ---------------------- |
| `pending`   | Awaiting human response | Continues polling      |
| `completed` | Human responded         | Returns immediately    |
| `expired`   | Timed out (default 24h) | Returns immediately    |

<Note>
  Every review response is `completed`. The agent interprets the response content (e.g. selected
  option, feedback text) and decides whether to send a new iteration. Placet is a transport layer —
  it does not encode business logic about what constitutes "approval" vs "rejection".
</Note>

## Sending Iterations

### Step 1: Send the initial message

Send a message with a review as usual. No special parameters needed — the first message becomes the chain root automatically when an iteration references it.

```json theme={null}
POST /api/v1/messages
{
  "channelId": "agent-123",
  "text": "Here is the Q1 report draft.\n\n- Revenue: $1.2M\n- Growth: 15%",
  "status": "warning",
  "metadata": { "runId": "run-001", "model": "gpt-4" },
  "review": {
    "type": "approval",
    "payload": {
      "options": [
        { "id": "approve", "label": "Approve", "style": "primary" },
        { "id": "reject", "label": "Reject", "style": "danger" }
      ]
    }
  }
}
```

### Step 2: Wait for the response

Use the wait endpoint to poll for the human's decision:

```json theme={null}
GET /api/v1/reviews/{messageId}/wait?channel=agent-123&timeout=120000
```

The response includes the review status and human feedback:

```json theme={null}
{
  "status": "completed",
  "message": {
    "id": "msg-1",
    "review": {
      "status": "completed",
      "feedback": "Please add Q2 projections and fix the growth calculation.",
      "response": { "selectedOption": "reject" }
    }
  }
}
```

### Step 3: Send a revised iteration

Reference the previous message via `iterationOf` to create an iteration chain:

```json theme={null}
POST /api/v1/messages
{
  "channelId": "agent-123",
  "text": "Revised Q1 report with Q2 projections.\n\n- Revenue: $1.2M\n- Growth: 18% (corrected)\n- Q2 Projection: $1.4M",
  "status": "warning",
  "metadata": { "runId": "run-002", "model": "gpt-4" },
  "iterationOf": "msg-1",
  "review": {
    "type": "approval",
    "payload": {
      "options": [
        { "id": "approve", "label": "Approve", "style": "primary" },
        { "id": "reject", "label": "Reject", "style": "danger" }
      ]
    }
  }
}
```

The response includes the iteration metadata:

```json theme={null}
{
  "id": "msg-2",
  "iterationGroupId": "msg-1",
  "iteration": 2,
  "text": "Revised Q1 report with Q2 projections...",
  ...
}
```

### Step 4: Repeat until approved

Continue the loop — check the wait endpoint, and based on the response content, decide whether to send another iteration:

```mermaid theme={null}
flowchart TD
    Send["Send message<br/>(with iterationOf if revision)"]
    Wait["Wait for review response"]
    Check{"Agent interprets<br/>response"}
    Revise["Revise content using<br/>feedback from response"]
    Done["✅ Workflow complete"]

    Send --> Wait --> Check
    Check -->|needs revision| Revise
    Check -->|approved| Done
    Revise --> Send
    Check -->|expired| Done

    style Done fill:#22c55e,color:#fff
    style Revise fill:#f59e0b,color:#000
```

## Interpreting Responses (Agent Side)

Placet delivers the human's response as-is. The agent (or workflow) decides what constitutes "approval" vs "rejection":

* **Approval reviews** — check `response.selectedOption` (e.g. `"approve"` vs `"reject"`)
* **Form reviews** — inspect submitted field values
* **Text input** — read the text response and optionally the `feedback` field
* **Selection** — check `response.selectedItems`

The `feedback` field on the review response contains optional human-provided text explaining their decision. Use it to guide the next iteration.

<Tip>
  Define your review options to make agent-side interpretation simple. For example, use
  `{ id: "approve", label: "Approve" }` and `{ id: "revise", label: "Request Changes" }` —
  then check `response.selectedOption === "revise"` in your agent loop.
</Tip>

## Retrieving Iteration Chains

### Agent API

```bash theme={null}
GET /api/v1/messages/iterations/{messageId}?channel={channelId}
```

### Response

```json theme={null}
{
  "groupId": "msg-1",
  "iterations": [
    {
      "id": "msg-1",
      "iteration": 1,
      "text": "Draft report v1...",
      "review": {
        "status": "completed",
        "feedback": "Add Q2 data",
        "response": { "selectedOption": "reject" }
      }
    },
    {
      "id": "msg-2",
      "iteration": 2,
      "text": "Revised report with Q2...",
      "review": { "status": "completed", "response": { "selectedOption": "approve" } }
    }
  ]
}
```

You can pass **any message ID** from the chain — the API returns the complete chain sorted by iteration number.

## Validation Rules

The `iterationOf` parameter is validated by the backend:

| Rule                                           | Error                                                  |
| ---------------------------------------------- | ------------------------------------------------------ |
| Target message must exist                      | `400 Bad Request`                                      |
| Target must be in the same channel             | `400 Bad Request`                                      |
| Target review must be `completed` or `expired` | `400 Bad Request` — cannot iterate on a pending review |

<Warning>
  Messages in an iteration chain cannot be deleted while other messages reference the same group.
  This protects the integrity of the chain.
</Warning>

## Diff & Comparison Views

When iterations exist, the web app automatically shows what changed between versions:

* **Text diff** — inline additions (green) and deletions (red) between iterations
* **Image comparison** — side-by-side view of previous and current image attachments
* **Iteration breadcrumbs** — clickable `① → ② → ③` navigation with status indicators
* **Previous feedback** — the feedback from the last iteration is displayed for context

These views appear in the chat detail view, file preview modal, and the inbox detail.

## Inbox Integration

The inbox is iteration-aware:

* **Re-Review badge** — messages that are iteration #2+ show a "Re-Review" tag
* **Iteration breadcrumbs** — navigate between iterations directly from the inbox detail
* **Diff toggle** — compare the current iteration with the previous one
* **Pending reviews bar** — floating bar at the top of chat showing open reviews, with iteration chains grouped

## Webhook Events

When a human responds to a review, a webhook is delivered with:

```json theme={null}
{
  "event": "review:responded",
  "messageId": "msg-1",
  "channelId": "agent-123",
  "iteration": 1,
  "iterationGroupId": "msg-1",
  "feedback": "Please add Q2 projections.",
  "response": { "selectedOption": "reject" },
  "review": { ... }
}
```

The agent inspects the `response` and `feedback` fields to decide whether to iterate.

## MCP Server Tools

The MCP server exposes iteration support through enhanced tools:

| Tool                  | Iteration support                                |
| --------------------- | ------------------------------------------------ |
| `send_message`        | `iterationOf` parameter to chain messages        |
| `send_review_message` | `iterationOf` parameter to chain review messages |
| `wait_for_review`     | Returns `completed` with response and feedback   |
| `get_iteration_chain` | New tool — fetch all iterations for a message    |

## Agent Loop Pattern

A typical agent implementation handles iterations with a simple loop:

<CodeGroup>
  ```python Python theme={null}
  import requests, time

  def run_agent(channel, api_key):
  session = requests.Session()
  session.headers["x-api-key"] = api_key
  base = "http://localhost:3001"

      iteration_of = None
      content = generate_initial_content()

      while True:
          body = {
              "channelId": channel,
              "text": content,
              "metadata": {"generatedAt": time.time()},
              "review": {
                  "type": "approval",
                  "payload": {"options": [
                      {"id": "approve", "label": "Approve"},
                      {"id": "reject", "label": "Reject"},
                  ]},
              },
          }
          if iteration_of:
              body["iterationOf"] = iteration_of

          msg = session.post(f"{base}/api/v1/messages", json=body).json()

          result = session.get(
              f"{base}/api/v1/reviews/{msg['id']}/wait",
              params={"channel": channel, "timeout": "120000"},
          ).json()

          # Agent interprets the response — Placet just delivers it
          response = result["message"]["review"].get("response", {})
          if response.get("selectedOption") == "reject":
              feedback = result["message"]["review"].get("feedback", "")
              content = revise_content(content, feedback)
              iteration_of = msg["id"]
              continue  # next iteration

          break  # approved, expired, or timed out

  ```

  ```typescript TypeScript theme={null}
  async function runAgent(channel: string, apiKey: string) {
    const base = "http://localhost:3001";
    const headers = { "x-api-key": apiKey, "Content-Type": "application/json" };

    let iterationOf: string | undefined;
    let content = generateInitialContent();

    while (true) {
      const body: Record<string, unknown> = {
        channelId: channel,
        text: content,
        metadata: { generatedAt: Date.now() },
        review: {
          type: "approval",
          payload: { options: [
            { id: "approve", label: "Approve" },
            { id: "reject", label: "Reject" },
          ]},
        },
      };
      if (iterationOf) body.iterationOf = iterationOf;

      const msg = await fetch(`${base}/api/v1/messages`, {
        method: "POST", headers, body: JSON.stringify(body),
      }).then(r => r.json());

      const result = await fetch(
        `${base}/api/v1/reviews/${msg.id}/wait?channel=${channel}&timeout=120000`,
        { headers },
      ).then(r => r.json());

      // Agent interprets the response — Placet just delivers it
      const response = result.message?.review?.response;
      if (response?.selectedOption === "reject") {
        const feedback = result.message?.review?.feedback ?? "";
        content = reviseContent(content, feedback);
        iterationOf = msg.id;
        continue; // next iteration
      }

      break; // approved, expired, or timed out
    }
  }
  ```
</CodeGroup>

## Using Metadata for Agent Context

The `metadata` field on messages is a free-form JSON object that the agent controls. Placet stores it unchanged and returns it in all API responses. Use it to track agent-specific context across iterations:

```json theme={null}
{
  "metadata": {
    "runId": "run-abc-123",
    "model": "gpt-4",
    "promptVersion": "v2.1",
    "tokensUsed": 1847,
    "previousFeedback": ["Add Q2 data", "Fix growth %"]
  }
}
```

<Tip>
  Store your agent's run context in `metadata` so you can reconstruct state across iterations.
  Placet never reads or modifies this field.
</Tip>

## n8n / Automation Workflow Pattern

For workflow automation tools like n8n, implement the iteration loop using a **Switch node** after the wait step:

```mermaid theme={null}
flowchart LR
    Send["HTTP Request<br/>POST /messages"]
    Wait["HTTP Request<br/>GET /reviews/.../wait"]
    Switch{"Switch on<br/>response content"}
    Revise["AI Node<br/>Revise content"]
    Done["✅ Done"]

    Send --> Wait --> Switch
    Switch -->|rejected| Revise --> Send
    Switch -->|approved| Done
    Switch -->|expired| Done

    style Done fill:#22c55e,color:#fff
    style Revise fill:#f59e0b,color:#000
```

The key is the loop back from the Switch node to the Send node, passing the previous message ID as `iterationOf` and incorporating the feedback from the response. The Switch node inspects the response content (e.g. `selectedOption`) to determine the next step.


# Management Dashboard
Source: https://docs.placet.io/connections/management-dashboard

Expose your agent's management surface in the Placet dashboard by registering management credentials.

Placet's **Agent Management Dashboard** is an optional UI that lets a user inspect and control a connected agent runtime (sessions, audit logs, token usage, credentials, cron, MCP bridges, workspace, skills, scripts, channels, commands, agent card, A2A peers) directly from Placet — without ever exposing the agent's bearer token to the browser.

The protocol Placet speaks upstream is a bearer-authenticated **management API** rooted at `/api/v1/*`. Any agent runtime that implements the same surface — or a compatible subset — can be connected; the routes documented below describe the wire contract Placet expects upstream.

The dashboard is **off by default** per user. It becomes visible once a user enables it under **Settings → Preferences → Management Dashboard**. Placet auto-enables this preference the first time a user registers an agent that provides management credentials.

```mermaid theme={null}
sequenceDiagram
    participant Browser
    participant Placet
    participant Agent

    Browser->>Placet: GET /api/agents/:id/manage/sessions (JWT)
    Placet->>Placet: Look up stored management_url + api_key
    Placet->>Agent: GET {management_url}/api/v1/sessions<br/>Authorization: Bearer <stored key>
    Agent-->>Placet: 200 OK (JSON)
    Placet-->>Browser: 200 OK (JSON)
```

Placet owns a dedicated, typed endpoint for every upstream management route — it is **not** a generic wildcard proxy. Controllers are explicit to give the backend room for caching, cross-agent aggregation, and request shaping. When the upstream is unreachable Placet returns `502 Bad Gateway` and the frontend silently hides the view.

***

## Registering Management Credentials

An agent registers management credentials the same way it registers a channel — by calling `POST /api/v1/agents/setWebhook` on the Placet backend with the additional `management` object, or by using the dedicated `setManagement` endpoint.

### Option A — Combined with `setWebhook`

```http theme={null}
POST /api/v1/agents/setWebhook
x-api-key: <placet-agent-key>
Content-Type: application/json
```

```json theme={null}
{
  "channelId": "my-agent-id",
  "webhookUrl": "https://agent.example.com/placet/webhook",
  "management": {
    "url": "https://agent.example.com",
    "apiKey": "management-bearer-token"
  },
  "isSubagent": false,
  "parentChannelId": null
}
```

| Field               | Type             | Description                                                                                |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| `management.url`    | `string` (URL)   | Base URL of the agent runtime (`/api/v1` is appended automatically).                       |
| `management.apiKey` | `string`         | Management bearer token. Stored encrypted, returned as `***` to the UI.                    |
| `isSubagent`        | `boolean`        | `true` marks this channel as a HITL sub-channel that should be hidden from the agent list. |
| `parentChannelId`   | `string \| null` | When `isSubagent` is `true`, the `channelId` of the parent agent owning this HITL channel. |

### Option B — Dedicated endpoint

```http theme={null}
POST /api/v1/agents/setManagement
x-api-key: <placet-agent-key>
Content-Type: application/json
```

```json theme={null}
{
  "channelId": "my-agent-id",
  "url": "https://agent.example.com",
  "apiKey": "management-bearer-token"
}
```

Pass `"url": null, "apiKey": null` to **clear** the management credentials for a channel.

***

## Endpoints

Every endpoint listed below lives under `/api/agents/:agentId/manage/` on the Placet backend and maps 1:1 to the upstream `/api/v1/` route. All requests require a valid Placet user JWT (`Authorization: Bearer <jwt>`) and are scoped to the authenticated user's agent.

### Health

| Method | Placet path | Upstream route | Description               |
| ------ | ----------- | -------------- | ------------------------- |
| GET    | `/health`   | `/health`      | Management liveness check |

### Sessions

| Method | Placet path       | Upstream route    | Description                     |
| ------ | ----------------- | ----------------- | ------------------------------- |
| GET    | `/sessions`       | `/sessions`       | List sessions (metadata only)   |
| GET    | `/sessions/{key}` | `/sessions/{key}` | Full history for a session key  |
| DELETE | `/sessions/{key}` | `/sessions/{key}` | Remove a session (cache + file) |

### Audit log

| Method | Placet path           | Upstream route        | Description                 |
| ------ | --------------------- | --------------------- | --------------------------- |
| GET    | `/audit`              | `/audit`              | Filtered event list         |
| GET    | `/audit/tail`         | `/audit/tail`         | Last N events from today    |
| GET    | `/audit/stats`        | `/audit/stats`        | Aggregated event counts     |
| GET    | `/audit/runs/{runId}` | `/audit/runs/{runId}` | All events for a single run |

### Token usage

| Method | Placet path           | Upstream route        | Description                       |
| ------ | --------------------- | --------------------- | --------------------------------- |
| GET    | `/usage`              | `/usage`              | Aggregated totals + grouped items |
| GET    | `/usage/runs/{runId}` | `/usage/runs/{runId}` | Single-turn token-usage row       |

### Settings

Runtime settings exposed by the agent. Browser settings include the new browser tool controls shown in the Management Dashboard: `enable`, `max_named_sessions`, `domain_allowlist`, and `domain_denylist`.

| Method | Placet path | Upstream route | Description                                      |
| ------ | ----------- | -------------- | ------------------------------------------------ |
| GET    | `/settings` | `/settings`    | Read editable runtime settings and option lists  |
| PATCH  | `/settings` | `/settings`    | Apply partial settings updates and restart hints |

### Credentials

Generic secrets stored on the agent and made available to skills/tools as `${credentials.KEY}`. The `exposed` flag mirrors `config.tools.exec.exposed_credentials` — when `true` the key is injected as an env var into the shell-exec sandbox.

| Method | Placet path                  | Upstream route               | Description                                                       |
| ------ | ---------------------------- | ---------------------------- | ----------------------------------------------------------------- |
| GET    | `/credentials`               | `/credentials`               | List keys (values masked) + `exposed` flags                       |
| POST   | `/credentials`               | `/credentials`               | Create a secret (`{key, value, exposed?}`); `409` when key exists |
| GET    | `/credentials/{key}`         | `/credentials/{key}`         | Existence check                                                   |
| PUT    | `/credentials/{key}`         | `/credentials/{key}`         | Upsert (`{"value": "..."}`)                                       |
| PUT    | `/credentials/{key}/exposed` | `/credentials/{key}/exposed` | Toggle exec-sandbox exposure (`{"exposed": bool}`)                |
| DELETE | `/credentials/{key}`         | `/credentials/{key}`         | Remove                                                            |

#### LLM provider credentials

Provider API keys live under `config.providers.<name>.api_key`. OAuth-only providers (`github_copilot`, `openai_codex`) report `isOauth: true` and use a token store instead of `api_key`; for those, `POST` / `PUT` return `400` and the OAuth endpoints below must be used.

| Method | Placet path                                 | Upstream route                              | Description                                                 |
| ------ | ------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------- |
| GET    | `/credentials/providers`                    | `/credentials/providers`                    | List providers + `hasValue` / `isOauth` state               |
| POST   | `/credentials/providers`                    | `/credentials/providers`                    | Set `api_key` (create-only — `409` when already set)        |
| PUT    | `/credentials/providers/{name}`             | `/credentials/providers/{name}`             | Upsert `api_key` (`{"value": "..."}`)                       |
| DELETE | `/credentials/providers/{name}`             | `/credentials/providers/{name}`             | Clear `api_key`, or disconnect OAuth for OAuth providers    |
| POST   | `/credentials/providers/{name}/oauth/start` | `/credentials/providers/{name}/oauth/start` | Begin OAuth device flow (`github_copilot` only — see below) |
| GET    | `/credentials/providers/{name}/oauth/poll`  | `/credentials/providers/{name}/oauth/poll`  | Poll an in-progress OAuth flow (`?session_id=...`)          |

`POST /oauth/start` returns:

```json theme={null}
{
  "sessionId": "…",
  "mode": "device",
  "userCode": "ABCD-1234",
  "verificationUri": "https://github.com/login/device",
  "expiresIn": 900,
  "interval": 5
}
```

The agent polls the provider in the background; the client polls `GET /oauth/poll?session_id=…` every `interval` seconds and receives `{status: "pending" | "ok" | "error", error?, account?}`. On `ok` the OAuth token is persisted server-side (no value ever crosses the wire). `openai_codex` is intentionally **not** supported via REST — its OAuth client mandates a fixed `http://localhost:1455/auth/callback` redirect, so use your agent's local CLI to complete the OAuth login.

### Cron

| Method | Placet path          | Upstream route       | Description         |
| ------ | -------------------- | -------------------- | ------------------- |
| GET    | `/cron`              | `/cron`              | List jobs           |
| POST   | `/cron`              | `/cron`              | Create              |
| GET    | `/cron/{id}`         | `/cron/{id}`         | Get single job      |
| PATCH  | `/cron/{id}`         | `/cron/{id}`         | Partial update      |
| DELETE | `/cron/{id}`         | `/cron/{id}`         | Remove              |
| POST   | `/cron/{id}/run-now` | `/cron/{id}/run-now` | Trigger immediately |
| POST   | `/cron/{id}/pause`   | `/cron/{id}/pause`   | Disable             |
| POST   | `/cron/{id}/resume`  | `/cron/{id}/resume`  | Enable              |

### MCP servers

| Method | Placet path           | Upstream route        | Description          |
| ------ | --------------------- | --------------------- | -------------------- |
| GET    | `/mcp`                | `/mcp`                | List servers         |
| POST   | `/mcp`                | `/mcp`                | Add a server         |
| GET    | `/mcp/{name}`         | `/mcp/{name}`         | Get single server    |
| PATCH  | `/mcp/{name}`         | `/mcp/{name}`         | Edit config          |
| DELETE | `/mcp/{name}`         | `/mcp/{name}`         | Remove               |
| POST   | `/mcp/{name}/enable`  | `/mcp/{name}/enable`  | Enable + connect     |
| POST   | `/mcp/{name}/disable` | `/mcp/{name}/disable` | Disable + disconnect |
| POST   | `/mcp/{name}/restart` | `/mcp/{name}/restart` | Reconnect            |

### Tool policy

Persistent allow/deny rules for tool calls plus runtime toggles for the approval gate. `deny` wins over `allow`; missing rules trigger a one-time approval prompt unless the gate is disabled or skipped for cron callers.

| Method | Placet path        | Upstream route     | Description                                                                    |
| ------ | ------------------ | ------------------ | ------------------------------------------------------------------------------ |
| GET    | `/policy`          | `/policy`          | List rules + current `enabled` / `skipCron` flags and on-disk policy file path |
| POST   | `/policy`          | `/policy`          | Add a rule (`{action: 'allow' \| 'deny', tool, params?}`)                      |
| DELETE | `/policy`          | `/policy`          | Remove a single rule (same body shape as `POST`)                               |
| DELETE | `/policy/all`      | `/policy/all`      | Clear all rules                                                                |
| PATCH  | `/policy/settings` | `/policy/settings` | Update runtime flags (`{enabled?: boolean, skipCron?: boolean}`)               |

The `enabled` flag is the master switch for the approval gate — when off, every tool call runs without prompts and the rule list is ignored. `skipCron` lets cron-triggered tool calls bypass the approval prompt while keeping the gate active for interactive callers.

### Workspace

| Method | Placet path       | Upstream route    | Description                         |
| ------ | ----------------- | ----------------- | ----------------------------------- |
| GET    | `/workspace/tree` | `/workspace/tree` | Directory listing (`?path=&depth=`) |
| GET    | `/workspace/file` | `/workspace/file` | Read file contents (`?path=`)       |
| PUT    | `/workspace/file` | `/workspace/file` | Write file contents (`?path=`)      |
| DELETE | `/workspace/file` | `/workspace/file` | Delete file (`?path=`)              |

### Skills & scripts

| Method | Placet path | Upstream route | Description                  |
| ------ | ----------- | -------------- | ---------------------------- |
| GET    | `/skills`   | `/skills`      | List workspace `skills/*.md` |
| GET    | `/scripts`  | `/scripts`     | List workspace `scripts/*`   |

### Channels

| Method | Placet path        | Upstream route     | Description                              |
| ------ | ------------------ | ------------------ | ---------------------------------------- |
| GET    | `/channels`        | `/channels`        | List channel configs                     |
| GET    | `/channels/{name}` | `/channels/{name}` | Get channel config                       |
| PUT    | `/channels/{name}` | `/channels/{name}` | Upsert channel config (restart required) |
| DELETE | `/channels/{name}` | `/channels/{name}` | Remove channel config (restart required) |

### Commands

| Method | Placet path         | Upstream route      | Description        |
| ------ | ------------------- | ------------------- | ------------------ |
| POST   | `/commands/stop`    | `/commands/stop`    | Execute `/stop`    |
| POST   | `/commands/restart` | `/commands/restart` | Execute `/restart` |
| POST   | `/commands/new`     | `/commands/new`     | Execute `/new`     |
| POST   | `/commands/reflect` | `/commands/reflect` | Execute `/reflect` |
| GET    | `/commands/status`  | `/commands/status`  | Execute `/status`  |

### Agent Card

| Method | Placet path   | Upstream route | Description             |
| ------ | ------------- | -------------- | ----------------------- |
| GET    | `/agent-card` | `/agent-card`  | Live A2A AgentCard JSON |

### A2A peers

| Method | Placet path               | Upstream route            | Description                     |
| ------ | ------------------------- | ------------------------- | ------------------------------- |
| GET    | `/a2a/peers`              | `/a2a/peers`              | List registered peers           |
| POST   | `/a2a/peers`              | `/a2a/peers`              | Register / overwrite a peer     |
| DELETE | `/a2a/peers/{alias}`      | `/a2a/peers/{alias}`      | Remove a peer                   |
| GET    | `/a2a/peers/{alias}/card` | `/a2a/peers/{alias}/card` | Fetch the peer Agent Card       |
| POST   | `/a2a/peers/{alias}/call` | `/a2a/peers/{alias}/call` | Send a message through the peer |

### Error semantics

| Status | Meaning                                                                                                                                       |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing/invalid Placet JWT.                                                                                                                   |
| `404`  | Agent has no management credentials configured.                                                                                               |
| `502`  | Upstream timed out (15 s) or is unreachable. The frontend hides the dashboard silently.                                                       |
| other  | Upstream errors are normalized to `{ error: { code: 'upstream_<status>', message }, upstreamStatus }` and re-emitted at the same HTTP status. |

***

## Minimal Upstream Requirements

To support the management dashboard, your agent runtime **must**:

1. Expose a bearer-authenticated management API on `/api/v1/*` that matches the wire contract documented above.
2. Implement any subset of the routes above that you want users to see; unsupported ones simply return `404`, which the dashboard handles gracefully.
3. Accept a long-lived management bearer token that you can transmit to Placet via `setWebhook`/`setManagement`.

If a domain (e.g. `cron`, `mcp`) isn't supported by your runtime, the Placet UI tab for that feature stays empty — there is nothing else you need to do to "opt out".

***

## Security Notes

* Management keys are stored alongside webhook secrets and returned as `***` on every agent read.
* Only the agent owner (owner of the `apiKey` that registered the channel) can call `/manage/*` for that agent.
* Rotate a key by calling `setManagement` again; to revoke, set both fields to `null`.


# MCP (Model Context Protocol)
Source: https://docs.placet.io/connections/mcp

Connect AI coding agents (Claude Code, VS Code Copilot, Cursor, Windsurf) to Placet via the Model Context Protocol.

The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that lets AI assistants use external tools.
Placet ships an MCP server (`@placet/mcp`) that exposes all Placet capabilities — sending messages, requesting human reviews, rendering diagrams, and more — as MCP tools.

This is the recommended connection type when your agent runs inside an **AI-powered IDE or coding assistant** like Claude Code, VS Code Copilot, Cursor, or Windsurf.

```mermaid theme={null}
flowchart LR
    IDE["IDE / AI Assistant"] -->|MCP protocol| MCP["Placet MCP Server"]
    MCP -->|REST API| Backend["Placet Backend"]
    Backend --> Frontend["👤 Human Dashboard"]
```

## Transport Modes

The MCP server supports two transport modes:

| Mode                         | Use Case                               | Auth                           |
| ---------------------------- | -------------------------------------- | ------------------------------ |
| **StreamableHTTP** (default) | Remote/Docker deployment, multi-client | `x-api-key` header per request |
| **stdio**                    | Local development, single client       | `PLACET_API_KEY` env var       |

***

## Setup

### Docker (recommended)

The MCP server is included in the default `docker-compose.yml`:

```yaml theme={null}
mcp-server:
  container_name: placet-mcp-server
  build:
    context: .
    dockerfile: packages/mcp-server/Dockerfile
  environment:
    PLACET_API_URL: http://backend:3001
    MCP_PORT: 3002
  ports:
    - '3002:3002'
```

Start it alongside the rest of Placet:

```bash theme={null}
docker compose up -d
```

### npx (local / stdio)

For local development or one-off usage:

```bash theme={null}
PLACET_API_URL=http://localhost:3001 \
PLACET_API_KEY=hp_your-api-key \
npx @placet/mcp --stdio
```

***

## Client Configuration

### VS Code / GitHub Copilot

Create `.vscode/mcp.json` in your project:

```json theme={null}
{
  "servers": {
    "placet": {
      "type": "http",
      "url": "http://localhost:3002/mcp",
      "headers": {
        "x-api-key": "hp_your-api-key"
      }
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add placet \
  --transport http \
  --url http://localhost:3002/mcp \
  --header "x-api-key: hp_your-api-key"
```

Or add to `~/.claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "placet": {
      "command": "npx",
      "args": ["@placet/mcp", "--stdio"],
      "env": {
        "PLACET_API_URL": "http://localhost:3001",
        "PLACET_API_KEY": "hp_your-api-key"
      }
    }
  }
}
```

### Cursor

Add to Cursor settings (`Settings > MCP Servers`):

```json theme={null}
{
  "placet": {
    "url": "http://localhost:3002/mcp",
    "headers": {
      "x-api-key": "hp_your-api-key"
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "placet": {
      "serverUrl": "http://localhost:3002/mcp",
      "headers": {
        "x-api-key": "hp_your-api-key"
      }
    }
  }
}
```

### Any stdio-compatible client

For clients that support stdio transport:

```json theme={null}
{
  "mcpServers": {
    "placet": {
      "command": "npx",
      "args": ["@placet/mcp", "--stdio"],
      "env": {
        "PLACET_API_URL": "http://localhost:3001",
        "PLACET_API_KEY": "hp_your-api-key",
        "PLACET_DEFAULT_CHANNEL": "your-channel-id"
      }
    }
  }
}
```

<Tip>
  Set `PLACET_DEFAULT_CHANNEL` to make the `channelId` parameter optional in all tools. This is
  useful when your agent only works with a single channel.
</Tip>

***

## Available Tools

### Channel Management

| Tool             | Description                                                           |
| ---------------- | --------------------------------------------------------------------- |
| `list_channels`  | List all channels accessible by the API key                           |
| `create_channel` | Create a new channel with name, description, and optional webhook URL |

### Messages

| Tool             | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `send_message`   | Send an informational message with markdown and optional status indicator (`info`, `success`, `warning`, `error`) |
| `get_messages`   | List messages with pagination, search, and filtering                                                              |
| `get_message`    | Get a single message including review status and attachments                                                      |
| `delete_message` | Delete (retract) a message                                                                                        |

### Reviews (Human-in-the-Loop)

| Tool                  | Description                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `send_review_message` | Send a message that requires human interaction (see [review types](#review-types) below) |
| `wait_for_review`     | Long-poll for a human response (default 5 min, retryable)                                |
| `get_pending_reviews` | List all pending reviews in a channel                                                    |

### Status

| Tool          | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `ping_status` | Report agent heartbeat — shown as online indicator in the dashboard |

### Plugins

| Tool           | Description                                       |
| -------------- | ------------------------------------------------- |
| `list_plugins` | List all installed plugins and their capabilities |

Plugin tools are **registered dynamically** at startup. The MCP server fetches all installed plugin manifests from the backend and creates a `send_{plugin_name}_message` tool for each plugin that has an `inputSchema`. See [Dynamic Plugin Tools](#dynamic-plugin-tools) below.

***

## Review Types

The `send_review_message` tool supports 5 review types. The AI agent sends the review, and a human responds in the Placet dashboard.

### Approval

Show buttons for the human to approve or reject an action.

```json theme={null}
{
  "reviewType": "approval",
  "reviewPayload": {
    "options": [
      { "id": "approve", "label": "Approve", "style": "primary" },
      { "id": "reject", "label": "Reject", "style": "danger" }
    ],
    "allowComment": true
  }
}
```

**Button styles**: `primary` (green), `danger` (red), `secondary` (gray), `ghost` (outline)

**Response**: `{ "selectedOption": "approve", "comment": "Looks good!" }`

### Selection

Let the human choose from a list of options.

```json theme={null}
{
  "reviewType": "selection",
  "reviewPayload": {
    "mode": "single",
    "items": [
      { "id": "opt-a", "label": "Option A", "description": "First choice" },
      { "id": "opt-b", "label": "Option B", "description": "Second choice" }
    ]
  }
}
```

Set `mode` to `"multi"` to allow selecting multiple items.

**Response**: `{ "selectedIds": ["opt-a"] }`

### Form

Render a structured form with typed fields.

```json theme={null}
{
  "reviewType": "form",
  "reviewPayload": {
    "fields": [
      { "name": "serverName", "type": "text", "label": "Server Name", "required": true },
      {
        "name": "region",
        "type": "select",
        "label": "Region",
        "options": [
          { "value": "eu-west-1", "label": "EU West" },
          { "value": "us-east-1", "label": "US East" }
        ]
      },
      { "name": "instances", "type": "number", "label": "Instances", "min": 1, "max": 10 },
      { "name": "enableSSL", "type": "checkbox", "label": "Enable SSL", "defaultValue": true },
      { "name": "goLive", "type": "date", "label": "Go-Live Date" },
      { "name": "notes", "type": "textarea", "label": "Notes", "placeholder": "Any details..." }
    ],
    "submitLabel": "Deploy"
  }
}
```

**Supported field types**: `text`, `number`, `email`, `url`, `textarea`, `select`, `checkbox`, `date`, `time`, `datetime`, `range`, `password`

**Field options**: `required`, `placeholder`, `defaultValue`, `min`, `max`, `step`, `unit`, `options` (for `select`)

**Response**: `{ "serverName": "prod-api-02", "region": "eu-west-1", "instances": 3, "enableSSL": true, ... }`

### Text Input

Free text input, optionally with a markdown editor.

```json theme={null}
{
  "reviewType": "text-input",
  "reviewPayload": {
    "markdown": true,
    "placeholder": "Your response...",
    "prefill": "## Template\n\n",
    "minLength": 10,
    "maxLength": 5000
  }
}
```

**Response**: `{ "text": "The user's response text..." }`

### Freeform

Pass-through for custom plugin UIs. See [Dynamic Plugin Tools](#dynamic-plugin-tools).

***

## Dynamic Plugin Tools

The MCP server discovers installed plugins at startup and registers a tool for each one. For example, the built-in plugins create these tools:

### `send_kroki_diagram_message`

Render diagrams (Mermaid, PlantUML, D2, Graphviz, etc.) as SVG via a [Kroki](https://kroki.io/) server.

```json theme={null}
{
  "pluginData": {
    "type": "mermaid",
    "source": "graph TD\n    A[Start] --> B[End]"
  }
}
```

**Supported diagram types**: `mermaid`, `plantuml`, `d2`, `graphviz`, `ditaa`, `erd`, `nomnoml`, `svgbob`, `vega`, `vegalite`, `wavedrom`, `bytefield`, `excalidraw`

### `send_form_submit_message`

Render a pre-filled form and submit to a webhook.

```json theme={null}
{
  "pluginData": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Access request for the staging environment"
  }
}
```

<Note>
  When you install additional plugins with an `inputSchema`, the MCP server automatically creates
  new `send_{plugin}_message` tools — no code changes required.
</Note>

***

## Workflow Pattern

The typical MCP workflow is **fire → poll → continue**:

```mermaid theme={null}
sequenceDiagram
    participant AI as AI Agent (IDE)
    participant MCP as MCP Server
    participant Backend as Placet Backend
    participant Human as 👤 Human

    AI->>MCP: send_review_message (approval)
    MCP->>Backend: POST /api/v1/messages
    Backend->>Human: Show in dashboard
    MCP-->>AI: { status: "pending", messageId: "..." }
    AI->>MCP: wait_for_review (messageId)
    MCP->>Backend: GET /api/v1/reviews/{id}/wait (30s long-poll loop)
    Human->>Backend: Click "Approve"
    Backend-->>MCP: { status: "completed", response: { selectedOption: "approve" } }
    MCP-->>AI: Review result
    AI->>AI: Continue based on response
```

The `wait_for_review` tool holds the connection for up to 5 minutes (configurable via `MCP_CONNECTION_TIMEOUT_MS`), polling the backend every 30 seconds. If the human hasn't responded, it returns `status: "timeout"` — the agent can call `wait_for_review` again to keep waiting.

<Warning>
  Some MCP clients (like VS Code) have their own HTTP timeouts that may be shorter than the
  configured wait time. If `waitInline=true` fails, use the two-step pattern: `send_review_message`
  followed by `wait_for_review`.
</Warning>

***

## Environment Variables

| Variable                    | Default      | Description                                                 |
| --------------------------- | ------------ | ----------------------------------------------------------- |
| `PLACET_API_URL`            | *(required)* | Placet backend URL (e.g. `http://localhost:3001`)           |
| `PLACET_API_KEY`            | —            | API key (required for stdio mode, optional for HTTP mode)   |
| `PLACET_DEFAULT_CHANNEL`    | —            | Default channel ID, makes `channelId` optional in all tools |
| `MCP_PORT`                  | `3002`       | HTTP transport listen port                                  |
| `MCP_PATH`                  | `/mcp`       | HTTP transport endpoint path                                |
| `MCP_CONNECTION_TIMEOUT_MS` | `300000`     | Max time `wait_for_review` holds a connection (5 min)       |
| `MCP_TRANSPORT`             | —            | Set to `stdio` as alternative to `--stdio` flag             |


# OAuth Relay
Source: https://docs.placet.io/connections/oauth-relay

Relay OAuth authorization flows through Placet to connected agents.

<Warning>
  This feature is **experimental** and may change without notice in future releases.
</Warning>

Placet can act as an OAuth relay, allowing connected agents to initiate OAuth authorization flows that involve the end user — without the agent needing direct browser access.

This is useful when an agent needs the user to authorize a third-party service (e.g., GitHub, Google, Slack) and the agent runs headlessly behind Placet.

## Supported Flows

### Authorization Code + PKCE

The agent generates a PKCE challenge and constructs the authorization URL with Placet's callback as the `redirect_uri`. The user clicks the link in the Placet UI, authorizes the app, and the OAuth provider redirects back to Placet. Placet then relays the authorization code to the agent via Socket.IO.

**Security:** The PKCE verifier never leaves the agent. Placet only sees the authorization code (which is useless without the verifier).

### Device Code

The agent initiates a device code flow with the OAuth provider and sends the verification URL + user code to the user via Placet. The user opens the URL and enters the code. The agent polls the token endpoint directly.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Placet
    participant User
    participant Provider as OAuth Provider

    Note over Agent,Provider: Authorization Code + PKCE Flow
    Agent->>Placet: emit oauth:start {authUrl, state, provider}
    Placet->>User: Forward oauth:start to frontend
    User->>Provider: Click link → authorize
    Provider->>Placet: GET /api/v1/oauth/callback?code=...&state=...
    Placet->>Agent: emit oauth:code {code, state, provider}
    Agent->>Provider: Exchange code + PKCE verifier for token
```

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Placet
    participant User
    participant Provider as OAuth Provider

    Note over Agent,Provider: Device Code Flow
    Agent->>Provider: Request device code
    Provider-->>Agent: {device_code, user_code, verification_uri}
    Agent->>Placet: emit oauth:start {deviceCode: {verificationUri, userCode}}
    Placet->>User: Forward to frontend (shows link + code)
    User->>Provider: Open link, enter code, authorize
    Agent->>Provider: Poll token endpoint
    Provider-->>Agent: Access token
```

## Callback URL

The OAuth callback endpoint is:

```
{PLACET_URL}/api/v1/oauth/callback
```

Use this as the `redirect_uri` when constructing authorization URLs for the Authorization Code flow.

## Socket.IO Events

### `oauth:start` (agent → server)

Emitted by the agent to initiate an OAuth flow. The server registers the state for callback resolution and forwards the event to the user's frontend.

```typescript theme={null}
socket.emit('oauth:start', {
  channelId: 'your-agent-id',
  state: 'random-state-string',
  provider: 'github',
  // For Authorization Code flow:
  authUrl: 'https://github.com/login/oauth/authorize?...',
  // For Device Code flow:
  deviceCode: {
    verificationUri: 'https://github.com/login/device',
    userCode: 'ABCD-1234',
    expiresIn: 900,
  },
});
```

| Field                        | Type   | Required | Description                             |
| ---------------------------- | ------ | -------- | --------------------------------------- |
| `channelId`                  | string | Yes      | The agent's channel ID                  |
| `state`                      | string | Yes      | Unique state parameter for this flow    |
| `provider`                   | string | Yes      | Name of the OAuth provider              |
| `authUrl`                    | string | No       | Full authorization URL (Auth Code flow) |
| `deviceCode`                 | object | No       | Device code details (Device Code flow)  |
| `deviceCode.verificationUri` | string | Yes\*    | URL for the user to visit               |
| `deviceCode.userCode`        | string | Yes\*    | Code for the user to enter              |
| `deviceCode.expiresIn`       | number | No       | Seconds until the device code expires   |

### `oauth:code` (server → agent)

Emitted to the agent's channel when the OAuth callback receives an authorization code.

```json theme={null}
{
  "state": "random-state-string",
  "code": "the-authorization-code",
  "provider": "github"
}
```

### `oauth:error` (server → agent)

Emitted when the OAuth provider returns an error to the callback.

```json theme={null}
{
  "state": "random-state-string",
  "error": "access_denied",
  "errorDescription": "The user denied the request",
  "provider": "github"
}
```

### `oauth:start` (server → frontend)

Forwarded to the user's frontend session to display the authorization link or device code.

```json theme={null}
{
  "channelId": "your-agent-id",
  "state": "random-state-string",
  "provider": "github",
  "authUrl": "https://github.com/login/oauth/authorize?...",
  "deviceCode": null
}
```

## State Management

* Each `oauth:start` event registers the `state` parameter in an in-memory store with a **10-minute TTL**.
* The state is consumed (single-use) when the callback arrives.
* Expired or unknown states return an error page to the user.

## Example: Agent Integration (TypeScript)

```typescript theme={null}
import { io } from 'socket.io-client';
import crypto from 'crypto';

const socket = io('https://your-placet.com/ws', {
  auth: { apiKey: 'hp_your-key' },
  transports: ['websocket'],
});

// Generate PKCE
const verifier = crypto.randomBytes(32).toString('base64url');
const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');

const state = crypto.randomBytes(16).toString('hex');

const authUrl = new URL('https://github.com/login/oauth/authorize');
authUrl.searchParams.set('client_id', 'your-client-id');
authUrl.searchParams.set('redirect_uri', 'https://your-placet.com/api/v1/oauth/callback');
authUrl.searchParams.set('state', state);
authUrl.searchParams.set('code_challenge', challenge);
authUrl.searchParams.set('code_challenge_method', 'S256');
authUrl.searchParams.set('scope', 'read:user');

socket.emit('subscribe:channel', 'your-agent-id');
socket.emit('oauth:start', {
  channelId: 'your-agent-id',
  state,
  provider: 'github',
  authUrl: authUrl.toString(),
});

socket.on('oauth:code', async (data) => {
  if (data.state !== state) return; // ignore unrelated flows

  // Exchange code for token using PKCE verifier
  const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
    method: 'POST',
    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: 'your-client-id',
      code: data.code,
      code_verifier: verifier,
    }),
  });

  const { access_token } = await tokenResponse.json();
  console.log('Got token:', access_token);
});
```


# REST API
Source: https://docs.placet.io/connections/rest-api

Interact with Placet via HTTP requests — send messages, request reviews, and long-poll for responses.

The REST API is the most straightforward way to integrate with Placet. Send HTTP requests to create messages, request human reviews, and poll for responses. Works from any language, any environment — no persistent connections or public endpoints required.

This is the recommended connection type for **scripts, CLI tools, serverless functions**, and any agent that runs as a short-lived process.

```mermaid theme={null}
flowchart LR
    Agent["🤖 Agent"] -->|HTTP requests| Backend["Placet Backend"]
    Backend --> Frontend["👤 Human Dashboard"]
    Frontend --> Backend
    Backend -->|HTTP response| Agent
```

## Authentication

All API requests require an API key passed in the `x-api-key` header:

```bash theme={null}
curl -H "x-api-key: hp_your-api-key" \
  https://your-placet-instance.com/api/v1/agents
```

API keys are created in the Placet dashboard under **Settings > API Keys**. They always start with `hp_`.

***

## Sending Messages

### Informational Messages

Send status updates, logs, reports, or any content that doesn't require a response. Messages support full markdown.

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "your-agent-id",
    "text": "## Build Complete\n\nAll **47 tests** passed in 2.3s.",
    "status": "success",
    "metadata": { "buildId": "build-123", "duration": 2.3 }
  }'
```

**Status indicators**: `info` (blue), `success` (green), `warning` (yellow), `error` (red)

### Messages with Reviews

Send a message that requires human interaction:

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "your-agent-id",
    "text": "Deploy to production?",
    "review": {
      "type": "approval",
      "payload": {
        "options": [
          { "id": "approve", "label": "Approve", "style": "primary" },
          { "id": "reject", "label": "Reject", "style": "danger" }
        ],
        "allowComment": true
      },
      "expiresInSeconds": 3600
    }
  }'
```

See [Review Types](/concepts/agents#review-types) for all available review types and their payloads.

***

## Streaming Replies

For agents that produce a reply token-by-token, Placet supports a draft-then-update model:

1. **Start the draft** — `POST /api/v1/messages` with `streamId` (a stable id for this turn), `streamState: "streaming"`, and the partial `text` so far. The response contains the persisted message id.
2. **Append updates** — `PATCH /api/v1/messages/streams/:streamId` with the latest accumulated `text` whenever new tokens arrive. Throttle these to a few per second; the WebSocket `message:delta` event drives instant UI updates between PATCH calls.
3. **Finalise** — `PATCH /api/v1/messages/streams/:streamId` with the final `text` and `complete: true`. The frontend stops treating the row as a live draft and pins it back into chronological order.

The `(channelId, streamId)` pair is unique, so the first POST is idempotent: a retried POST returns the existing draft rather than creating a duplicate row. Refreshing the chat mid-stream redisplays whatever has been PATCHed so far — the streamed reply never disappears on reload.

***

## Long-Polling

The simplest way to wait for a human response. Your agent sends a request and blocks until the human responds (or the poll times out).

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Placet
    participant Human

    Agent->>Placet: POST /api/v1/messages (with review)
    Placet-->>Agent: { id: "msg_123", review: { status: "pending" } }
    Agent->>Placet: GET /api/v1/reviews/msg_123/wait?channel=...
    Note over Placet: Polls DB every 2s, holds up to 30s
    Human->>Placet: Responds in dashboard
    Placet-->>Agent: { status: "completed", message: { review: { response: {...} } } }
```

### Usage

```bash theme={null}
# 1. Send a message with a review
RESPONSE=$(curl -s -X POST "$PLACET_URL/api/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "your-agent-id",
    "text": "Continue processing?",
    "review": {
      "type": "approval",
      "payload": {
        "options": [
          { "id": "yes", "label": "Yes" },
          { "id": "no", "label": "No" }
        ]
      }
    }
  }')

MESSAGE_ID=$(echo "$RESPONSE" | jq -r '.id')

# 2. Long-poll for the response (repeat until completed or expired)
while true; do
  RESULT=$(curl -s "$PLACET_URL/api/v1/reviews/$MESSAGE_ID/wait?channel=your-agent-id&timeout=30000" \
    -H "x-api-key: $API_KEY")

  STATUS=$(echo "$RESULT" | jq -r '.status')

  if [ "$STATUS" = "completed" ]; then
    echo "Response: $(echo "$RESULT" | jq '.message.review.response')"
    break
  elif [ "$STATUS" = "expired" ]; then
    echo "Review expired"
    break
  elif [ "$STATUS" = "timeout" ]; then
    : # poll again
  fi
done
```

### Parameters

| Parameter | Default      | Description                            |
| --------- | ------------ | -------------------------------------- |
| `channel` | *(required)* | Agent/channel ID                       |
| `timeout` | `30000`      | Max wait time in ms (capped at 30,000) |

### Response States

| `status`    | Meaning                                                         |
| ----------- | --------------------------------------------------------------- |
| `completed` | Human responded — `message.review.response` contains the answer |
| `timeout`   | Timeout reached, no response yet — call again to keep waiting   |
| `expired`   | Review expired (default 24h) — no response will come            |

<Tip>
  A single poll waits up to 30 seconds. For reviews that may take minutes or hours, simply loop the
  poll call. The review stays active until the human responds or it expires.
</Tip>

***

## Python Example

```python theme={null}
import requests
import time

PLACET_URL = "http://localhost:3001"
API_KEY = "hp_your-api-key"
CHANNEL_ID = "your-agent-id"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}

# Send a form review
msg = requests.post(f"{PLACET_URL}/api/v1/messages", headers=headers, json={
    "channelId": CHANNEL_ID,
    "text": "Please configure the deployment:",
    "review": {
        "type": "form",
        "payload": {
            "fields": [
                {"name": "env", "type": "select", "label": "Environment", "required": True,
                 "options": [
                     {"value": "staging", "label": "Staging"},
                     {"value": "production", "label": "Production"},
                 ]},
                {"name": "instances", "type": "number", "label": "Instances", "min": 1, "max": 10},
            ],
            "submitLabel": "Deploy",
        },
    },
}).json()

# Poll for the response
while True:
    result = requests.get(
        f"{PLACET_URL}/api/v1/reviews/{msg['id']}/wait",
        headers={"x-api-key": API_KEY},
        params={"channel": CHANNEL_ID, "timeout": 30000},
    ).json()

    status = result.get("status")
    if status == "completed":
        response = result["message"]["review"]["response"]
        print(f"Deploy to {response['env']} with {response['instances']} instances")
        break
    elif status == "expired":
        print("Review expired")
        break
    # Still pending — poll again
```

***

## TypeScript Example

```typescript theme={null}
const PLACET_URL = 'http://localhost:3001';
const API_KEY = 'hp_your-api-key';
const CHANNEL_ID = 'your-agent-id';

const headers = {
  'x-api-key': API_KEY,
  'Content-Type': 'application/json',
};

// Send a selection review
const msg = await fetch(`${PLACET_URL}/api/v1/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    channelId: CHANNEL_ID,
    text: 'Which database migration should we run?',
    review: {
      type: 'selection',
      payload: {
        mode: 'single',
        items: [
          { id: 'migrate-up', label: 'Run pending migrations' },
          { id: 'migrate-down', label: 'Rollback last migration' },
          { id: 'skip', label: 'Skip — no changes needed' },
        ],
      },
    },
  }),
}).then((r) => r.json());

// Poll for the response
while (true) {
  const result = await fetch(
    `${PLACET_URL}/api/v1/reviews/${msg.id}/wait?channel=${CHANNEL_ID}&timeout=30000`,
    { headers: { 'x-api-key': API_KEY } },
  ).then((r) => r.json());

  if (result.status === 'completed') {
    console.log('Selected:', result.message.review.response.selectedIds);
    break;
  }
  if (result.status === 'expired') {
    console.log('Review expired');
    break;
  }
}
```

***

## Delivery Acknowledgment

Acknowledge that your agent received and processed a message. This updates the delivery status shown in the Placet dashboard (WhatsApp-style checkmarks).

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/messages/$MESSAGE_ID/ack?channel=$CHANNEL_ID" \
  -H "x-api-key: $API_KEY"
```

| Status              | Icon      | Meaning                    |
| ------------------- | --------- | -------------------------- |
| `sent`              | ✓         | Message stored             |
| `webhook_delivered` | ✓✓        | Webhook received 2xx       |
| `webhook_failed`    | ✓ ❌       | Webhook delivery failed    |
| `agent_received`    | ✓✓ (blue) | Agent acknowledged receipt |

***

## API Endpoints

For the full API reference with request/response schemas, see the [REST API Reference](/api-reference).

| Method   | Endpoint                             | Description                               |
| -------- | ------------------------------------ | ----------------------------------------- |
| `POST`   | `/api/v1/messages`                   | Send a message (with optional review)     |
| `PATCH`  | `/api/v1/messages/streams/:streamId` | Update a streaming draft (text, complete) |
| `GET`    | `/api/v1/messages`                   | List messages (paginated, searchable)     |
| `GET`    | `/api/v1/messages/:id`               | Get a single message                      |
| `DELETE` | `/api/v1/messages/:id`               | Delete (retract) a message                |
| `POST`   | `/api/v1/messages/:id/ack`           | Acknowledge receipt                       |
| `GET`    | `/api/v1/reviews/pending`            | List pending reviews                      |
| `GET`    | `/api/v1/reviews/:id`                | Get review by message ID                  |
| `GET`    | `/api/v1/reviews/:id/wait`           | Long-poll for review response             |
| `GET`    | `/api/v1/agents`                     | List channels                             |
| `POST`   | `/api/v1/agents`                     | Create a channel                          |
| `POST`   | `/api/v1/status/ping`                | Report agent heartbeat                    |
| `GET`    | `/api/v1/plugins`                    | List installed plugins                    |
| `GET`    | `/api/v1/plugins/:name`              | Get plugin details                        |
| `POST`   | `/api/v1/files/upload`               | Upload a file                             |
| `POST`   | `/api/v1/files/store`                | Store a file for later attachment         |
| `GET`    | `/api/v1/files/:id/download`         | Download a file                           |


# Webhooks
Source: https://docs.placet.io/connections/webhooks

Receive HTTP callbacks when humans respond to reviews — no persistent connections required.

Webhooks let Placet push review responses to your server via HTTP callbacks. Your agent sends a message with a review and a `webhookUrl`, and Placet POSTs the response to that URL when a human responds.

This is the recommended connection type for **background automations, CI/CD pipelines, and serverless functions** that can't maintain persistent connections.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Placet
    participant Human

    Agent->>Placet: POST /api/v1/messages (with webhookUrl)
    Placet->>Human: Show in dashboard
    Human->>Placet: Respond to review
    Placet->>Agent: POST webhookUrl (response payload)
```

## When to Use Webhooks

* Your agent runs as a **background service** or **serverless function**
* You don't want to hold a connection open waiting for a response
* Your agent has a **publicly accessible HTTP endpoint**
* You need **fire-and-forget** with async response handling

If your agent can't expose a public endpoint, use [Long-Polling](/connections/rest-api#long-polling) or [MCP](/connections/mcp) instead.

***

## Setting a Webhook URL

Webhook URLs can be set at three levels, in order of priority:

### 1. Per-message (highest priority)

Set `webhookUrl` directly on the message:

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "your-agent-id",
    "text": "Approve deployment to production?",
    "webhookUrl": "https://your-server.com/webhook/deploy",
    "review": {
      "type": "approval",
      "payload": {
        "options": [
          { "id": "approve", "label": "Approve", "style": "primary" },
          { "id": "reject", "label": "Reject", "style": "danger" }
        ]
      }
    }
  }'
```

### 2. Per-channel (default for all messages)

Configure a default webhook URL on the channel/agent in the dashboard under **Settings > Channels**. This URL is used for all messages in that channel unless overridden by a per-message URL.

### 3. Legacy callback (lowest priority)

Set `review.callback` on the review object:

```json theme={null}
{
  "review": {
    "type": "approval",
    "payload": { "options": [{ "id": "ok", "label": "OK" }] },
    "callback": {
      "url": "https://your-server.com/webhook",
      "method": "POST",
      "headers": { "X-Custom-Header": "value" }
    }
  }
}
```

<Note>
  The first matching webhook URL wins. If a message has `webhookUrl`, the channel-level and callback
  URLs are ignored.
</Note>

***

## Webhook Payload

When a human responds, Placet POSTs a JSON payload to your webhook URL:

```json theme={null}
{
  "event": "review:responded",
  "channelId": "clxyz456",
  "message_id": "clxyz111",
  "review_type": "approval",
  "response": {
    "selectedOption": "approve",
    "comment": "Looks good, ship it!"
  },
  "responded_at": "2026-04-01T14:32:00.000Z"
}
```

The `response` shape depends on the review type:

| Review Type  | Response Fields                        |
| ------------ | -------------------------------------- |
| `approval`   | `selectedOption`, `comment?`           |
| `selection`  | `selectedIds` (string array)           |
| `form`       | Key-value pairs matching field `name`s |
| `text-input` | `text` (string)                        |
| `freeform`   | Arbitrary key-value pairs              |

***

## Webhook Server Example

A minimal Express.js server that handles webhook callbacks:

```typescript theme={null}
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/deploy', (req, res) => {
  const { event, response, message_id } = req.body;

  if (event === 'review:responded') {
    const { selectedOption, comment } = response;
    console.log(`Deployment ${selectedOption} (message: ${message_id})`);
    if (comment) console.log(`Comment: ${comment}`);

    if (selectedOption === 'approve') {
      // Trigger deployment pipeline
      triggerDeploy();
    }
  }

  res.sendStatus(200);
});

app.listen(8080, () => {
  console.log('Webhook server running on :8080');
});
```

***

## Delivery Status

Placet tracks webhook delivery and exposes the status in the dashboard:

| Status              | Meaning                                          |
| ------------------- | ------------------------------------------------ |
| `sent`              | Message stored, webhook not yet sent             |
| `webhook_delivered` | Your endpoint returned 2xx                       |
| `webhook_failed`    | Your endpoint returned non-2xx or timed out      |
| `agent_received`    | Agent explicitly acknowledged (via ACK endpoint) |

### Retrying Failed Deliveries

When a webhook delivery fails, users can retry from the dashboard UI. The retry re-sends the original payload.

***

## Security

### SSRF Protection

Placet validates all webhook URLs and blocks requests to private/internal IP ranges to prevent SSRF attacks:

* `10.0.0.0/8`
* `172.16.0.0/12`
* `192.168.0.0/16`
* `127.0.0.0/8`
* `::1`, `fd00::/8`

<Warning>
  Your webhook endpoint **must be publicly accessible**. Placet will reject requests to private IP
  addresses and localhost URLs.
</Warning>

### Timeouts

Webhook requests have a **10-second timeout**. If your endpoint doesn't respond within 10 seconds, the delivery is marked as `webhook_failed`.

### Recommendations

* Return `200 OK` as quickly as possible — process the payload asynchronously
* Implement idempotency using the `message.id` field to handle retries
* Validate the payload structure before processing
* Use HTTPS for your webhook endpoint in production


# WebSocket
Source: https://docs.placet.io/connections/websocket

Real-time bidirectional communication via Socket.IO for persistent agent connections.

WebSocket provides real-time, bidirectional communication between your agent and Placet. Built on [Socket.IO](https://socket.io/), it delivers instant push notifications when humans respond to reviews, send messages, or when delivery status changes.

This is the recommended connection type for **interactive agents** that need to react immediately to human input and maintain a persistent connection.

```mermaid theme={null}
flowchart LR
    Agent["🤖 Agent"] <-->|Socket.IO /ws| Backend["Placet Backend"]
    Backend --> Frontend["👤 Human Dashboard"]
    Frontend --> Backend
```

## When to Use WebSocket

* Your agent runs **continuously** (server process, daemon, long-running script)
* You need **real-time** responses (sub-second latency)
* Your agent handles **multiple channels** simultaneously
* You want **bidirectional** communication (send + receive)

For short-lived scripts or serverless functions, consider [Long-Polling](/connections/rest-api#long-polling) or [Webhooks](/connections/webhooks) instead.

***

## Authentication

Agents authenticate by passing their API key in the Socket.IO `auth` object:

```typescript theme={null}
import { io } from 'socket.io-client';

const socket = io('https://your-placet-instance.com/ws', {
  auth: { apiKey: 'hp_your-api-key' },
  transports: ['websocket'],
});
```

```python theme={null}
import socketio

sio = socketio.Client()
sio.connect(
    "https://your-placet-instance.com",
    namespaces=["/ws"],
    auth={"apiKey": "hp_your-api-key"},
    transports=["websocket"],
)
```

The server validates the API key on connection. Invalid or missing keys result in an immediate disconnect.

<Note>
  The frontend dashboard uses a different auth method: a short-lived JWT ticket obtained via `POST
      /api/auth/ws-ticket`. This is handled automatically by the Placet frontend.
</Note>

***

## Channel Subscription

After connecting, subscribe to channels to receive their events:

```typescript theme={null}
socket.on('connect', () => {
  // Subscribe to one or more channels
  socket.emit('subscribe:channel', 'your-agent-id');
  socket.emit('subscribe:channel', 'another-agent-id');
});

// Unsubscribe when no longer needed
socket.emit('unsubscribe:channel', 'your-agent-id');
```

<Warning>
  The server verifies that the API key has access to the channel. Subscribing to a channel your API
  key doesn't own will silently fail.
</Warning>

***

## Events

All events are received on the `/ws` namespace.

### `message:created`

A new message was posted in a subscribed channel.

```json theme={null}
{
  "id": "clxyz111",
  "channelId": "clxyz456",
  "senderType": "user",
  "senderId": "user_abc",
  "text": "Looks good, ship it!",
  "status": null,
  "review": null,
  "metadata": null,
  "createdAt": "2026-04-01T14:30:00.000Z",
  "attachments": []
}
```

### `message:updated`

An existing message row changed — most commonly because an agent PATCHed the
draft of a streaming reply (see [Streaming Replies](/connections/rest-api#streaming-replies)).
The full updated message record is emitted; clients should replace the row by
`id` in place. Messages with `streamState === "streaming"` are still live drafts;
once `streamState` flips to `"complete"` the reply is final.

### `message:delta`

A streaming agent reply produced a new chunk. Used for low-latency UI updates
between the slower PATCH-driven `message:updated` events. Match deltas to the
draft row by `streamBaseId` (which equals the row's `streamId` column).

```json theme={null}
{
  "channelId": "clxyz456",
  "delta": " more tokens",
  "streamBaseId": "stream-abc",
  "streamId": "stream-abc:2",
  "streamStartedAt": "2026-04-01T14:30:00.000Z"
}
```

### `review:responded`

A human completed a review (approval, selection, form, etc.). The full message record is emitted, including attachments.

```json theme={null}
{
  "id": "clxyz111",
  "channelId": "clxyz456",
  "senderType": "agent",
  "senderId": "clxyz456",
  "text": "Deploy to production?",
  "status": null,
  "review": {
    "type": "approval",
    "status": "completed",
    "payload": {
      "options": [
        { "id": "approve", "label": "Approve", "style": "primary" },
        { "id": "reject", "label": "Reject", "style": "danger" }
      ]
    },
    "response": {
      "selectedOption": "approve",
      "comment": "Go ahead"
    },
    "completed_at": "2026-04-01T14:32:00.000Z"
  },
  "metadata": null,
  "createdAt": "2026-04-01T14:30:00.000Z",
  "attachments": []
}
```

The `review.response` shape depends on the review type:

| Review Type  | Response Fields                        |
| ------------ | -------------------------------------- |
| `approval`   | `selectedOption`, `comment?`           |
| `selection`  | `selectedIds` (string array)           |
| `form`       | Key-value pairs matching field `name`s |
| `text-input` | `text` (string)                        |
| `freeform`   | Arbitrary key-value pairs              |

### `review:expired`

A review expired without a human response (default: 24 hours).

```json theme={null}
{
  "messageId": "clxyz111"
}
```

### `message:delivery`

A message's delivery status changed.

```json theme={null}
{
  "messageId": "clxyz111",
  "deliveryStatus": "agent_received"
}
```

| Status              | Meaning                              |
| ------------------- | ------------------------------------ |
| `sent`              | Message stored, webhook not yet sent |
| `webhook_delivered` | Webhook received 2xx response        |
| `webhook_failed`    | Webhook delivery failed              |
| `agent_received`    | Agent acknowledged receipt           |

### `agent:status`

An agent's heartbeat status changed.

```json theme={null}
{
  "agentId": "clxyz456",
  "status": "active",
  "statusMessage": "Processing batch job",
  "statusSince": "2026-04-01T14:00:00.000Z"
}
```

### `ping` / `pong`

Send a `ping` event to check the connection is alive. The server responds with `pong`.

```typescript theme={null}
socket.emit('ping');
socket.on('pong', () => console.log('Connection alive'));
```

***

## Full Example

A complete agent that sends a deployment approval request and waits for the response via WebSocket:

```typescript theme={null}
import { io } from 'socket.io-client';

const PLACET_URL = 'https://your-placet-instance.com';
const API_KEY = 'hp_your-api-key';
const CHANNEL_ID = 'your-agent-id';

// 1. Connect via WebSocket
const socket = io(`${PLACET_URL}/ws`, {
  auth: { apiKey: API_KEY },
  transports: ['websocket'],
});

socket.on('connect', () => {
  console.log('Connected to Placet');
  socket.emit('subscribe:channel', CHANNEL_ID);

  // 2. Send a deployment approval request
  sendApproval();
});

// 3. Listen for the review response
socket.on('review:responded', (data) => {
  const { selectedOption, comment } = data.review.response;
  console.log(`Decision: ${selectedOption}`);
  if (comment) console.log(`Comment: ${comment}`);

  if (selectedOption === 'approve') {
    console.log('Deploying...');
    // Trigger deployment
  } else {
    console.log('Deployment cancelled');
  }
});

socket.on('review:expired', (data) => {
  console.log(`Review ${data.messageId} expired — no response received`);
});

async function sendApproval() {
  const res = await fetch(`${PLACET_URL}/api/v1/messages`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      channelId: CHANNEL_ID,
      text: '### Deploy v2.1.0 to production?',
      review: {
        type: 'approval',
        payload: {
          options: [
            { id: 'approve', label: 'Approve', style: 'primary' },
            { id: 'reject', label: 'Reject', style: 'danger' },
          ],
          allowComment: true,
        },
      },
    }),
  });
  const message = await res.json();
  console.log(`Approval sent: ${message.id}`);
}
```

***

## Reconnection

Socket.IO handles reconnection automatically. Placet uses the default Socket.IO reconnection settings:

* Reconnects automatically on disconnect
* Exponential backoff (1s, 2s, 4s, ...)
* Re-authenticates on reconnect

<Tip>
  After reconnecting, re-subscribe to your channels — Socket.IO does not persist subscriptions
  across reconnects. Listen for the `connect` event and emit `subscribe:channel` again.
</Tip>


# Introduction
Source: https://docs.placet.io/index

The inbox where AI agents meet humans.

## What is Placet?

Placet is a **self-hostable, plugin-driven platform for Human-in-the-Loop workflows**. It provides a purpose-built inbox where AI agents, automation workflows, and no-code tools collaborate with humans through structured interactions.

Unlike chat apps with agent integrations bolted on, Placet is designed from the ground up for the agent-human interaction loop.

<Frame>
  <img alt="Placet chat example" />
</Frame>

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get up and running in minutes with Docker Compose
  </Card>

  <Card title="Self-Hosting" icon="server" href="/self-hosting">
    Deploy Placet on your own infrastructure
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the REST API for agent integration
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/plugins/overview">
    Extend Placet with custom message types
  </Card>
</CardGroup>

## Why Placet?

AI agents and automations are getting more capable every day, but they still need humans in the loop: approvals, reviews, feedback, complex decisions.

Most teams wire this through Slack, Teams, or email, tools designed for human-to-human chat, not human-to-agent collaboration.

**Placet is different:**

<AccordionGroup>
  <Accordion title="Purpose-built for Human-in-the-Loop">
    The entire platform is designed around the agent-human interaction loop. Not a chat app with
    agent integrations bolted on. Works with AI agents, CI/CD pipelines, no-code tools, and any
    HTTP-capable automation.
  </Accordion>

  <Accordion title="5 built-in review types">
    Approval buttons, single/multi selection, dynamic forms, free-text input, and freeform JSON.
    Each review type renders natively in the chat and supports expiry, webhooks, and long-polling.
  </Accordion>

  <Accordion title="Integrated file storage with inline preview">
    Upload files via API, attach them to messages, and preview them directly in the chat. Supports
    images, PDFs, video, audio, Office documents, spreadsheets, code files, and more. Includes
    canvas annotation tools for marking up images.
  </Accordion>

  <Accordion title="Agent status dashboard">
    Agents report their status (active, busy, error, offline) via a heartbeat endpoint. The frontend
    shows a live status overview with uptime, message stats, and status history.
  </Accordion>

  <Accordion title="Plugin system for unlimited flexibility">
    Two files (`plugin.json` + `render.html`) = a custom message type. Build CRM cards, diagram
    renderers, diff viewers, or whatever your workflow needs.
  </Accordion>

  <Accordion title="Multiple communication patterns">
    WebSocket for real-time, webhooks for async delivery, long-polling for synchronous agents. Your
    agent connects however it wants.
  </Accordion>

  <Accordion title="Self-hostable, no vendor lock-in">
    One `docker compose up` and you're running. No cloud dependency, no LLM provider coupling.
  </Accordion>
</AccordionGroup>


# cURL
Source: https://docs.placet.io/integrations/curl

Quick Placet integration for shell scripts and cron jobs.

## Setup

```bash theme={null}
export PLACET_URL="https://your-placet-instance.com"
export PLACET_API_KEY="hp_your-api-key"
export PLACET_CHANNEL="your-agent-id"
```

## Send a Message

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/messages" \
  -H "x-api-key: $PLACET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "'"$PLACET_CHANNEL"'",
    "text": "Backup completed at '"$(date)"'",
    "status": "success"
  }'
```

## Upload a File

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/files/store" \
  -H "x-api-key: $PLACET_API_KEY" \
  -F "file=@report.pdf" \
  -F "channelId=$PLACET_CHANNEL"
```

## Report Agent Status

```bash theme={null}
curl -X POST "$PLACET_URL/api/v1/status/ping" \
  -H "x-api-key: $PLACET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "'"$PLACET_CHANNEL"'", "status": "active"}'
```

## Request Approval and Wait

```bash theme={null}
# Send approval request
RESPONSE=$(curl -s -X POST "$PLACET_URL/api/v1/messages" \
  -H "x-api-key: $PLACET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "'"$PLACET_CHANNEL"'",
    "text": "Run database migration?",
    "status": "warning",
    "review": {
      "type": "approval",
      "payload": {
        "options": [
          {"id": "approve", "label": "Approve", "style": "primary"},
          {"id": "reject", "label": "Reject", "style": "danger"}
        ]
      }
    }
  }')

MESSAGE_ID=$(echo "$RESPONSE" | jq -r '.id')

# Wait for human response (long-poll, 30s timeout)
RESULT=$(curl -s "$PLACET_URL/api/v1/reviews/$MESSAGE_ID/wait?channel=$PLACET_CHANNEL&timeout=30000" \
  -H "x-api-key: $PLACET_API_KEY")

STATUS=$(echo "$RESULT" | jq -r '.status')
SELECTED=$(echo "$RESULT" | jq -r '.message.review.response.selectedOption')

if [ "$STATUS" = "completed" ] && [ "$SELECTED" = "approve" ]; then
  echo "Approved, running migration..."
else
  echo "Rejected or timed out, aborting."
  exit 1
fi
```

## Download a File

```bash theme={null}
ATTACHMENT_ID="your-attachment-id"
curl -o downloaded.pdf \
  -H "x-api-key: $PLACET_API_KEY" \
  "$PLACET_URL/api/v1/files/$ATTACHMENT_ID/download"
```


# LangChain
Source: https://docs.placet.io/integrations/langchain

Build an AI chat agent with human-in-the-loop using LangChain and Placet.

<Info>
  Runnable example in
  [`examples/langchain/`](https://github.com/placet-io/placet/tree/main/examples/langchain), a
  GPT-powered chat agent with approvals, selections, and forms via WebSocket.
</Info>

## Overview

Placet integrates with [LangChain](https://python.langchain.com/) as a **human-in-the-loop** tool.
Your LangChain agent receives messages in real-time via WebSocket and can send replies, request
approvals, present selections, or ask the user to fill in forms, all rendered natively in the
Placet UI.

The agent uses four tools:

| Tool            | Description                                   | Blocking |
| --------------- | --------------------------------------------- | -------- |
| `send_message`  | Send a one-way message (status update, reply) | No       |
| `ask_approval`  | Approve / Reject buttons                      | Yes      |
| `ask_selection` | Pick one option from a list                   | Yes      |
| `ask_form`      | Fill in a multi-field form                    | Yes      |

Blocking tools wait for the user's response via a WebSocket `review:responded` event (up to 5
minutes).

## Message Helper

All tools post messages through the same helper:

```python theme={null}
import requests

PLACET_URL = "https://your-placet-instance.com"
API_KEY = "hp_your-api-key"
CHANNEL_ID = "your-agent-id"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}


def post_message(**kwargs):
    resp = requests.post(
        f"{PLACET_URL}/api/v1/messages",
        headers=headers,
        json={"channelId": CHANNEL_ID, **kwargs},
    )
    resp.raise_for_status()
    return resp.json()
```

## Tools

### send\_message

Fire-and-forget: sends a message and returns immediately:

```python theme={null}
from langchain_core.tools import tool


@tool
def send_message(text: str, status: str = "info") -> str:
    """Send a plain message to the user. No response expected.

    Args:
        text: Markdown-formatted message text.
        status: One of 'info', 'success', 'warning', 'error'.
    """
    post_message(text=text, status=status)
    return "Message sent."
```

### ask\_approval

Shows Approve / Reject buttons. Blocks until the user clicks one:

```python theme={null}
@tool
def ask_approval(question: str) -> str:
    """Present the user with an Approve / Reject decision.
    Blocks until the user clicks a button (up to 5 minutes).

    Returns: 'approve', 'reject', or 'timeout'.
    """
    msg = post_message(
        text=question,
        status="warning",
        review={
            "type": "approval",
            "payload": {
                "options": [
                    {"id": "approve", "label": "Approve", "style": "primary"},
                    {"id": "reject", "label": "Reject", "style": "danger"},
                ],
            },
        },
    )
    data = wait_review(msg["id"])
    if data:
        return data["review"]["response"]["selectedOption"]
    return "timeout"
```

### ask\_selection

Presents a list of options for the user to pick from:

```python theme={null}
@tool
def ask_selection(question: str, options: str) -> str:
    """Present multiple options for the user to choose from.

    Args:
        question: The question to display above the options.
        options: Comma-separated list, e.g. "Option A, Option B, Option C"

    Returns: The id of the selected option, or 'timeout'.
    """
    items = [
        {"id": o.strip().lower().replace(" ", "_"), "label": o.strip()}
        for o in options.split(",")
    ]
    msg = post_message(
        text=question,
        status="info",
        review={"type": "selection", "payload": {"mode": "single", "items": items}},
    )
    data = wait_review(msg["id"])
    if data:
        ids = data["review"]["response"].get("selectedIds", [])
        return ids[0] if ids else "unknown"
    return "timeout"
```

### ask\_form

Shows a form with input fields:

```python theme={null}
@tool
def ask_form(question: str, fields: str) -> str:
    """Ask the user to fill in a form with one or more fields.

    Args:
        question: Instruction text displayed above the form.
        fields: Comma-separated field names, e.g. "Name, Email, Environment"

    Returns: The filled values as "field: value" pairs, or 'timeout'.
    """
    field_list = [
        {"name": f.strip().lower().replace(" ", "_"), "type": "text",
         "label": f.strip(), "required": True}
        for f in fields.split(",")
    ]
    msg = post_message(
        text=question,
        status="info",
        review={"type": "form", "payload": {"fields": field_list, "submitLabel": "Submit"}},
    )
    data = wait_review(msg["id"])
    if data:
        resp = data["review"]["response"]
        return ", ".join(f"{k}: {v}" for k, v in resp.items() if k != "selectedOption")
    return "timeout"
```

## Waiting for Reviews via WebSocket

The blocking tools above call `wait_review()`, which uses a `threading.Event` that gets set when
the WebSocket delivers the `review:responded` event for the corresponding message:

```python theme={null}
import threading

_review_events = {}   # message_id → threading.Event
_review_results = {}  # message_id → response data


def wait_review(message_id, timeout=300):
    """Block until the WebSocket delivers review:responded for this message."""
    event = threading.Event()
    _review_events[message_id] = event
    event.wait(timeout=timeout)
    _review_events.pop(message_id, None)
    return _review_results.pop(message_id, None)
```

The WebSocket handler fills `_review_results` and signals the event:

```python theme={null}
@sio.on("review:responded", namespace="/ws")
def on_review(data):
    msg_id = data.get("id")
    if msg_id and msg_id in _review_events:
        _review_results[msg_id] = data
        _review_events[msg_id].set()
```

This avoids HTTP long-polling entirely. Reviews resolve in real-time over the same
WebSocket connection.

## Agent

Wire the tools into a ChatGPT agent with explicit instructions to always use tools
(the agent's plain-text output is not visible to the user):

```python theme={null}
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

llm = ChatOpenAI(model="gpt-5.2-instant")

prompt = ChatPromptTemplate.from_messages([
    ("system",
     "You are a helpful AI assistant communicating through Placet.\n\n"
     "IMPORTANT: You MUST use the provided tools to communicate. "
     "NEVER reply with plain text — the user cannot see it.\n\n"
     "Guidelines:\n"
     "- Follow-up questions with fixed choices → use ask_selection.\n"
     "- Need free-text input → use ask_form.\n"
     "- Yes/no or go/no-go decision → use ask_approval.\n"
     "- Everything else (replies, explanations) → use send_message.\n"
     "- If any tool returns 'timeout', do NOT retry. "
     "Send a message that you're stopping because the user didn't respond in time."),
    MessagesPlaceholder("chat_history"),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

tools = [send_message, ask_approval, ask_selection, ask_form]
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True,
                         handle_parsing_errors=True)
```

## WebSocket Connection

The agent connects via Socket.IO, subscribes to its channel, and dispatches incoming
user messages to the LangChain executor:

```python theme={null}
import socketio
from langchain_core.messages import HumanMessage

sio = socketio.Client(reconnection=False)

chat_history = []


def handle_user_message(text):
    """Process a user message through the LangChain agent."""
    chat_history.append(HumanMessage(content=text))
    executor.invoke({"input": text, "chat_history": chat_history})


seen = set()


@sio.on("message:created", namespace="/ws")
def on_message(data):
    if data.get("id") in seen or data.get("senderType") != "user":
        return
    seen.add(data["id"])
    text = (data.get("text") or "").strip()
    if text:
        handle_user_message(text)
```

### WebSocket Authentication

Placet WebSocket supports API key authentication for agents. Pass your API key
directly in the connection's `auth` object:

```python theme={null}
sio = socketio.Client(reconnection=False)
sio.connect(PLACET_URL, namespaces=["/ws"],
            auth={"apiKey": API_KEY}, transports=["websocket"])
sio.wait()
```


# Integrations
Source: https://docs.placet.io/integrations/overview

Connect your AI agents and automations to Placet.

Placet provides a simple REST API that any HTTP client can use. Connect AI agents, automation workflows, CI/CD pipelines, or no-code tools. Below are examples for popular frameworks and libraries.

<CardGroup>
  <Card title="Python" icon="python" href="/integrations/python">
    Direct integration using `requests` or `httpx`
  </Card>

  <Card title="LangChain" icon="link-horizontal" href="/integrations/langchain">
    Use Placet as a human-in-the-loop tool in LangChain agents
  </Card>

  <Card title="TypeScript / Node.js" icon="js" href="/integrations/typescript">
    Integrate with any Node.js runtime or framework
  </Card>

  <Card title="cURL / Shell" icon="terminal" href="/integrations/curl">
    Quick integration for shell scripts and cron jobs
  </Card>
</CardGroup>

## Authentication

All integrations use the same authentication method: an **API key** passed as a Bearer token.

```bash theme={null}
x-api-key: hp_your-api-key
```

Create API keys in **Settings → API Keys** in the Placet web UI.

## Base URL

All agent-facing endpoints live under `/api/v1/`:

```
https://your-placet-instance.com/api/v1/messages
https://your-placet-instance.com/api/v1/reviews
https://your-placet-instance.com/api/v1/files
https://your-placet-instance.com/api/v1/status
```


# Python
Source: https://docs.placet.io/integrations/python

Integrate Placet with Python using requests.

<Info>
  Runnable example in
  [`examples/python/`](https://github.com/placet-io/placet/tree/main/examples/python) covers upload,
  messaging, approval, and download in a single script.
</Info>

## Send a Message

```python theme={null}
import requests

PLACET_URL = "https://your-placet-instance.com"
API_KEY = "hp_your-api-key"
CHANNEL_ID = "your-agent-id"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}

resp = requests.post(
    f"{PLACET_URL}/api/v1/messages",
    headers=headers,
    json={
        "channelId": CHANNEL_ID,
        "text": "Deployment completed successfully.",
        "status": "success",
    },
)
msg = resp.json()
print(f"Message sent: {msg['id']}")
```

## Upload a File

Upload a file without creating a message (can be attached later):

```python theme={null}
with open("report.pdf", "rb") as f:
    resp = requests.post(
        f"{PLACET_URL}/api/v1/files/store",
        headers={"x-api-key": API_KEY},
        files={"file": ("report.pdf", f, "application/pdf")},
        data={"channelId": CHANNEL_ID},
    )
attachment = resp.json()
print(f"Uploaded: {attachment['filename']} (id: {attachment['id']})")
```

## Send Message with File & Approval

Attach a previously uploaded file and request human approval:

```python theme={null}
resp = requests.post(
    f"{PLACET_URL}/api/v1/messages",
    headers=headers,
    json={
        "channelId": CHANNEL_ID,
        "text": "Please review the attached report.",
        "status": "warning",
        "attachmentIds": [attachment["id"]],
        "review": {
            "type": "approval",
            "payload": {
                "options": [
                    {"id": "approve", "label": "Approve", "style": "primary"},
                    {"id": "reject", "label": "Reject", "style": "danger"},
                ],
            },
        },
    },
)
approval_msg = resp.json()

# Long-poll for the human's response (max 30s)
result = requests.get(
    f"{PLACET_URL}/api/v1/reviews/{approval_msg['id']}/wait",
    headers=headers,
    params={"channel": CHANNEL_ID, "timeout": "30000"},
)
review = result.json()

if review["status"] == "completed":
    chosen = review["message"]["review"]["response"]["selectedOption"]
    print(f"Human chose: {chosen}")
```

## Download a File

```python theme={null}
resp = requests.get(
    f"{PLACET_URL}/api/v1/files/{attachment['id']}/download",
    headers={"x-api-key": API_KEY},
)
with open("downloaded.pdf", "wb") as f:
    f.write(resp.content)
```

## Report Agent Status

```python theme={null}
requests.post(
    f"{PLACET_URL}/api/v1/status/ping",
    headers=headers,
    json={"agentId": CHANNEL_ID, "status": "active"},
)
```


# TypeScript / Node.js
Source: https://docs.placet.io/integrations/typescript

Integrate Placet from TypeScript or Node.js applications.

<Info>
  Runnable example in
  [`examples/typescript/`](https://github.com/placet-io/placet/tree/main/examples/typescript) covers
  upload, messaging, approval, and download in a single script.
</Info>

## Send a Message

Use the built-in `fetch` API (Node.js 18+):

```typescript theme={null}
const PLACET_URL = 'https://your-placet-instance.com';
const API_KEY = 'hp_your-api-key';
const CHANNEL_ID = 'your-agent-id';

const headers = {
  'x-api-key': API_KEY,
  'Content-Type': 'application/json',
};

const resp = await fetch(`${PLACET_URL}/api/v1/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    channelId: CHANNEL_ID,
    text: 'Build completed successfully.',
    status: 'success',
  }),
});

const msg = await resp.json();
console.log(`Message sent: ${msg.id}`);
```

## Upload a File

Upload a file without creating a message (can be attached later):

```typescript theme={null}
const form = new FormData();
form.append('file', new Blob([fileBuffer], { type: 'application/pdf' }), 'report.pdf');
form.append('channelId', CHANNEL_ID);

const uploadResp = await fetch(`${PLACET_URL}/api/v1/files/store`, {
  method: 'POST',
  headers: { 'x-api-key': API_KEY },
  body: form,
});

const attachment = await uploadResp.json();
console.log(`Uploaded: ${attachment.filename} (id: ${attachment.id})`);
```

## Send Message with File & Approval

Attach a previously uploaded file and request human approval:

```typescript theme={null}
const approvalResp = await fetch(`${PLACET_URL}/api/v1/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    channelId: CHANNEL_ID,
    text: 'Please review the attached report.',
    status: 'warning',
    attachmentIds: [attachment.id],
    review: {
      type: 'approval',
      payload: {
        options: [
          { id: 'approve', label: 'Approve', style: 'primary' },
          { id: 'reject', label: 'Reject', style: 'danger' },
        ],
      },
    },
  }),
});

const approvalMsg = await approvalResp.json();

// Long-poll for the review response (up to 30s)
const reviewResp = await fetch(
  `${PLACET_URL}/api/v1/reviews/${approvalMsg.id}/wait?channel=${CHANNEL_ID}&timeout=30000`,
  { headers },
);
const review = await reviewResp.json();

if (review.status === 'completed') {
  console.log(`Decision: ${review.message.review.response.selectedOption}`);
}
```

## Download a File

```typescript theme={null}
const dlResp = await fetch(`${PLACET_URL}/api/v1/files/${attachment.id}/download`, {
  headers: { 'x-api-key': API_KEY },
});

const buffer = await dlResp.arrayBuffer();
// Save or process the file buffer
```

## Report Agent Status

```typescript theme={null}
await fetch(`${PLACET_URL}/api/v1/status/ping`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ agentId: CHANNEL_ID, status: 'active' }),
});
```


# Bridge API
Source: https://docs.placet.io/plugins/bridge-api

The Placet JavaScript API available inside plugin iframes.

## Overview

Every plugin iframe gets a `Placet` global object, the **Bridge API**. It provides access to message data, environment variables, file handling, HTTP requests, and UI controls.

## Properties

| Property             | Type                      | Description                                                    |
| -------------------- | ------------------------- | -------------------------------------------------------------- |
| `Placet.data`        | `Record<string, unknown>` | Plugin input data from the message metadata                    |
| `Placet.env`         | `Record<string, string>`  | Environment variables configured in Settings                   |
| `Placet.attachments` | `AttachmentInfo[]`        | Array of attached files (`{ id, filename, mimeType, size }`)   |
| `Placet.message`     | `MessageContext`          | Message context (`id`, `channelId`, `senderType`, `createdAt`) |
| `Placet.theme`       | `'light' \| 'dark'`       | Current theme                                                  |
| `Placet.review`      | `ReviewContext \| null`   | Review context (`{ type, status, payload }`) or `null`         |
| `Placet.isPreview`   | `boolean`                 | `true` when rendered in the full-screen preview modal          |

## Methods

### `Placet.resize()`

Resizes the iframe to fit its content. Call this after rendering.

```javascript theme={null}
document.addEventListener('DOMContentLoaded', function () {
  // ... render content ...
  Placet.resize();
});
```

### `Placet.fetch(url, options)`

Makes an HTTP request **proxied through the backend server**. Respects the `maxHttpDomains` permission.

```javascript theme={null}
Placet.fetch('https://api.example.com/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: Placet.env.API_KEY }),
}).then(function (res) {
  var json = JSON.parse(res.body);
});
```

<Warning>
  HTTP requests are **server-side proxied** through the backend. The backend enforces domain
  allowlists, permissions, and timeout limits (30s).
</Warning>

### `Placet.getFile(attachmentId)`

Returns file content as a base64 data URL.

```javascript theme={null}
Placet.getFile(Placet.attachments[0].id).then(function (file) {
  // file = { ok: true, data: "data:image/png;base64,...", mimeType: "image/png", filename: "photo.png" }
});
```

### `Placet.getFileUrl(attachmentId)`

Returns a download URL for the file.

```javascript theme={null}
Placet.getFileUrl(Placet.attachments[0].id).then(function (result) {
  // result = { ok: true, url: "/api/files/.../download" }
});
```

### `Placet.toast(message, variant)`

Shows a toast notification in the parent UI.

```javascript theme={null}
Placet.toast('Done!', 'success'); // success, error, warning, info
```

### `Placet.emit(action, data)`

Emits a custom action to the parent application.

```javascript theme={null}
Placet.emit('respond', { approved: true });
```

### `Placet.respond(response)`

Submits a review response. This is a **one-time operation** per pending review.

```javascript theme={null}
Placet.respond({ approved: true })
  .then(function (result) {
    Placet.toast('Response submitted!', 'success');
  })
  .catch(function (err) {
    // "Already responded to this review" or "No pending review"
  });
```

### `Placet.on(event, handler)`

Listens for events from the parent application.

```javascript theme={null}
Placet.on('theme-changed', function (data) {
  document.body.classList.toggle('dark', data.theme === 'dark');
});
```

## Complete Example

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <style>
      body {
        font-family: sans-serif;
        padding: 16px;
        background: transparent;
      }
      body.dark {
        color: #e5e5e4;
      }
      .card {
        border: 1px solid #e0e0e0;
        border-radius: 8px;
        padding: 16px;
      }
      body.dark .card {
        border-color: #404040;
      }
    </style>
  </head>
  <body>
    <div class="card">
      <h3 id="title"></h3>
      <p id="content"></p>
      <button id="action">Submit</button>
    </div>
    <script>
      document.addEventListener('DOMContentLoaded', function () {
        if (Placet.theme === 'dark') document.body.classList.add('dark');

        document.getElementById('title').textContent = Placet.data.title;
        document.getElementById('content').textContent = Placet.data.description;

        document.getElementById('action').addEventListener('click', function () {
          Placet.fetch(Placet.env.WEBHOOK_URL, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(Placet.data),
          }).then(function () {
            Placet.toast('Submitted!', 'success');
          });
        });

        Placet.resize();
      });
    </script>
  </body>
</html>
```


# Creating Plugins
Source: https://docs.placet.io/plugins/creating-plugins

Step-by-step guide to building a Placet plugin.

## Create a Plugin

<Steps>
  <Step title="Create the directory">
    ```bash theme={null}
    mkdir packages/plugins/my-plugin
    ```
  </Step>

  <Step title="Define plugin.json">
    ```json theme={null}
    {
      "name": "my-plugin",
      "displayName": "My Plugin",
      "description": "What this plugin does",
      "version": "1.0.0",
      "author": "Your Name",
      "icon": "./icon.svg",
      "inputSchema": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string" }
        },
        "required": ["title"]
      },
      "permissions": {
        "httpRequests": true,
        "maxHttpDomains": ["api.example.com"]
      },
      "env": [
        {
          "key": "API_KEY",
          "label": "API Key",
          "required": true,
          "secret": true,
          "description": "Your API key for the external service."
        }
      ]
    }
    ```
  </Step>

  <Step title="Create render.html">
    ```html theme={null}
    <!DOCTYPE html>
    <html>
      <head>
        <style>
          body {
            font-family: sans-serif;
            padding: 16px;
            color: #1a1a19;
            background: transparent;
          }
          body.dark { color: #e5e5e4; }
        </style>
      </head>
      <body>
        <div id="app">
          <h3 id="title"></h3>
          <p id="info"></p>
        </div>
        <script>
          document.addEventListener('DOMContentLoaded', function () {
            if (Placet.theme === 'dark') document.body.classList.add('dark');
            document.getElementById('title').textContent = Placet.data.title;
            document.getElementById('info').textContent = Placet.data.url || 'No URL';
            Placet.resize();
          });
        </script>
      </body>
    </html>
    ```
  </Step>

  <Step title="Optionally add an icon">
    Place an `icon.svg` (or `.png`) in the plugin directory and reference it in `plugin.json`:

    ```json theme={null}
    { "icon": "./icon.svg" }
    ```
  </Step>

  <Step title="Restart the backend">
    ```bash theme={null}
    make stop && make start
    ```

    The plugin is automatically discovered and available.
  </Step>

  <Step title="Configure env values">
    Go to **Settings → Plugins**, expand your plugin, fill in the environment variables, and click **Save**.
  </Step>
</Steps>

## Manifest Reference

### Top-Level Fields

| Field                        | Required | Description                                           |
| ---------------------------- | -------- | ----------------------------------------------------- |
| `name`                       | Yes      | Unique plugin identifier (kebab-case)                 |
| `displayName`                | Yes      | Human-readable name                                   |
| `version`                    | Yes      | Semver version                                        |
| `description`                | No       | Short description                                     |
| `author`                     | No       | Author name                                           |
| `icon`                       | No       | Relative file path (`./icon.svg`) or Lucide icon name |
| `inputSchema`                | No       | JSON Schema for the plugin's input data               |
| `permissions.httpRequests`   | No       | Whether the plugin can make HTTP requests             |
| `permissions.maxHttpDomains` | No       | Allowed domains for HTTP requests (`["*"]` = any)     |
| `env`                        | No       | Array of environment variable definitions             |

### Environment Variables

Each entry in the `env` array:

| Field         | Required | Description                              |
| ------------- | -------- | ---------------------------------------- |
| `key`         | Yes      | Variable name (e.g. `API_KEY`)           |
| `label`       | Yes      | Human-readable label for the Settings UI |
| `required`    | No       | Whether this variable must be set        |
| `default`     | No       | Default value                            |
| `secret`      | No       | If `true`, rendered as a password field  |
| `description` | No       | Help text shown below the input          |

<Info>
  Env values are configured per-plugin in **Settings → Plugins** and stored in the database,
  version-coupled. Plugins access them at runtime via `Placet.env`.
</Info>

## Validate a Plugin

Use the included validation script:

```bash theme={null}
npx ts-node scripts/validate-plugin.ts packages/plugins/my-plugin
```


# Plugin Overview
Source: https://docs.placet.io/plugins/overview

Placet's directory-based plugin system for custom message types.

## What is a Plugin?

A **Plugin** defines a **custom message type**. It controls:

1. **What data a message carries** via an input schema (what fields the agent sends)
2. **How that message renders** as HTML/CSS/JS in a sandboxed iframe
3. **What logic runs client-side** such as HTTP requests, data fetching, user interactions
4. **What configuration it needs** like environment variables (API keys, URLs, etc.)

A Plugin does **NOT** control:

* Whether a message requires a review/response (that's the agent's decision per message)
* The approve/reject buttons (that's the review system, orthogonal to plugins)
* Authentication or routing (that's the platform)

### Plugin vs Review

These are **two independent axes** on a message:

```
Message
  ├── metadata.plugin: "form-submit"    ← HOW the message renders (Plugin)
  ├── review: { ... }                   ← WHETHER user input is needed (Review)
  │     ├── type: "approval"            ← WHAT kind of input
  │     └── payload: { options: [...] }
  └── metadata: { name: "John", ... }   ← Plugin-specific data
```

## Plugin Structure

Each plugin lives in `packages/plugins/<name>/` and consists of:

* [**plugin.json**](/plugins/creating-plugins#manifest-reference): Manifest with metadata, input schema, env variables, and permissions
* [**render.html**](/plugins/creating-plugins#create-renderhtml): HTML + CSS + JS rendered inside a sandboxed iframe
* **icon.svg/.png** (optional): Icon shown in the Settings UI

<Note>
  Plugins are discovered automatically on backend startup. No build step required, just add the
  directory and restart.
</Note>

## Built-in Plugins

Placet ships with two example plugins you can use as reference:

| Plugin            | Description                                                                      | Source                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Form Submit**   | Renders a form from structured data and submits it to a configurable webhook URL | [`packages/plugins/form-submit/`](https://github.com/placet-io/placet/tree/main/packages/plugins/form-submit)     |
| **Kroki Diagram** | Renders diagrams (Mermaid, PlantUML, D2, etc.) via a Kroki server                | [`packages/plugins/kroki-diagram/`](https://github.com/placet-io/placet/tree/main/packages/plugins/kroki-diagram) |

## Data Flow

```mermaid theme={null}
sequenceDiagram
    participant Agent as Agent
    participant API as Placet API
    participant UI as Web App
    participant Plugin as Plugin iframe

    Agent->>API: POST /api/v1/messages<br/>metadata: { plugin: "form-submit", ... }
    API->>UI: WebSocket: message:created
    UI->>Plugin: Load render.html in sandboxed iframe
    Plugin->>Plugin: Placet.data, Placet.env available
    Plugin->>API: Placet.fetch() (server-side proxied)
```

## Security Model

| Concern              | Solution                                                                     |
| -------------------- | ---------------------------------------------------------------------------- |
| **DOM access**       | `sandbox="allow-scripts"` only, no `allow-same-origin`, no parent DOM access |
| **Cookies/Storage**  | Sandboxed iframe has no access to parent cookies or localStorage             |
| **HTTP requests**    | Server-side proxied; domain allowlist enforced via `maxHttpDomains`          |
| **Script injection** | Plugin HTML is static per-plugin, loaded from disk                           |
| **Env values**       | Stored in DB, injected at render time; secrets not exposed in manifest       |

## Available in Plugins

Inside the iframe, plugins access the [Bridge API](/plugins/bridge-api) via the `Placet` global:

| Property             | Type                      | Description                                                    |
| -------------------- | ------------------------- | -------------------------------------------------------------- |
| `Placet.data`        | `Record<string, unknown>` | Plugin input data from the message metadata                    |
| `Placet.env`         | `Record<string, string>`  | Environment variables configured in Settings                   |
| `Placet.attachments` | `AttachmentInfo[]`        | Array of attached files (`{ id, filename, mimeType, size }`)   |
| `Placet.message`     | `MessageContext`          | Message context (`id`, `channelId`, `senderType`, `createdAt`) |
| `Placet.theme`       | `'light' \| 'dark'`       | Current theme                                                  |
| `Placet.review`      | `ReviewContext \| null`   | Review context (`{ type, status, payload }`) or `null`         |
| `Placet.isPreview`   | `boolean`                 | `true` when rendered in the full-screen preview modal          |

Methods: `Placet.fetch()`, `Placet.getFile()`, `Placet.getFileUrl()`, `Placet.toast()`, `Placet.respond()`, `Placet.resize()`, `Placet.emit()`, `Placet.on()`. See the full [Bridge API reference](/plugins/bridge-api) for details.


# Quickstart
Source: https://docs.placet.io/quickstart

Get Placet running locally in under 5 minutes.

## Prerequisites

* **Git**
* **Docker & Docker Compose**

## Setup

<Steps>
  <Step title="Clone the repository">
    `git clone https://github.com/placet-io/placet.git && cd placet`
  </Step>

  <Step title="Configure environment">
    `cp .env.example .env` Edit `.env` to set your desired admin email, password, and other
    settings.
  </Step>

  <Step title="Start everything">
    `make setup` This installs dependencies, builds packages, starts all Docker services
    (Postgres, MinIO, Backend, Frontend), runs migrations, and creates the initial user.
  </Step>
</Steps>

## Access the services

Once setup completes, the following services are available:

| Service           | URL                              |
| ----------------- | -------------------------------- |
| **Frontend**      | `http://localhost:3000`          |
| **Backend API**   | `http://localhost:3001`          |
| **Swagger Docs**  | `http://localhost:3001/api/docs` |
| **MinIO Console** | `http://localhost:9001`          |

**Default login:** `admin@placet.local` / `changeme` (configurable in `.env`)

## Send your first agent message

<Steps>
  <Step title="Create an API key">
    Go to **Settings → API Keys** and create a new key.
  </Step>

  <Step title="Create an agent">
    Click **+ New Agent** in the inbox sidebar to create a new agent.
  </Step>

  <Step title="Send a message">
    ```bash theme={null}
    curl -X POST http://localhost:3001/api/v1/messages \
      -H "x-api-key: hp_your-key-here" \
      -H "Content-Type: application/json" \
      -d '{"channelId": "your-agent-id", "text": "Hello from my agent!", "status": "success"}'
    ```
  </Step>

  <Step title="View the message">
    Open the agent's chat in the frontend and your message appears in real-time.
  </Step>
</Steps>

## Request human approval

```bash theme={null}
curl -X POST http://localhost:3001/api/v1/messages \
  -H "x-api-key: hp_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "your-agent-id",
    "text": "Deploy v2.1 to production?",
    "review": {
      "type": "approval",
      "payload": {
        "options": [
          { "id": "approve", "label": "Approve", "style": "primary" },
          { "id": "reject", "label": "Reject", "style": "danger" }
        ]
      }
    }
  }'
```

The message appears with approval buttons. When the user clicks one, you receive the response via webhook or by polling the API.

## Next steps

<CardGroup>
  <Card title="How It Works" icon="sitemap" href="/concepts/how-it-works">
    Understand how agents and humans interact in Placet
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/plugins/overview">
    Build custom message types with the plugin system
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full REST API documentation
  </Card>

  <Card title="Self-Hosting" icon="server" href="/self-hosting">
    Deploy Placet on your own infrastructure
  </Card>
</CardGroup>


# Self-Hosting
Source: https://docs.placet.io/self-hosting

Deploy Placet on your own infrastructure with Docker Compose.

## Requirements

* Docker & Docker Compose v2
* At least 2 GB RAM

## Docker Compose Deployment

Placet ships with a production-ready `docker-compose.yml` that includes all required services.

<Steps>
  <Step title="Clone and configure">
    `git clone https://github.com/placet-io/placet.git && cd placet && cp .env.example .env`
    Edit `.env` with your production settings: - Set strong passwords for `POSTGRES_PASSWORD`,
    `MINIO_ROOT_PASSWORD` - Set `JWT_SECRET` to a secure random string - Configure
    `INITIAL_USER_EMAIL` and `INITIAL_USER_PASSWORD` - Set `NEXT_PUBLIC_WS_URL` and
    `NEXT_PUBLIC_APP_URL` to your domain
  </Step>

  <Step title="Start services">`docker compose up -d`</Step>
  <Step title="Run migrations">`docker compose exec backend npx prisma migrate deploy`</Step>
</Steps>

## Services

| Service      | Port | Description                  |
| ------------ | ---- | ---------------------------- |
| **Frontend** | 3000 | Next.js web application      |
| **Backend**  | 3001 | REST API server              |
| **Postgres** | 5432 | PostgreSQL database          |
| **MinIO**    | 9000 | S3-compatible object storage |

## Reverse Proxy

A Traefik configuration is included in `docker-compose.traefik.yml` for production deployments with TLS/SSL.

```
docker compose -f docker-compose.yml -f docker-compose.traefik.yml up -d
```

## Environment Variables

<Note>
  See `.env.example` in the repository for a complete list of all available environment variables
  with descriptions.
</Note>

### Core Settings

| Variable                | Description                    | Default                 |
| ----------------------- | ------------------------------ | ----------------------- |
| `DATABASE_URL`          | PostgreSQL connection string   | —                       |
| `JWT_SECRET`            | Secret for JWT token signing   | —                       |
| `INITIAL_USER_EMAIL`    | Initial admin user email       | `admin@placet.local`    |
| `INITIAL_USER_PASSWORD` | Initial admin user password    | `changeme`              |
| `NEXT_PUBLIC_WS_URL`    | WebSocket URL for the frontend | `http://localhost:3001` |
| `NEXT_PUBLIC_APP_URL`   | Public URL of the frontend     | `http://localhost:3000` |

### File Storage (MinIO/S3)

| Variable           | Description   | Default     |
| ------------------ | ------------- | ----------- |
| `MINIO_ENDPOINT`   | MinIO/S3 host | `localhost` |
| `MINIO_PORT`       | MinIO/S3 port | `9000`      |
| `MINIO_ACCESS_KEY` | Access key    | —           |
| `MINIO_SECRET_KEY` | Secret key    | —           |
| `MINIO_BUCKET`     | Bucket name   | `placet`    |