AI Gateway (Beta) - Square Cloud

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

string

required

The API key for your account. You can find this in your account settings.

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.

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.

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). 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

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

Request contract

string

Accepted for SDK compatibility; the gateway always answers as cubic.

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.

number

Silently clamped to your plan’s output ceiling.

number

From 0 to 2.

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.

string | object

Standard OpenAI tool_choice values.

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.

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

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

Does it remember conversations?

No — the API is stateless, exactly like OpenAI’s: send the conversation history in messages on every request.

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.

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.

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.

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

​How to connect

​Plans and limits

​Request contract

​Built-in web search

​Errors

​Frequently asked questions

How to connect

Plans and limits

Request contract

Built-in web search

Errors

Frequently asked questions