Chat Completions

Send OpenAI-style messages to POST /v1/chat/completions. Set agent for direct agent mode; omit it to use the project orchestrator. model can override the selected agent model for a single call. temperature, max_tokens, and the deprecated project field are accepted for compatibility and applied when supported by the runtime/provider path. An optional loop selects one of the target agent’s assignedLoops.

Per-request tool restriction

Use polpo.execution.allowedTools to narrow tool access for one request:

{
  "agent": "backend-dev",
  "messages": [{"role": "user", "content": "Inspect the API"}],
  "polpo": {
    "execution": {
      "allowedTools": ["read", "glob", "grep"]
    }
  }
}

This is an additional intersection, never an override that grants access. For direct chat, effective access is the intersection of the agent-wide policy, chat.allowedTools, this request policy, and trusted runtime grants. For a Project Loop, Polpo uses the agent-wide policy, loop.allowedTools, the current step policy, this request policy, and trusted grants. Entering a Loop therefore does not carry forward a direct-chat restriction. Client-side OpenAI-compatible tools declared in tools are filtered by the same policy. A forced tool_choice that names a denied tool fails before model execution. Tool-policy trace data records the active mode, requested tools, effective tools, and denied tools.

Request

curl -N "https://{project-slug}.polpo.cloud/v1/chat/completions" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "backend-dev",
    "loop": "qa-flow",
    "model": "anthropic/claude-sonnet-4-5",
    "sandbox": {
      "isolation": "reuse",
      "volumes": [{"name": "reference", "access": "read-only"}],
      "lifecycle": {"onRelease": "pool", "stopAfterIdleMinutes": 30, "deleteAfterStopMinutes": 60}
    },
    "messages": [
      {"role": "user", "content": "Explain the authentication flow"}
    ],
    "stream": true
  }'

Streaming uses server-sent events and ends with data: [DONE]. Set stream: false for one chat.completion JSON response. Messages support system, user, assistant, and tool roles. Content can be a string or an array of text, image_url, and file parts. user is an opaque caller-provided end-user identifier; Polpo does not authenticate it. sandbox.isolation can be reuse, fresh, or shared; sandbox.lifecycle controls whether the workspace is pooled or destroyed after the run; sandbox.volumes selects a narrower subset of the target agent’s persistent-volume grants. See Sandboxes. metadata accepts up to 16 string entries, with keys up to 64 characters and values up to 512 characters.

Sessions

Every response includes x-session-id. If the request has no x-session-id header, Polpo creates a new session. Persist the returned value and send it on later requests:

curl "https://{project-slug}.polpo.cloud/v1/chat/completions" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "x-session-id: sess_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "backend-dev",
    "messages": [{"role": "user", "content": "Continue"}]
  }'

Use x-session-id: new to force a new session. There is no implicit reuse when the header is omitted.

TypeScript SDK

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

const client = new PolpoClient({
  baseUrl: "https://{project-slug}.polpo.cloud",
  apiKey: process.env.POLPO_API_KEY!,
});

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

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

console.log(stream.sessionId);

Pass sessionId in the SDK request to continue a session. Call stream.abort() to cancel a streaming request.

Continue after disconnect

Durable delivery is opt-in. Add polpo.delivery.onDisconnect: "continue" to a streaming request when the run must continue after the client loses its SSE connection:

const stream = client.chatCompletionsStream({
  agent: "backend-dev",
  messages: [{ role: "user", content: "Build and test the application" }],
  polpo: { delivery: { onDisconnect: "continue" } },
});

stream.subscribeConnectionState((state) => {
  // streaming | reconnecting | closed
  console.log(state);
});

The initial response includes x-polpo-run-id, and persisted SSE frames include an id cursor. The SDK reconnects to GET /v1/runs/{runId}/events from the last complete cursor without repeating the original request.

stream.detach() closes only the current subscriber.
await stream.cancel(reason) explicitly cancels the run.
stream.abort() retains its historical cancel behavior.
stream.resume({ after }) attaches to an existing run from a cursor.

Requests that omit this option keep cancel-on-disconnect behavior. Durable delivery requires stream: true; Polpo rejects unsupported combinations rather than silently changing their semantics.

Files and images

Upload a file to an existing persistent volume through the public Files API:

curl -X POST "https://{project-slug}.polpo.cloud/v1/files/upload" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -F "path=reference" \
  -F "file=@report.pdf"

Then use the workspace-relative path as file_id:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Read and summarize this report"},
    {"type": "file", "file_id": "reference/report.pdf"}
  ]
}

A file part becomes a text reference to a project file path, so the agent needs suitable file tools and a grant to that volume. For direct multimodal image input, use an image_url part with an HTTPS URL or data URL and configure a compatible vision model. Persistent volume files belong to the project, not the chat session. The implicit local sandbox workspace instead follows sandbox lifecycle.

Client-side tool calls

In direct agent chat, interactive tools such as ask_user_question stop the model tool loop and return finish_reason: "ask_user". To resume, continue the same x-session-id and send a tool message with the returned tool_call_id, tool name, and serialized answer in content. The interrupted assistant tool call is already stored in that session. Project Loops do not support client-interaction tools in agent steps, deterministic tool steps, or hooks. A Loop configuration that references ask_user_question is rejected with loop_interactive_tool_not_supported. Collect required answers before selecting loop, then start the Loop with complete input. The endpoint follows OpenAI chat request and response conventions, but agent, loop, session headers, and Polpo finish reasons are extensions. OpenAI clients may require an extra-body mechanism for those fields.

Recover an interrupted application tool

Runtime and SDK 0.18.16 add a settlement API for request-scoped client tools. Managed writes also require the matching Cloud deployment, tenant schema and project/environment rollout; installing the SDK alone does not enable them. Inspect the call from your application server before deciding how to recover:

const identity = { sessionId, toolCallId, agent: "assistant", user: customerId };
const resolution = await polpo.getClientToolResolution(identity);

if (resolution.status === "pending") {
  await polpo.settleClientTool({
    ...identity,
    sessionVersion: resolution.sessionVersion,
    idempotencyKey: recoveryKey,
    outcome: "cancelled",
    reason: "The application did not accept this operation",
  });
}

Settlement adds one canonical tool result and a persistent receipt in the same Session. It does not call a model, execute a handler, start a Loop or create a Run. Outcomes are success, failed and cancelled; success requires a result string. Exact retries return the same receipt, including after reload. History uses completed for success or error for failed/cancelled, with settlementOutcome preserving the exact outcome. A continuation resolution means the work was already accepted: inspect its receipt and runId instead of invoking it again. Missing Run observability never makes that call pending. A settlement receipt has no runId because it creates no execution. Never use continuation as a cleanup operation after reconnect. The HTTP resources are GET /v1/chat/sessions/{sessionId}/tool-calls/{toolCallId} and PUT /v1/chat/sessions/{sessionId}/tool-calls/{toolCallId}/settlement. Use the normal Polpo key for the owning environment and the exact Session agent/user. See the versioned recovery contract for receipt schemas, version checks, idempotency and error codes. CLI equivalents are polpo sessions tool-call and polpo sessions settle-tool-call.

Chat suggestions

Loop completion suggestions and per-request options require runtime/SDK 0.16.1 or later. Use 0.16.2 or later for the shared 15-second auxiliary budget, including Loop preparation, and agent-first reasoning settings. Application actions require runtime/SDK 0.17.0 or later. Enable chat.suggestions.enabled on the agent and declare client support with polpo.capabilities.suggestions: true. Suggestions are optional { id, label, prompt } items. Send prompt as the next user message when the user selects one. The default count is three; the supported range is two through five. Successful Project Loops generate suggestions from their final presentation and Session conversation too. Streaming responses emit a root polpo.suggestions chunk before stop and [DONE]. Non-streaming responses return the same extension. GET /v1/chat/sessions/{id}/messages includes the same array on the final assistant message. Durable reconnect replays those items without generating them again. An application can supply per-request phase guidance and state:

{
  "polpo": {
    "capabilities": {
      "suggestions": {
        "enabled": true,
        "maxItems": 5,
        "guidance": "The site was just created. Help personalize it.",
        "context": {
          "published": false,
          "unpublishedChanges": true,
          "modificationsLeft": 2
        }
      }
    }
  }
}

The boolean form remains supported. An options object opts in unless enabled is false; agent settings and Cloud runtime availability still apply. Request maxItems overrides the agent count for this turn. Request guidance supplements the agent’s static guidance; neither becomes part of the assistant message. Each guidance field allows 500 characters. Context must be a JSON object of at most 8192 serialized characters, eight nesting levels, and 1024 values. Set authoritative state in your authenticated application backend and omit secrets. Context is a snapshot that can become stale during a long Loop. It helps the model avoid irrelevant suggestions but is not a permission system or a hard business-rule guarantee. Check quotas and current permissions when actions run. Raw tool results, private Loop state, and system messages are not automatically sent to the suggestion generator. For SDK client-tool handoffs, pass capabilities: { suggestions: options } to continueWithToolResult. React useChat opts in by default; set suggestions on the hook or override it in sendMessage and continueToolResult options. Generation errors and timeouts leave the primary result unchanged. Pending client-tool calls, structured responses, errors, and aborted turns do not generate suggestions. Compatible WhatsApp Channels can opt in through their host and the separate managed rollout; see Channel suggestions. On an eligible successful response, caller actions survive an optional generation error or timeout; cancellation emits no new suggestion list.

Application actions

Your application can provide deterministic actions alongside generated next messages. Supply them in polpo.capabilities.suggestions.actions:

{
  "polpo": {
    "capabilities": {
      "suggestions": {
        "enabled": true,
        "maxItems": 5,
        "actions": [
          {
            "kind": "action",
            "id": "publish",
            "label": "Publish the site",
            "action": {
              "type": "open_url",
              "url": "https://app.example.com/sites/demo/publish"
            }
          },
          {
            "kind": "action",
            "id": "plans",
            "label": "View plans",
            "action": { "type": "postback", "value": "billing:plans" }
          }
        ]
      }
    }
  }
}

Caller actions come first, in supplied order; generated messages fill the remaining slots in the same total count. Here, two actions leave room for three messages. The default total is three and the maximum is five. When actions fill the count, Polpo skips the auxiliary model call. Existing agent, client, and Cloud opt-ins still apply to the whole list. An action-capable response uses kind: "action" or kind: "message". For example:

[
  {
    "kind": "action",
    "id": "publish",
    "label": "Publish the site",
    "action": {
      "type": "open_url",
      "url": "https://app.example.com/sites/demo/publish"
    }
  },
  {
    "kind": "message",
    "id": "suggestion_example",
    "label": "Review the result",
    "prompt": "What should I check before publishing?"
  }
]

The model only generates messages. Action destinations and postback values are never included in its suggestion prompt. A list accepts at most five actions; labels allow 64 characters, HTTPS URLs 2048, and opaque postback values 2000. Optional IDs allow 64 characters and must be unique. Omitted IDs are assigned deterministically without colliding with caller IDs. URLs must be absolute HTTPS URLs without embedded credentials, whitespace, or backslashes. Your client handles selection explicitly:

For a message, send prompt as the next user message.
For open_url, open the validated destination through your application’s UI.
For postback, invoke your application’s handler with action.value. Do not send the opaque value to the agent as if it were a user message.

Polpo does not execute application operations. Your backend must recheck the current user’s permissions, quotas, and resource state before acting. A supplied action or its ID is not an authorization grant. Requests without actions retain the existing message-only output shape. Older history may omit kind; treat those records as messages. From SDK 0.17.0, ChatSuggestion is a union: check item.kind === "action" before reading item.action, otherwise read item.prompt. Validate unknown historical action URLs before enabling a link, and keep postbacks behind an explicit handler. Live responses, immediately loaded Session history, and durable replay contain the same ordered list. These capabilities describe the API and SDK contract. The hosted Playground does not currently render suggestions; updating runtime packages does not enable its controls. CLI and agent-directory settings remain unchanged because actions are supplied per request. Channel buttons and lists use a separate host rollout; enabling application actions does not enable Channel delivery.

Getting Started

Platform

Agents

Orchestration

Chat Completions

Per-request tool restriction

Request

Sessions

TypeScript SDK

Continue after disconnect

Files and images

Client-side tool calls

Recover an interrupted application tool

Chat suggestions

Application actions

​Per-request tool restriction

​Request

​Sessions

​TypeScript SDK

​Continue after disconnect

​Files and images

​Client-side tool calls

​Recover an interrupted application tool

​Chat suggestions

​Application actions

Per-request tool restriction

Request

Sessions

TypeScript SDK

Continue after disconnect

Files and images

Client-side tool calls

Recover an interrupted application tool

Chat suggestions

Application actions