Examples - Poolside

Prerequisites

Before you get started, you need:

Authentication: API keys sent with Bearer authentication
curl or similar: A tool to make API requests

List available models

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

curl --request GET \
  --url https://<api.domain.com>/openai/v1/models \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Authorization: Bearer <api-key>'

Response:

{
  "$schema": "https://<api.domain.com>/openai/schemas/PageListModel.json",
  "data": [
    {
      "id": "malibu",
      "created": 1751637312,
      "owned_by": "system",
      "object": "model"
    }
  ],
  "object": "list"
}

In this case, the response includes one model with the id malibu.

Chat prompt example

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

curl --request POST \
  --url https://<api.domain.com>/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": "malibu"
}'

Response:

{
  "$schema": "https://<api.domain.com>/openai/schemas/ChatCompletion.json",
  "model": "malibu",
  "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.
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.

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.

curl --request POST \
  --url https://<api.domain.com>/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": "malibu",
  "stream": true
}'

Response:

data: {"model":"malibu","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":""}]}

data: {"model":"malibu","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"cURL","role":"assistant"},"finish_reason":""}]}

data: {"model":"malibu","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" ","role":"assistant"},"finish_reason":""}]}

data: {"model":"malibu","created":1754035552,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"is a","role":"assistant"},"finish_reason":""}]}

...

data: {"model":"malibu","created":1754035552,"object":"chat.completion.chunk","choices":[],"usage":{"completion_tokens":95,"prompt_tokens":167,"total_tokens":262}}

Chat prompt example with expanded 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 for further guidance. Consider the following query:

curl --request POST \
  --url https://<api.domain.com>/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": "malibu"
}'

The model has no mechanism to know the user’s name, and as such provides a sub-par response: Response:

{
  "$schema": "https://<api.domain.com>/openai/schemas/ChatCompletion.json",
  "model": "malibu",
  "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:

curl --request POST \
  --url https://<api.domain.com>/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": "malibu"
}'

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:

{
  "$schema": "https://<api.domain.com>/openai/schemas/ChatCompletion.json",
  "model": "malibu",
  "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:

curl --request POST \
  --url https://<api.domain.com>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "model": "malibu",
  "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 assistant message. Response:

{
  "model": "malibu",
  "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:

curl --request POST \
  --url https://<api.domain.com>/openai/v1/chat/completions \
  --header 'Accept: application/json, application/problem+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data '{
  "model": "malibu",
  "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
        }
      }
    }
  ]
}'

OpenAI API

chat

models

​Prerequisites

​List available models

​Chat prompt example

​Chat prompt example with expanded context

​Extend models with tools

Prerequisites

List available models

Chat prompt example

Chat prompt example with expanded context

Extend models with tools