Skip to main content
Polpo exposes an OpenAI-compatible chat completions endpoint. You can talk to any agent using the same format as the OpenAI API — streaming or non-streaming.

​
How it works

  1. You send a message to a specific agent via POST /v1/chat/completions
  2. The agent receives your message along with its system prompt, skills, identity, and memory
  3. The agent responds using its configured model and tools
  4. Conversation history is stored in a session for multi-turn chat

​
Streaming

curl -X POST https://api.polpo.sh/v1/chat/completions \
  -H "x-api-key: $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "backend-dev",
    "messages": [
      { "role": "user", "content": "Explain how the auth module works" }
    ],
    "stream": true
  }'
The response is a standard SSE stream of OpenAI-compatible chunks: 
data: {"choices":[{"delta":{"role":"assistant","content":"The auth"},"index":0}]}

data: {"choices":[{"delta":{"content":" module uses"},"index":0}]}

data: {"choices":[{"delta":{"content":" JWT tokens..."},"index":0}]}

data: [DONE]

​
Non-streaming

curl -X POST https://api.polpo.sh/v1/chat/completions \
  -H "x-api-key: $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "backend-dev",
    "messages": [
      { "role": "user", "content": "Explain how the auth module works" }
    ],
    "stream": false
  }'

​
Sessions

Each conversation is tracked as a session. The response includes a x-session-id header that you can use to continue the conversation: 
# First message — creates a new session
curl ... -d '{ "agent": "dev", "messages": [{ "role": "user", "content": "Hello" }] }'
# Response header: x-session-id: sess_abc123

# Continue the conversation
curl ... -d '{ "agent": "dev", "sessionId": "sess_abc123", "messages": [...] }'

​
SDK usage

​
Streaming

import { PolpoClient } from "@polpo-ai/sdk";

const client = new PolpoClient({
  baseUrl: "https://api.polpo.sh",
  apiKey: "pk_live_...",
});

const stream = client.chatCompletionsStream({
  agent: "backend-dev",
  messages: [{ role: "user", content: "Refactor the payment module" }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

console.log("\nSession:", stream.sessionId);

​
Aborting

const stream = client.chatCompletionsStream({ agent: "dev", messages });
setTimeout(() => stream.abort(), 10_000); // cancel after 10s

​
Non-streaming

const response = await client.chatCompletions({
  agent: "backend-dev",
  messages: [{ role: "user", content: "Explain the auth flow" }],
});

console.log(response.choices[0].message.content);

​
What the agent receives

When you send a chat completion, the agent’s full context includes:
  1. System prompt — base Polpo prompt + agent’s systemPrompt field
  2. Identity — display name, title, tone, personality, responsibilities
  3. Skills — domain knowledge from assigned skills
  4. Memory — shared + agent-specific memory
  5. Tools — all tools from allowedTools
  6. Your messages — the conversation history

​
Attachments beta

You can attach files to a chat session. The agent reads them automatically using the built-in read_attachment tool.

​
Upload

curl -X POST https://api.polpo.sh/v1/attachments \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -F "sessionId=sess_abc123" \
  -F "file=@report.pdf"
Response: 
{
  "ok": true,
  "data": {
    "id": "att_x7k9m2",
    "sessionId": "sess_abc123",
    "filename": "report.pdf",
    "mimeType": "application/pdf",
    "size": 142857,
    "path": "workspace/attachments/sess_abc123/report.pdf"
  }
}

​
List attachments

curl https://api.polpo.sh/v1/attachments?sessionId=sess_abc123 \
  -H "Authorization: Bearer $POLPO_API_KEY"

​
Download

curl https://api.polpo.sh/v1/attachments/{id}/download \
  -H "Authorization: Bearer $POLPO_API_KEY"

​
How the agent reads attachments

When you attach a file and mention it in your message, the agent uses the read_attachment tool to read the content. The tool automatically detects the file type:
File typeHow it’s read
PDFText extraction (pdf-lib)
DOCXText extraction (mammoth)
XLSX, CSVStructured content extraction
PNG, JPG, GIF, WebPImage data for multimodal models
Text, JSON, YAML, codePlain text read
Attachments are currently in beta.

​
Tool calls

Agents can use tools during the conversation (read files, run commands, fetch URLs, etc.). Tool calls happen transparently — you receive the final response after the agent completes its tool use.
The completions API is fully compatible with OpenAI client libraries. You can use the official openai Python/Node.js package by pointing it at your Polpo endpoint.