Poolside API - Poolside

Set the OpenAI-compatible API base URL

The OpenAI-compatible API base URL depends on how you access Poolside. The examples on this page use the base URL for Poolside Platform.

Access method OpenAI-compatible API base URL
Poolside Platform https://inference.poolside.ai/v1
Poolside deployment https://<api-domain>/openai/v1
OpenRouter https://openrouter.ai/api/v1
OpenAI-compatible provider The base URL your provider or model server exposes

OpenRouter uses an OpenAI-compatible API, so the same request shape and OpenAI SDK examples work when you switch the base URL and API key to OpenRouter. For self-managed Poolside model inference, you can use LiteLLM as an OpenAI-compatible provider gateway in front of model-server /v1 endpoints. See Use LiteLLM with Poolside model inference.

The Poolside Platform API is served at /v1. A Poolside deployment serves the OpenAI-compatible API at /openai/v1. When you switch between them, update the path as well as the host.

Authenticate API requests

Authenticate API requests with an API key sent as a Bearer token.

Get and set your API key

Where you get your API key depends on how you access Poolside.

If you use Poolside Agent CLI, see Log in to Poolside instead. Save your key as an environment variable so it is never hard-coded into your scripts. The examples below read from these variables.

export POOLSIDE_API_KEY="<api-key>"
export OPENROUTER_API_KEY="<api-key>"

The examples read these values with os.environ in Python, process.env in TypeScript, and $POOLSIDE_API_KEY in shell.

Send the key with Bearer authentication

Send your API key in the Authorization header:

Authorization: Bearer <api-key>

API keys are secrets. Store them securely and never commit them to source control.

Make your first request

Choose the approach that fits your setup. Each approach sends the same request, so you only need one.

Direct HTTP request

Send a Chat Completions request. To find model IDs for your access method, see List available models.

cURL

curl https://inference.poolside.ai/v1/chat/completions \
  -H "Authorization: Bearer $POOLSIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "poolside/laguna-s-2.1",
    "messages": [{ "role": "user", "content": "Hello Laguna" }]
  }'

Python

import os
import requests

response = requests.post(
    "https://inference.poolside.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['POOLSIDE_API_KEY']}",
    "Content-Type": "application/json"},
    json={
        "model": "poolside/laguna-s-2.1",
        "messages": [{"role": "user", "content": "Hello Laguna"}],
    },
)

print(response.json())

TypeScript

const response = await fetch("https://inference.poolside.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POOLSIDE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "poolside/laguna-s-2.1",
    messages: [{ role: "user", content: "Hello Laguna" }],
  }),
});

console.log(await response.json());

To send the same request through OpenRouter, use https://openrouter.ai/api/v1/chat/completions as the URL and your OPENROUTER_API_KEY.

OpenAI SDK

Install the OpenAI client library.

pip

pip install openai

npm

npm install openai

Point the client at Poolside by setting the base URL and API key.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["POOLSIDE_API_KEY"],
    base_url="https://inference.poolside.ai/v1",
)

completion = client.chat.completions.create(
    model="poolside/laguna-s-2.1",
    messages=[{ "role": "user", "content": "Hello Laguna" }],
)

print(completion.choices[0].message.content)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.POOLSIDE_API_KEY,
  baseURL: "https://inference.poolside.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "poolside/laguna-s-2.1",
  messages: [{ role: "user", content: "Hello Laguna" }],
});

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

To use OpenRouter instead, set the base URL to https://openrouter.ai/api/v1 and pass your OPENROUTER_API_KEY.

OpenRouter SDK

Install the OpenRouter client library.

npm

npm install @openrouter/sdk

pnpm

pnpm add @openrouter/sdk

yarn

yarn add @openrouter/sdk

pip

pip install openrouter

Create a client with your OPENROUTER_API_KEY.

Python

import os
from openrouter import OpenRouter

with OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"]) as client:
    response = client.chat.send(
        model="poolside/laguna-s-2.1",
        messages=[{"role": "user", "content": "Hello Laguna"}],
    )

print(response.choices[0].message.content)

TypeScript

import { OpenRouter } from "@openrouter/sdk";

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const completion = await client.chat.send({
  chatRequest: {
    model: "poolside/laguna-s-2.1",
    messages: [{ role: "user", content: "Hello Laguna" }],
  },
});

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

Use the API for CLI automation

For CLI automation, set POOLSIDE_API_KEY before running pool exec. If you also set POOLSIDE_API_URL, use the Poolside deployment API URL from your administrator, not the /openai/v1 OpenAI-compatible API path. See Automate tasks.

Next steps

API examples