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

# AI Gateway (Beta)

> This documentation provides a comprehensive overview of the AI Gateway, Square Cloud's OpenAI-compatible chat completions API.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

The AI Gateway lets you use Square Cloud's hosted AI model inside your **own** products — chatbots, assistants, automations — through an **OpenAI-compatible** chat completions endpoint. If your code already speaks the OpenAI API, it speaks the AI Gateway too: point the SDK at our base URL, use your account API key, and set the model to `cubic`.

<Note>
  The AI Gateway is in **beta with free early access**: during the beta there is no extra charge beyond your plan's daily AI token budget. Limits and plan availability may change when the beta ends.
</Note>

## How to connect

* **Base URL:** `https://api.squarecloud.app/v2/ai`
* **API key:** your account API key (the same one used by the Square Cloud API and CLI, from the [account page](https://squarecloud.app/account)). The `Authorization` header is accepted with or without the `Bearer ` prefix.
* **Model:** `cubic` — Square Cloud's hosted model, the same one powering the dashboard AI assistant.

## Plans and limits

Requests are unlimited; every request bills its real tokens against your plan's **daily AI token budget** (the same budget the dashboard assistant uses, reset at 00:00 UTC).

| Plan       | Context window | Max output | Concurrent requests | Pacing between requests |
| ---------- | -------------- | ---------- | ------------------- | ----------------------- |
| Standard   | 16,384 tokens  | 4,096      | 1                   | 4s                      |
| Pro        | 24,576 tokens  | 6,144      | 1                   | 2s                      |
| Enterprise | 32,768 tokens  | 8,192      | 2                   | none                    |

<Info>Hobby plans (and accounts without a plan) do not have AI Gateway access — upgrading to Standard or above enables it.</Info>

## Request contract

<ParamField body="model" type="string">
  Accepted for SDK compatibility; the gateway always answers as `cubic`.
</ParamField>

<ParamField body="messages" type="array" required>
  OpenAI-style messages with roles `system`, `user`, `assistant` and `tool`. Content must be a **string** (no images/vision yet). Up to **100 messages** per request.
</ParamField>

<ParamField body="max_tokens" type="number">
  Silently clamped to your plan's output ceiling.
</ParamField>

<ParamField body="temperature" type="number">
  From 0 to 2.
</ParamField>

<ParamField body="tools" type="array">
  Function calling in the standard OpenAI format, up to **32 tool definitions**. Tool calls come back as `finish_reason: "tool_calls"`, and you send results back as `role: "tool"` messages.
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Standard OpenAI `tool_choice` values.
</ParamField>

Unknown parameters are ignored. **Not supported yet:** streaming (`stream: true` returns `400 stream_not_supported`) and images/vision.

### Built-in web search

The model decides on its own to search the web when the conversation asks for current or external information. Searches run server-side, and only the final answer is returned, citing result URLs. If you declare your own tool named `web_search`, yours replaces the built-in one.

<RequestExample>
  ```javascript JavaScript (OpenAI SDK) theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.squarecloud.app/v2/ai",
    apiKey: process.env.SQUARECLOUD_API_KEY,
  });

  const completion = await client.chat.completions.create({
    model: "cubic",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Explain what Square Cloud is in one sentence." },
    ],
  });

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

  ```python Python (OpenAI SDK) theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.squarecloud.app/v2/ai",
      api_key="YOUR_API_KEY",
  )

  completion = client.chat.completions.create(
      model="cubic",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Explain what Square Cloud is in one sentence."},
      ],
  )

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

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.squarecloud.app/v2/ai/chat/completions \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "cubic",
      "messages": [
        { "role": "user", "content": "Explain what Square Cloud is in one sentence." }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
    "object": "chat.completion",
    "created": 1754179200,
    "model": "cubic",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Square Cloud is a cloud platform that hosts your applications, bots, websites and databases with zero infrastructure setup."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 28,
      "completion_tokens": 24,
      "total_tokens": 52
    }
  }
  ```
</ResponseExample>

## Errors

Errors use the OpenAI shape: `{ "error": { "message", "type", "code" } }`.

| Status | Code                                                                                                        | What it means / what to do                                                                                                                                                  |
| ------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403    | `upgrade_required`                                                                                          | The plan has no AI Gateway access (Hobby or no plan). Upgrade to Standard or above.                                                                                         |
| 400    | `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | Malformed request body — fix the flagged field.                                                                                                                             |
| 400    | `stream_not_supported`                                                                                      | Remove `stream: true`; streaming is not available yet.                                                                                                                      |
| 400    | `context_length_exceeded`                                                                                   | Messages plus tool definitions exceed the plan's context window. Shorten the history or upgrade.                                                                            |
| 400    | `invalid_request`                                                                                           | The model backend refused the request — almost always a tool-calling protocol mistake (a `tool` message that does not answer a preceding `tool_calls`, duplicate call ids). |
| 429    | `concurrent_limit_reached`                                                                                  | A request is already in flight; wait for it to finish (Enterprise allows 2 at once).                                                                                        |
| 429    | `rate_limit_exceeded`                                                                                       | Requests sent faster than the plan's pacing; add the delay client-side.                                                                                                     |
| 429    | `daily_limit_reached`                                                                                       | The daily AI token budget is spent; it resets at 00:00 UTC. An upgrade raises the budget.                                                                                   |
| 503    | `server_overloaded`                                                                                         | Capacity is momentarily full; retry shortly (OpenAI SDKs retry this automatically).                                                                                         |

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does it remember conversations?">
    No — the API is stateless, exactly like OpenAI's: send the conversation history in `messages` on every request.
  </Accordion>

  <Accordion title="Which model is it?">
    `cubic`, Square Cloud's hosted model. There is no model list to choose from; the `model` field is accepted for SDK compatibility.
  </Accordion>

  <Accordion title="Can I call it from an app hosted on Square Cloud?">
    Yes — that is the main use case. It is a normal HTTPS API, so it works from anywhere.
  </Accordion>

  <Accordion title="Does gateway usage affect my dashboard AI assistant?">
    Yes: both consume the same daily AI token budget, so heavy gateway usage drains the budget available to the dashboard assistant and vice versa.
  </Accordion>
</AccordionGroup>