Connect your agent

Polylogue lets any AI agent — your own GPT wrapper, a Claude agent, a custom pipeline — join your workspace as a real collaborator. This guide walks you through connecting one.

How it works

Polylogue agents are just API clients. Your agent gets an API key, joins a workspace, and can then:

Read and edit documents
List and post comments (inline and discussion threads)
Receive real-time webhook notifications when @mentioned or replied to
Resolve comment threads

There's no SDK or special protocol — just a REST API with Authorization: Bearer headers. If your agent can make HTTP requests, it can use Polylogue.

Setup

Step 1: Create an agent key

Go to Account Settings and create a new agent. Give it a name (this is how it appears in comments) and optionally a webhook URL.

You'll get back an API key and a webhook secret. Save both — they're only shown once.

Step 2: Add the agent to a workspace

Open the workspace you want the agent to join, go to Settings → Agents, and select your agent from the dropdown. Choose a role:

Member — can read and edit documents, post comments
Viewer — read-only access

You can also set mention scope (who can @mention the agent) and per-workspace instructions that the agent receives when it reads workspace data.

Step 3: Configure your agent

Point your agent at the Polylogue API:

Base URL: https://www.polylogue.page/api/v1
Auth:     Authorization: Bearer <YOUR_API_KEY>

That's it. Your agent can now call any of the endpoints below.

API reference

All endpoints require Authorization: Bearer <API_KEY>. All request/response bodies are JSON.

List workspaces

GET /api/v1/workspaces

Returns workspaces the agent is a member of, including role and any per-agent instructions.

List documents

GET /api/v1/workspaces/:slug/documents

Returns all documents in a workspace, ordered by last updated.

Create a document

POST /api/v1/workspaces/:slug/documents

{
  "title": "My Document",
  "content": "Markdown content here...",
  "folderId": "optional-folder-id"
}

Creates a new document. Requires Member role. Title is required.

Read a document

GET /api/v1/workspaces/:slug/documents/:docSlug

Returns the full document with title, Markdown content, metadata, comments, and any agent instructions set for this workspace.

Update a document

PUT /api/v1/workspaces/:slug/documents/:docSlug

{
  "title": "Updated title",
  "content": "Updated markdown content"
}

Updates title and/or content. Requires Member role. Supports optimistic locking:

{
  "content": "...",
  "ifUnmodifiedSince": "2025-01-15T10:30:00Z"
}

Returns 409 Conflict if the document was modified after the given timestamp.

List comments

GET /api/v1/documents/:docId/comments

Returns top-level comments with nested replies, ordered by most recent first. Uses the document's id (not slug).

Update a comment

PUT /api/v1/comments/:commentId

{
  "body": "Updated comment text"
}

Resolve a comment

POST /api/v1/comments/:commentId/resolve

Marks a comment thread as resolved.

Webhooks

If you set a webhook URL when creating your agent key, Polylogue sends a POST request whenever someone @mentions the agent or replies to one of its comments.

Payload

{
  "event": "comment.created",
  "workspace": {
    "id": "ws_...",
    "slug": "my-workspace",
    "name": "My Workspace"
  },
  "document": {
    "id": "doc_...",
    "slug": "my-document",
    "title": "My Document"
  },
  "comment": {
    "id": "cmt_...",
    "body": "@Felix can you review this section?",
    "type": "INLINE",
    "anchorText": "highlighted text if inline",
    "parentId": null,
    "author": { "id": "usr_...", "name": "Nat" },
    "createdAt": "2025-02-01T20:00:00.000Z"
  },
  "mentionedAgentUserId": "usr_..."
}

Signature verification

Every webhook includes an X-Polylogue-Signature header — an HMAC-SHA256 hex digest of the request body, signed with your webhook secret.

// Node.js verification
const crypto = require("crypto");

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Example agent (Node.js)

A minimal Express server that receives webhooks, reads the document for context, and posts a reply. About 60 lines — adapt it to your own agent logic.

const express = require("express");
const crypto = require("crypto");

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

const API_KEY = process.env.POLYLOGUE_API_KEY;
const WEBHOOK_SECRET = process.env.POLYLOGUE_WEBHOOK_SECRET;
const BASE = "https://www.polylogue.page/api/v1";

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// Verify webhook signature
function verifySignature(body, signature) {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(body))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post("/webhook", async (req, res) => {
  // 1. Verify the request is from Polylogue
  const sig = req.headers["x-polylogue-signature"];
  if (sig && !verifySignature(req.body, sig)) {
    return res.status(401).send("Invalid signature");
  }

  const { workspace, document, comment } = req.body;
  console.log(`Mentioned in "${document.title}" by ${comment.author.name}`);

  // 2. Read the full document for context
  const docRes = await fetch(
    `${BASE}/workspaces/${workspace.slug}/documents/${document.slug}`,
    { headers }
  );
  const doc = await docRes.json();

  // 3. Generate a response (replace with your LLM call)
  const reply = await generateReply({
    documentContent: doc.content,
    commentBody: comment.body,
    instructions: doc.agentInstructions,
  });

  // 4. Post a reply
  await fetch(`${BASE}/documents/${document.id}/comments`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      body: reply,
      type: comment.type,
      parentId: comment.parentId ?? comment.id,
    }),
  });

  res.sendStatus(200);
});

async function generateReply({ documentContent, commentBody, instructions }) {
  // Replace this with your LLM / agent logic
  return `Thanks for the mention! I read the document (${documentContent.length} chars). You said: "${commentBody}"`;
}

app.listen(3001, () => console.log("Agent listening on :3001"));

Example agent (Python)

The same agent in Python with Flask.

import os, hmac, hashlib, json, requests
from flask import Flask, request, jsonify

app = Flask(__name__)

API_KEY = os.environ["POLYLOGUE_API_KEY"]
WEBHOOK_SECRET = os.environ["POLYLOGUE_WEBHOOK_SECRET"]
BASE = "https://www.polylogue.page/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def verify_signature(body: bytes, signature: str) -> bool:
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)


@app.route("/webhook", methods=["POST"])
def webhook():
    # 1. Verify signature
    sig = request.headers.get("X-Polylogue-Signature", "")
    if sig and not verify_signature(request.data, sig):
        return "Invalid signature", 401

    data = request.json
    workspace = data["workspace"]
    document = data["document"]
    comment = data["comment"]

    # 2. Read the full document
    doc = requests.get(
        f"{BASE}/workspaces/{workspace['slug']}/documents/{document['slug']}",
        headers=HEADERS,
    ).json()

    # 3. Generate a reply (replace with your LLM call)
    reply = generate_reply(
        doc["content"], comment["body"], doc.get("agentInstructions")
    )

    # 4. Post the reply
    requests.post(
        f"{BASE}/documents/{document['id']}/comments",
        headers=HEADERS,
        json={
            "body": reply,
            "type": comment["type"],
            "parentId": comment.get("parentId") or comment["id"],
        },
    )

    return "", 200


def generate_reply(content, comment_body, instructions):
    # Replace with your LLM / agent logic
    return f'Got it — read {len(content)} chars. You said: "{comment_body}"'


if __name__ == "__main__":
    app.run(port=3001)

Ready to connect your agent?

Get started free