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

# OpenAI API examples

> Make OpenAI-compatible API requests to Poolside models.

This page shows examples for the OpenAI-compatible API.

## Prerequisites

Before you get started, you need:

1. An API key sent with Bearer authentication. See [Authentication](/api/authentication).
2. `curl` or another tool that can make API requests.

## List available models

Most API requests require you to pass a model `id`. To get all available models and their `ids`:

```bash theme={null}
curl --request GET \
  --url https://<api-domain>/openai/v1/models \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Authorization: Bearer <api-key>'
```

**Response:**

```json theme={null}
{
  "$schema": "https://<api-domain>/openai/schemas/PageListModel.json",
  "data": [
    {
      "id": "poolside/laguna-m.1",
      "created": 1751637312,
      "owned_by": "system",
      "object": "model"
    }
  ],
  "object": "list"
}
```

In this case, the response includes one model with the `id` `poolside/laguna-m.1`.

## Send a chat prompt

To generate completions from a model, you need the model `id` and your prompt formatted as `content` inside `messages` with the `user` `role`:

```bash theme={null}
curl --request POST \
  --url https://<api-domain>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "messages": [
    {
      "content": "Explain cURL",
      "role": "user"
    }
  ],
  "model": "poolside/laguna-m.1"
}'
```

**Response:**

```json theme={null}
{
  "$schema": "https://<api-domain>/openai/schemas/ChatCompletion.json",
  "model": "poolside/laguna-m.1",
  "created": 1751993576,
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "content": "cURL is a powerful command-line tool used for transferring data to or from a server, supporting various protocols such as HTTP, HTTPS, FTP, and more. It's widely used for testing APIs, downloading files, and automating HTTP requests. cURL allows you to specify headers, methods (GET, POST, PUT, DELETE, etc.), and data payloads, making it versatile for a range of web-related tasks.\n",
        "role": "assistant"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "completion_tokens": 88,
    "prompt_tokens": 447,
    "total_tokens": 535
  }
}
```

This response used 535 total tokens: 447 for the input prompt and 88 to generate the response.

You can set optional parameters. This is not an exhaustive list.

**Request body:**

* `model` (required): Model `id` to use.
* `messages` (required): An array of messages representing the conversation.
* `max_completion_tokens` (optional): The maximum number of tokens to generate in the completion.
* `reasoning` (optional): Reasoning configuration for providers that accept the OpenRouter-style `reasoning` field.
* `stop` (optional): An array of sequences where the API stops generating further tokens.
* `temperature` (optional): What sampling temperature to use, between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic.
* `stream` (optional): Response format. A stream of a series of events or a single JSON object.

To control reasoning effort through OpenRouter-compatible models, include a `reasoning` object:

```json theme={null}
{
  "model": "poolside/laguna-m.1",
  "messages": [
    {
      "content": "Explain cURL",
      "role": "user"
    }
  ],
  "reasoning": {
    "effort": "high"
  }
}
```

Supported effort values are `xhigh`, `high`, `medium`, `low`, `minimal`, and `none`.

<Note>
  Use thought level control only with models behind OpenRouter or another provider that accepts the OpenRouter-style `reasoning` field. If the underlying model connects directly to the OpenAI Chat Completions API at `https://api.openai.com/v1/chat/completions`, requests that include the `reasoning` field fail because OpenAI rejects the field.

  For Claude 4.6 models through OpenRouter, effort settings other than `none` are ignored. OpenRouter uses adaptive thinking automatically for those requests.
</Note>

For example, if you want to receive your response as a series of completion chunks returned as server-sent events, set `stream` to `true`. This is useful for real-time applications.

```bash theme={null}
curl --request POST \
  --url https://<api-domain>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "messages": [
    {
      "content": "Explain cURL",
      "role": "user"
    }
  ],
  "model": "poolside/laguna-m.1",
  "stream": true
}'
```

**Response:**

```text theme={null}
data: {"model":"poolside/laguna-m.1","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":""}]}

data: {"model":"poolside/laguna-m.1","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"cURL","role":"assistant"},"finish_reason":""}]}

data: {"model":"poolside/laguna-m.1","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" ","role":"assistant"},"finish_reason":""}]}

data: {"model":"poolside/laguna-m.1","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"is a","role":"assistant"},"finish_reason":""}]}

...

data: {"model":"poolside/laguna-m.1","created":1754035552,"object":"chat.completion.chunk","choices":[],"usage":{"completion_tokens":95,"prompt_tokens":167,"total_tokens":262}}
```

## Send a chat prompt with extra context

Optionally, you can add more context to a query. This is useful when you want to give the model information it does not have. Refer to the [Prompting guide](/resources/prompting-best-practices) for further guidance.

Consider the following query:

```bash theme={null}
curl --request POST \
  --url https://<api-domain>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "messages": [
    {
      "content": "What is my name?",
      "role": "user"
    }
  ],
  "model": "poolside/laguna-m.1"
}'
```

The model has no mechanism to know the user's name, so it provides an incomplete response:

**Response:**

```json theme={null}
{
  "$schema": "https://<api-domain>/openai/schemas/ChatCompletion.json",
  "model": "poolside/laguna-m.1",
  "created": 1751993576,
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "content": "I'm sorry, but I do not have that information. Could you please provide your name?\n",
        "role": "assistant"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "completion_tokens": 22,
    "prompt_tokens": 674,
    "total_tokens": 696
  }
}
```

However, if you want the model to answer questions about data you have, you can pass that as context in a message:

```bash theme={null}
curl --request POST \
  --url https://<api-domain>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "messages": [
    {
      "content": "path:/Users/name/Desktop/userinfo content:My name is Ivo. Question: What is my name?",
      "role": "user"
    }
  ],
  "model": "poolside/laguna-m.1"
}'
```

In the previous snippet, the message provides context about the user's name. If you run this example, the response takes this information into account.

**Response:**

```json theme={null}
{
  "$schema": "https://<api-domain>/openai/schemas/ChatCompletion.json",
  "model": "poolside/laguna-m.1",
  "created": 1751993576,
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "content": "Based on the provided context, your name is Ivo.",
        "role": "assistant"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "completion_tokens": 15,
    "prompt_tokens": 693,
    "total_tokens": 708
  }
}
```

You can also provide multiple context messages or include file contents as context by describing them in system messages.

## Extend models with tools

You can extend your model's capabilities by providing tools (functions) that the model can call during conversations. This enables the model to perform actions like retrieving real-time data, calculations, or interacting with external systems.

To use tools, include a `tools` array in your request and define the functions the model can call:

```bash theme={null}
curl --request POST \
  --url https://<api-domain>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "model": "poolside/laguna-m.1",
  "messages": [
    {
      "role": "user",
      "content": "what is the weather forecast for Paris"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_forecast",
        "description": "Get weather forecast for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": [
            "city"
          ],
          "additionalProperties": false
        }
      }
    }
  ]
}'
```

When the model needs to use a tool, it responds with a `tool_calls` array in the model response message.

**Response:**

```json theme={null}
{
  "model": "poolside/laguna-m.1",
  "created": 1753997542,
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "type": "function",
            "function": {
              "name": "get_forecast",
              "arguments": "{\"city\": \"Paris\"}"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "completion_tokens": 95,
    "prompt_tokens": 338,
    "total_tokens": 433
  }
}
```

To continue the conversation, run the tool and provide the tool result:

```bash theme={null}
curl --request POST \
  --url https://<api-domain>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "model": "poolside/laguna-m.1",
  "messages": [
    {
      "role": "user",
      "content": "what is the weather forecast for Paris"
    },
    {
      "role": "assistant",
      "content": "",
      "tool_calls": [
        {
          "type": "function",
          "function": {
            "name": "get_forecast",
            "arguments": "{\"city\": \"Paris\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "content": "{\"temperature\": 25}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_forecast",
        "description": "Get weather forecast for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": [
            "city"
          ],
          "additionalProperties": false
        }
      }
    }
  ]
}'
```