> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Poolside API

> Choose a Poolside OpenAI-compatible inference endpoint, authenticate, and send your first request.

Call Poolside models through Poolside-hosted inference, self-managed Poolside inference, or OpenRouter. Each access method provides an OpenAI-compatible API, but the base URL, authentication, and available model IDs can differ. You can call the API directly or use an OpenAI-compatible SDK.

<Note>
  The endpoint reference in this section documents Poolside-hosted inference, which you use with an API key from [Poolside Platform](https://platform.poolside.ai/). Self-managed Poolside inference, inference gateways, and OpenRouter expose OpenAI-compatible interfaces at their own base URLs, with their own authentication and model IDs. Confirm which endpoints and parameters your access method supports. See [Use the API base URL for your access method](#use-the-api-base-url-for-your-access-method).
</Note>

## Use the API base URL for your access method

The OpenAI-compatible API base URL depends on how you access Poolside. The examples on this page use Poolside-hosted inference.

| Access method                                 | OpenAI-compatible API base URL                     |
| --------------------------------------------- | -------------------------------------------------- |
| Poolside-hosted inference                     | `https://inference.poolside.ai/v1`                 |
| Self-managed Poolside inference               | `https://<model-hostname>/v1`                      |
| Inference gateway, such as Bifrost or LiteLLM | The base URL exposed by the gateway                |
| OpenRouter                                    | `https://openrouter.ai/api/v1`                     |
| OpenAI-compatible provider                    | The base URL your provider or model server exposes |

OpenRouter supports OpenAI-compatible requests and the OpenAI SDK, but model IDs and supported parameters can differ.

Each model in a self-managed Poolside inference deployment has its own hostname. You can also place an OpenAI-compatible gateway in front of the model endpoints. See [Use Bifrost with Poolside model inference](/deployment/inference-gateways/bifrost) or [Use LiteLLM with Poolside model inference](/deployment/inference-gateways/litellm).

<Note>
  Poolside-hosted inference and direct model inference endpoints use `/v1`. The documented Bifrost and LiteLLM configurations also use `/v1`; another inference gateway may expose a different base URL.
</Note>

## Authenticate API requests

Poolside-hosted inference and OpenRouter require an API key sent as a Bearer token. Authentication for self-managed Poolside inference depends on how your endpoint or gateway is configured.

### Get your API key

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

* **Poolside-hosted inference**: Get an API key from [Poolside Platform](https://platform.poolside.ai/). Sign in, open the **API Keys** tab, and click **New key**.
* **OpenRouter**: Use this if you already use OpenRouter or need paid access to Poolside models. Go to [OpenRouter API keys](https://openrouter.ai/keys), sign in, and create an API key.
* **Self-managed Poolside inference**: Use the API key configured for the model endpoint or gateway. If API key authentication is off, omit the `Authorization` header.
* **OpenAI-compatible provider**: Use the API key from the provider you configure.

If you use Poolside Agent CLI, see [Log in to Poolside](/get-started/log-in) instead.

Before you run the examples, save your key in an environment variable so it is never hard-coded into your scripts.

```bash theme={null}
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:

```text theme={null}
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](/api/openai-api-examples#list-available-models).

<CodeGroup>
  ```bash cURL theme={null}
  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 Python theme={null}
  import os
  import requests

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

  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  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());
  ```
</CodeGroup>

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

### OpenAI SDK

Install the OpenAI client library.

<CodeGroup>
  ```bash pip theme={null}
  pip install openai
  ```

  ```bash npm theme={null}
  npm install openai
  ```
</CodeGroup>

Pass the base URL and API key when you create the client.

<CodeGroup>
  ```python Python theme={null}
  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 TypeScript theme={null}
  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);
  ```
</CodeGroup>

<Note>
  To use OpenRouter instead, replace the `base_url` or `baseURL` value with `https://openrouter.ai/api/v1` and pass your `OPENROUTER_API_KEY`.
</Note>

### OpenRouter SDK

Install the OpenRouter client library.

<CodeGroup>
  ```bash npm theme={null}
  npm install @openrouter/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @openrouter/sdk
  ```

  ```bash yarn theme={null}
  yarn add @openrouter/sdk
  ```

  ```bash pip theme={null}
  pip install openrouter
  ```
</CodeGroup>

Create a client with your `OPENROUTER_API_KEY`.

<CodeGroup>
  ```python Python theme={null}
  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 TypeScript theme={null}
  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);
  ```
</CodeGroup>

## Use the API for CLI automation

For CLI automation against an OpenAI-compatible endpoint, configure `POOLSIDE_STANDALONE_BASE_URL`, `POOLSIDE_STANDALONE_MODEL`, and `POOLSIDE_API_KEY`. If the endpoint does not validate API keys, use any non-empty value for `POOLSIDE_API_KEY`, such as `local-test`. See [Automate tasks](/cli/automated-mode#basic-usage).

## Next steps

* [OpenAI-compatible API examples](/api/openai-api-examples) for thinking control, streaming, tool calling, and structured output
* [Supported models](/get-started/supported-models) for model guidance, context windows, and modes
* [Editors](/tools#editors) to use Poolside from editors and editor extensions
* [Desktop apps](/tools#desktop-apps) to use Poolside from desktop apps