RSX · API · Reference

ai v1

Assistants for RSX systems: models with reasoning and read-only tools, knowledge of RSX's products, and operator-set tone and boundaries.

openapi.json

Current

Base URL: https://api.rsx.group/ai/v1
Self-grantable scopes: None. Every endpoint here needs a key issued by a platform admin.
Machine readable: openapi.json

models

1 operation under /ai/v1/models.

GET/ai/v1/models/list

List the tiers and the models behind them

Every enabled text model, with whether it can use tools and how its reasoning can be steered, and the three tiers. Prefer a tier: a tier is a promise about cost and capability that outlives any one model id.

Scope: ai:models:list Admin-issued keys only.

Response 200Tiers and models

Response of listAiModels
Field	Type	Description
datarequired	AiModelList
tiersrequired	array of AiTier
modelsrequired	array of AiModel

datarequired
Type
AiModelList
Description
tiersrequired
Type
array of AiTier
Description
modelsrequired
Type
array of AiModel
Description

Errors

Each is an RFC 7807 problem document whose type URL is a page in the error reference.

401No platform API key
403The key lacks this endpoint's scope

Example

curl

curl "https://api.rsx.group/ai/v1/models/list" \
  -H "Authorization: Bearer rsx_live_..."

200 response

{
  "data": {
    "tiers": [
      {
        "name": "balanced",
        "model": "@cf/openai/gpt-oss-120b",
        "thinking": "low"
      }
    ],
    "models": [
      {
        "id": "@cf/openai/gpt-oss-120b",
        "label": "GPT-OSS 120B",
        "description": "OpenAI open-weight model for reasoning and agentic tasks.",
        "tools": true,
        "thinking": "toggle",
        "contextWindow": 131072
      }
    ]
  }
}

tools

1 operation under /ai/v1/tools.

GET/ai/v1/tools/list

List the tools an assistant can be given

Every tool is read-only. Knowledge lookups are not listed because nobody asks for them: an assistant gets them whenever its knowledge is too large for the prompt.

Scope: ai:tools:list Admin-issued keys only.

Response 200Tools

Response of listAiTools
Field	Type	Description
datarequired	array of AiTool
namerequired	AiToolName	one of "web_fetch", "rsx_status", "rsx_page_read"
reachrequired	AiToolReach	Whether the tool reads RSX or the open internet.one of "rsx", "internet"
descriptionrequired	string

datarequired
Type
array of AiTool
Description
namerequired
Type
AiToolName
Description
one of "web_fetch", "rsx_status", "rsx_page_read"
reachrequired
Type
AiToolReach
Description
Whether the tool reads RSX or the open internet.one of "rsx", "internet"
descriptionrequired
Type
string
Description

Errors

Each is an RFC 7807 problem document whose type URL is a page in the error reference.

401No platform API key
403The key lacks this endpoint's scope

Example

curl

curl "https://api.rsx.group/ai/v1/tools/list" \
  -H "Authorization: Bearer rsx_live_..."

200 response

{
  "data": [
    {
      "name": "rsx_status",
      "reach": "rsx",
      "description": "Current status of RSX services from status.rsx.group."
    }
  ]
}

chat

1 operation under /ai/v1/chat.

POST/ai/v1/chat/respond

Run an assistant for one turn

Send the conversation so far; the assistant reasons, uses any tools it was given, and answers. Nothing is stored, so send the whole conversation every turn.

Each key has a daily neuron budget and a cap on turns in flight; a turn past either is refused with 429 and Retry-After.

Not idempotent and not an add: the same request can be answered differently, and each call is billed.

Scope: ai:chat:respond Admin-issued keys only.

Request bodyapplication/json

Request body of respondAiChat
Field	Type	Description
model	string	A tier (`fast`, `balanced`, `deep`) or a model id from `models/list`.1 to 128 characters · default "balanced"
messagesrequired	array of AiMessage	The conversation so far, oldest first. The service keeps none of it.1 to 50 items
rolerequired	string	one of "user", "assistant"
contentrequired	string	1 to 16000 characters
awareness	string	`rsx` gives the assistant RSX's identity and knowledge of how its products work.one of "none", "rsx" · default "none"
audience	string	Which RSX knowledge it may use. `staff` needs the `ai:knowledge:staff` scope.one of "public", "staff" · default "public"
persona	AiPersona
name	string	What the assistant calls itself.1 to 64 characters
tone	string	1 to 200 characters
language	string	Reply in this language whatever the person writes in. Omit to mirror them.1 to 32 characters
instructions	string	Free-form operator instructions. They cannot override the platform's rules for assistants.1 to 8000 characters
knowledge	array of AiKnowledge	up to 50 items
id	string	matches ^[a-z0-9-]{1,48}$
titlerequired	string	1 to 200 characters
bodyrequired	string	1 to 8000 characters
url	string, uri	up to 2048 characters
keywords	array of string	up to 20 items
boundaries	AiBoundaries
never	array of string	Topics the assistant must not discuss. A prompt, not a guarantee: keep anything secret out of the request entirely.up to 30 items
refusal	string	What the assistant replies, word for word, when a message touches one of those topics.1 to 500 characters
stayOnTopic	one of boolean, string	Decline anything off one subject. `true` means RSX when `awareness` is `rsx`.
context	AiContext
surface	string	1 to 200 characters
page	string	1 to 2048 characters
viewer	map of one of string, number, boolean, any, or null, any, or null	Non-secret facts about the person asking, such as their handle or whether their email is verified. Never a token, key or password.
{key}	one of string, number, boolean, any, or null, any, or null
tools	array of AiToolRequest	up to 3 items
thinking	object	The reasoning the tier runs with when a request does not choose. `null` leaves it to the model.
limits	AiLimits
maxSteps	integer	Model calls in the turn, including the one that answers. Tools need at least 2. Default 6.1 to 8
maxOutputTokens	integer	Per model call. Reasoning counts against it. Default 4096.256 to 8192
includeReasoning	boolean	Return the model's reasoning with the answer. It is written for the model, not for people.default false
stream	boolean	Answer as `text/event-stream` instead of one JSON document, so text arrives as the model writes it. The events are described on the 200 response.default false

model
Type
string
Description
A tier (fast, balanced, deep) or a model id from models/list.1 to 128 characters · default "balanced"
messagesrequired
Type
array of AiMessage
Description
The conversation so far, oldest first. The service keeps none of it.1 to 50 items
rolerequired
Type
string
Description
one of "user", "assistant"
contentrequired
Type
string
Description
1 to 16000 characters
awareness
Type
string
Description
rsx gives the assistant RSX's identity and knowledge of how its products work.one of "none", "rsx" · default "none"
audience
Type
string
Description
Which RSX knowledge it may use. staff needs the ai:knowledge:staff scope.one of "public", "staff" · default "public"
persona
Type
AiPersona
Description
name
Type
string
Description
What the assistant calls itself.1 to 64 characters
tone
Type
string
Description
1 to 200 characters
language
Type
string
Description
Reply in this language whatever the person writes in. Omit to mirror them.1 to 32 characters
instructions
Type
string
Description
Free-form operator instructions. They cannot override the platform's rules for assistants.1 to 8000 characters
knowledge
Type
array of AiKnowledge
Description
up to 50 items
id
Type
string
Description
matches ^[a-z0-9-]{1,48}$
titlerequired
Type
string
Description
1 to 200 characters
bodyrequired
Type
string
Description
1 to 8000 characters
url
Type
string, uri
Description
up to 2048 characters
keywords
Type
array of string
Description
up to 20 items
boundaries
Type
AiBoundaries
Description
never
Type
array of string
Description
Topics the assistant must not discuss. A prompt, not a guarantee: keep anything secret out of the request entirely.up to 30 items
refusal
Type
string
Description
What the assistant replies, word for word, when a message touches one of those topics.1 to 500 characters
stayOnTopic
Type
one of boolean, string
Description
Decline anything off one subject. true means RSX when awareness is rsx.
context
Type
AiContext
Description
surface
Type
string
Description
1 to 200 characters
page
Type
string
Description
1 to 2048 characters
viewer
Type
map of one of string, number, boolean, any, or null, any, or null
Description
Non-secret facts about the person asking, such as their handle or whether their email is verified. Never a token, key or password.
{key}
Type
one of string, number, boolean, any, or null, any, or null
Description
tools
Type
array of AiToolRequest
Description
up to 3 items
thinking
Type
object
Description
The reasoning the tier runs with when a request does not choose. null leaves it to the model.
limits
Type
AiLimits
Description
maxSteps
Type
integer
Description
Model calls in the turn, including the one that answers. Tools need at least 2. Default 6.1 to 8
maxOutputTokens
Type
integer
Description
Per model call. Reasoning counts against it. Default 4096.256 to 8192
includeReasoning
Type
boolean
Description
Return the model's reasoning with the answer. It is written for the model, not for people.default false
stream
Type
boolean
Description
Answer as text/event-stream instead of one JSON document, so text arrives as the model writes it. The events are described on the 200 response.default false

Response 200The assistant's answer: JSON, or with `stream: true` an event stream

Response of respondAiChat
Field	Type	Description
datarequired	AiResponse
textrequired	string
reasoning	string
finishReasonrequired	string	`stop`: the model answered. `length`: the answer hit `maxOutputTokens`. `step-limit`: the model answered without tools it was still using, because `maxSteps` ran out.one of "stop", "length", "step-limit"
modelrequired	string	The model that answered, always the resolved id, so a caller on a tier can see the tier move.
stepsrequired	integer
toolCallsrequired	array of AiToolCall
usagerequired	AiUsage

datarequired
Type
AiResponse
Description
textrequired
Type
string
Description
reasoning
Type
string
Description
finishReasonrequired
Type
string
Description
stop: the model answered. length: the answer hit maxOutputTokens. step-limit: the model answered without tools it was still using, because maxSteps ran out.one of "stop", "length", "step-limit"
modelrequired
Type
string
Description
The model that answered, always the resolved id, so a caller on a tier can see the tier move.
stepsrequired
Type
integer
Description
toolCallsrequired
Type
array of AiToolCall
Description
usagerequired
Type
AiUsage
Description

Errors

Each is an RFC 7807 problem document whose type URL is a page in the error reference.

400Invalid request, a model that is not available, or a capability the model does not have
401No platform API key
403The key lacks this endpoint's scope
422The AI Gateway's content policy refused the conversation or the reply
429The key's daily budget is spent, or it has too many turns in flight
502Workers AI failed, or the model finished without writing an answer
503The usage ledger could not answer, so no turn was run

Example

curl

curl -X POST https://api.rsx.group/ai/v1/chat/respond \
  -H "Authorization: Bearer rsx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "model": "balanced",
  "messages": [
    {
      "role": "user",
      "content": "string"
    }
  ],
  "awareness": "none",
  "audience": "public",
  "persona": {
    "name": "RSX Help",
    "tone": "friendly and brief",
    "language": "English",
    "instructions": "string"
  },
  "knowledge": [
    {
      "id": "opening-hours",
      "title": "Support hours",
      "body": "Support replies within one working day.",
      "url": "https://example.com/",
      "keywords": [
        "string"
      ]
    }
  ],
  "boundaries": {
    "never": [
      "unreleased products"
    ],
    "refusal": "That is not something I can discuss.",
    "stayOnTopic": true
  },
  "context": {
    "surface": "RSX ID (id.rsx.group)",
    "page": "https://id.rsx.group/security",
    "viewer": {
      "handle": "sam",
      "developer": false
    }
  },
  "tools": [
    "rsx_status"
  ],
  "thinking": {},
  "limits": {
    "maxSteps": 4,
    "maxOutputTokens": 2048
  },
  "includeReasoning": false,
  "stream": false
}'

200 response

{
  "data": {
    "text": "Go to https://id.rsx.group/profile. The Profile picture panel is at the top.",
    "reasoning": "string",
    "finishReason": "stop",
    "model": "@cf/openai/gpt-oss-120b",
    "steps": 1,
    "toolCalls": [
      {
        "name": "knowledge_search",
        "status": "ok",
        "reach": {},
        "ms": 42
      }
    ],
    "usage": {
      "inputTokens": 2785,
      "outputTokens": 96,
      "neurons": 100.4
    }
  }
}

admin

3 operations under /ai/v1/admin.

GET/ai/v1/admin/usage/list

Usage and budgets, per key

Every key that ran or was refused a turn in the period, or has a budget of its own: today's spend against its budget, turns in flight, and one row per day.

Scope: ai:admin:usage:list Admin-issued keys only.

Query parameters

Query parameters of listAiUsage
Parameter	Type	Description
days	integer	1 to 90 · default 7

days
Type
integer
Description
1 to 90 · default 7

Response 200Usage

Response of listAiUsage
Field	Type	Description
datarequired	AiUsageList
dayrequired	string
resetsAtrequired	string, date-time	When today's budgets reset: the next midnight UTC.
defaultsrequired	object
dailyNeuronsrequired	integer
maxConcurrentrequired	integer
keysrequired	array of AiKeyUsage	Every key with a turn in the period or a budget of its own, most spent today first.

datarequired
Type
AiUsageList
Description
dayrequired
Type
string
Description
resetsAtrequired
Type
string, date-time
Description
When today's budgets reset: the next midnight UTC.
defaultsrequired
Type
object
Description
dailyNeuronsrequired
Type
integer
Description
maxConcurrentrequired
Type
integer
Description
keysrequired
Type
array of AiKeyUsage
Description
Every key with a turn in the period or a budget of its own, most spent today first.

Errors

Each is an RFC 7807 problem document whose type URL is a page in the error reference.

401Missing or wrong platform admin token
404Not called over the dashboard's service binding
503The usage ledger could not answer

Example

curl

curl "https://api.rsx.group/ai/v1/admin/usage/list" \
  -H "Authorization: Bearer rsx_live_..."

200 response

{
  "data": {
    "day": "2026-09-16",
    "resetsAt": "2026-10-10T12:00:00.000Z",
    "defaults": {
      "dailyNeurons": 50000,
      "maxConcurrent": 8
    },
    "keys": [
      {
        "keyId": "string",
        "budget": {
          "keyId": "0198f2b1-6c2a-7c9e-9d3a-1e2f3a4b5c6d",
          "dailyNeurons": 200000,
          "maxConcurrent": null,
          "note": "Help box on rsx.group; raised for launch week.",
          "effectiveDailyNeurons": 200000,
          "effectiveMaxConcurrent": 8,
          "updatedAt": "2026-10-10T12:00:00.000Z",
          "updatedBy": "string"
        },
        "inFlight": 1,
        "today": {
          "day": "2026-09-16",
          "turns": 412,
          "refused": 0,
          "neurons": 38211.5,
          "inputTokens": 1,
          "outputTokens": 1
        },
        "days": [
          {
            "day": null,
            "turns": null,
            "refused": null,
            "neurons": null,
            "inputTokens": null,
            "outputTokens": null
          }
        ],
        "lastTurnAt": "2026-10-10T12:00:00.000Z"
      }
    ]
  }
}

POST/ai/v1/admin/budgets/update

Set a key's budget

Sets this key's daily neuron budget and its cap on turns in flight; null for either follows the default. Takes effect on the key's next turn. Recorded in the trail with the operator and the before and after.

Scope: ai:admin:budgets:update Admin-issued keys only.

Request bodyapplication/json

Request body of updateAiBudget
Field	Type	Description
keyIdrequired	string	1 to 64 characters
keyLabel	string, or null	The key's name, recorded with the change so the trail still reads after the key is revoked.1 to 120 characters · default null
dailyNeuronsrequired	integer, or null	0 to 100000000
maxConcurrentrequired	integer, or null	1 to 100
note	string, or null	1 to 280 characters · default null

keyIdrequired
Type
string
Description
1 to 64 characters
keyLabel
Type
string, or null
Description
The key's name, recorded with the change so the trail still reads after the key is revoked.1 to 120 characters · default null
dailyNeuronsrequired
Type
integer, or null
Description
0 to 100000000
maxConcurrentrequired
Type
integer, or null
Description
1 to 100
note
Type
string, or null
Description
1 to 280 characters · default null

Response 200The key's budget as it now stands

Response of updateAiBudget
Field	Type	Description
datarequired	AiBudget
keyIdrequired	string
dailyNeuronsrequired	integer, or null	This key's own daily budget. `null` follows the default. `0` switches the key off.
maxConcurrentrequired	integer, or null	This key's own cap on turns in flight. `null` follows the default.
noterequired	string, or null
effectiveDailyNeuronsrequired	integer
effectiveMaxConcurrentrequired	integer
updatedAtrequired	string, date-time, or null
updatedByrequired	string, or null
metarequired	object
eventrequired	AiAuditEvent

datarequired
Type
AiBudget
Description
keyIdrequired
Type
string
Description
dailyNeuronsrequired
Type
integer, or null
Description
This key's own daily budget. null follows the default. 0 switches the key off.
maxConcurrentrequired
Type
integer, or null
Description
This key's own cap on turns in flight. null follows the default.
noterequired
Type
string, or null
Description
effectiveDailyNeuronsrequired
Type
integer
Description
effectiveMaxConcurrentrequired
Type
integer
Description
updatedAtrequired
Type
string, date-time, or null
Description
updatedByrequired
Type
string, or null
Description
metarequired
Type
object
Description
eventrequired
Type
AiAuditEvent
Description

Errors

Each is an RFC 7807 problem document whose type URL is a page in the error reference.

400The request did not match the endpoint's schema
401Missing or wrong platform admin token
404Not called over the dashboard's service binding
503The usage ledger could not answer

Example

curl

curl -X POST https://api.rsx.group/ai/v1/admin/budgets/update \
  -H "Authorization: Bearer rsx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "keyId": "string",
  "keyLabel": null,
  "dailyNeurons": 1,
  "maxConcurrent": 1,
  "note": null
}'

200 response

{
  "data": {
    "keyId": "0198f2b1-6c2a-7c9e-9d3a-1e2f3a4b5c6d",
    "dailyNeurons": 200000,
    "maxConcurrent": null,
    "note": "Help box on rsx.group; raised for launch week.",
    "effectiveDailyNeurons": 200000,
    "effectiveMaxConcurrent": 8,
    "updatedAt": "2026-10-10T12:00:00.000Z",
    "updatedBy": "string"
  },
  "meta": {
    "event": {
      "id": "018f3b1c-9a2e-7c31-8f4d-2a6b5c7e9d12",
      "actor": "ops@rsx.group",
      "action": "budget.updated",
      "targetType": "key",
      "targetId": "string",
      "targetLabel": "string",
      "at": "2026-09-12T10:16:30.000Z",
      "detail": "string"
    }
  }
}

GET/ai/v1/admin/audit/list

The operator trail

Every budget change, newest first. Merged into the dashboard's Activity feed.

Scope: ai:admin:audit:list Admin-issued keys only.

Query parameters

Query parameters of listAiAudit
Parameter	Type	Description
targetType	string	one of "key"
targetId	string	up to 128 characters
actor	string	up to 320 characters
action	string	one of "budget.updated"
offset	integer, or null	at least 0 · default 0
limit	integer	1 to 100 · default 50

targetType
Type
string
Description
one of "key"
targetId
Type
string
Description
up to 128 characters
actor
Type
string
Description
up to 320 characters
action
Type
string
Description
one of "budget.updated"
offset
Type
integer, or null
Description
at least 0 · default 0
limit
Type
integer
Description
1 to 100 · default 50

Response 200Events

Response of listAiAudit
Field	Type	Description
datarequired	array of AiAuditEvent
idrequired	string
actorrequired	string
actionrequired	string	one of "budget.updated"
targetTyperequired	string	one of "key"
targetIdrequired	string
targetLabelrequired	string, or null
atrequired	string, date-time
detailrequired	string, or null
metarequired	object
offsetrequired	integer
limitrequired	integer
morerequired	boolean

datarequired
Type
array of AiAuditEvent
Description
idrequired
Type
string
Description
actorrequired
Type
string
Description
actionrequired
Type
string
Description
one of "budget.updated"
targetTyperequired
Type
string
Description
one of "key"
targetIdrequired
Type
string
Description
targetLabelrequired
Type
string, or null
Description
atrequired
Type
string, date-time
Description
detailrequired
Type
string, or null
Description
metarequired
Type
object
Description
offsetrequired
Type
integer
Description
limitrequired
Type
integer
Description
morerequired
Type
boolean
Description

Errors

Each is an RFC 7807 problem document whose type URL is a page in the error reference.

401Missing or wrong platform admin token
404Not called over the dashboard's service binding
503The usage ledger could not answer

Example

curl

curl "https://api.rsx.group/ai/v1/admin/audit/list" \
  -H "Authorization: Bearer rsx_live_..."

200 response

{
  "data": [
    {
      "id": "018f3b1c-9a2e-7c31-8f4d-2a6b5c7e9d12",
      "actor": "ops@rsx.group",
      "action": "budget.updated",
      "targetType": "key",
      "targetId": "string",
      "targetLabel": "string",
      "at": "2026-09-12T10:16:30.000Z",
      "detail": "string"
    }
  ],
  "meta": {
    "offset": 1,
    "limit": 1,
    "more": true
  }
}

Schemas

Every named shape in this reference, as the operations above refer to it.

AiTierName

string

AiThinkingLevel

The reasoning the tier runs with when a request does not choose. null leaves it to the model.

string, or null. The reasoning the tier runs with when a request does not choose. `null` leaves it to the model.

AiTier

AiTier
Field	Type	Description
namerequired	AiTierName	one of "fast", "balanced", "deep"
modelrequired	string
thinkingrequired	AiThinkingLevel	The reasoning the tier runs with when a request does not choose. `null` leaves it to the model.one of "off", "low", "medium", "high"

namerequired
Type
AiTierName
Description
one of "fast", "balanced", "deep"
modelrequired
Type
string
Description
thinkingrequired
Type
AiThinkingLevel
Description
The reasoning the tier runs with when a request does not choose. null leaves it to the model.one of "off", "low", "medium", "high"

AiThinkingMode

none: the model does not reason. toggle: reasoning can be switched off. always: it reasons on every call, whatever is asked.

string. `none`: the model does not reason. `toggle`: reasoning can be switched off. `always`: it reasons on every call, whatever is asked.

AiModel

AiModel
Field	Type	Description
idrequired	string
labelrequired	string
descriptionrequired	string
toolsrequired	boolean	Whether the model can be given tools. Measured by running it, not taken from the catalogue.
thinkingrequired	AiThinkingMode	`none`: the model does not reason. `toggle`: reasoning can be switched off. `always`: it reasons on every call, whatever is asked.one of "none", "toggle", "always"
contextWindowrequired	integer, or null	Tokens, where Cloudflare states it. `null` means unknown, never unlimited.

idrequired
Type
string
Description
labelrequired
Type
string
Description
descriptionrequired
Type
string
Description
toolsrequired
Type
boolean
Description
Whether the model can be given tools. Measured by running it, not taken from the catalogue.
thinkingrequired
Type
AiThinkingMode
Description
none: the model does not reason. toggle: reasoning can be switched off. always: it reasons on every call, whatever is asked.one of "none", "toggle", "always"
contextWindowrequired
Type
integer, or null
Description
Tokens, where Cloudflare states it. null means unknown, never unlimited.

AiModelList

AiModelList
Field	Type	Description
tiersrequired	array of AiTier
namerequired	AiTierName	one of "fast", "balanced", "deep"
modelrequired	string
thinkingrequired	AiThinkingLevel	The reasoning the tier runs with when a request does not choose. `null` leaves it to the model.one of "off", "low", "medium", "high"
modelsrequired	array of AiModel
idrequired	string
labelrequired	string
descriptionrequired	string
toolsrequired	boolean	Whether the model can be given tools. Measured by running it, not taken from the catalogue.
thinkingrequired	AiThinkingMode	`none`: the model does not reason. `toggle`: reasoning can be switched off. `always`: it reasons on every call, whatever is asked.one of "none", "toggle", "always"
contextWindowrequired	integer, or null	Tokens, where Cloudflare states it. `null` means unknown, never unlimited.

tiersrequired
Type
array of AiTier
Description
namerequired
Type
AiTierName
Description
one of "fast", "balanced", "deep"
modelrequired
Type
string
Description
thinkingrequired
Type
AiThinkingLevel
Description
The reasoning the tier runs with when a request does not choose. null leaves it to the model.one of "off", "low", "medium", "high"
modelsrequired
Type
array of AiModel
Description
idrequired
Type
string
Description
labelrequired
Type
string
Description
descriptionrequired
Type
string
Description
toolsrequired
Type
boolean
Description
Whether the model can be given tools. Measured by running it, not taken from the catalogue.
thinkingrequired
Type
AiThinkingMode
Description
none: the model does not reason. toggle: reasoning can be switched off. always: it reasons on every call, whatever is asked.one of "none", "toggle", "always"
contextWindowrequired
Type
integer, or null
Description
Tokens, where Cloudflare states it. null means unknown, never unlimited.

Problem

Problem
Field	Type	Description
typerequired	string
titlerequired	string
statusrequired	integer
detail	string
instance	string
requestId	string

typerequired
Type
string
Description
titlerequired
Type
string
Description
statusrequired
Type
integer
Description
detail
Type
string
Description
instance
Type
string
Description
requestId
Type
string
Description

AiTool
Field	Type	Description
namerequired	AiToolName	one of "web_fetch", "rsx_status", "rsx_page_read"
reachrequired	AiToolReach	Whether the tool reads RSX or the open internet.one of "rsx", "internet"
descriptionrequired	string

namerequired
Type
AiToolName
Description
one of "web_fetch", "rsx_status", "rsx_page_read"
reachrequired
Type
AiToolReach
Description
Whether the tool reads RSX or the open internet.one of "rsx", "internet"
descriptionrequired
Type
string
Description

AiToolCall

AiToolCall
Field	Type	Description
namerequired	string
statusrequired	string	`refused`: the call never ran. `failed`: it ran and did not succeed. The model is told either way.one of "ok", "failed", "refused"
reachrequired	object	Whether the tool reads RSX or the open internet.
msrequired	integer

namerequired
Type
string
Description
statusrequired
Type
string
Description
refused: the call never ran. failed: it ran and did not succeed. The model is told either way.one of "ok", "failed", "refused"
reachrequired
Type
object
Description
Whether the tool reads RSX or the open internet.
msrequired
Type
integer
Description

AiUsage

AiUsage
Field	Type	Description
inputTokensrequired	integer
outputTokensrequired	integer
neurons	number	Workers AI's billing unit, as reported with the answer. Approximate; not an invoice.

inputTokensrequired
Type
integer
Description
outputTokensrequired
Type
integer
Description
neurons
Type
number
Description
Workers AI's billing unit, as reported with the answer. Approximate; not an invoice.

AiResponse

AiResponse
Field	Type	Description
textrequired	string
reasoning	string
finishReasonrequired	string	`stop`: the model answered. `length`: the answer hit `maxOutputTokens`. `step-limit`: the model answered without tools it was still using, because `maxSteps` ran out.one of "stop", "length", "step-limit"
modelrequired	string	The model that answered, always the resolved id, so a caller on a tier can see the tier move.
stepsrequired	integer
toolCallsrequired	array of AiToolCall
namerequired	string
statusrequired	string	`refused`: the call never ran. `failed`: it ran and did not succeed. The model is told either way.one of "ok", "failed", "refused"
reachrequired	object	Whether the tool reads RSX or the open internet.
msrequired	integer
usagerequired	AiUsage
inputTokensrequired	integer
outputTokensrequired	integer
neurons	number	Workers AI's billing unit, as reported with the answer. Approximate; not an invoice.

textrequired
Type
string
Description
reasoning
Type
string
Description
finishReasonrequired
Type
string
Description
stop: the model answered. length: the answer hit maxOutputTokens. step-limit: the model answered without tools it was still using, because maxSteps ran out.one of "stop", "length", "step-limit"
modelrequired
Type
string
Description
The model that answered, always the resolved id, so a caller on a tier can see the tier move.
stepsrequired
Type
integer
Description
toolCallsrequired
Type
array of AiToolCall
Description
namerequired
Type
string
Description
statusrequired
Type
string
Description
refused: the call never ran. failed: it ran and did not succeed. The model is told either way.one of "ok", "failed", "refused"
reachrequired
Type
object
Description
Whether the tool reads RSX or the open internet.
msrequired
Type
integer
Description
usagerequired
Type
AiUsage
Description
inputTokensrequired
Type
integer
Description
outputTokensrequired
Type
integer
Description
neurons
Type
number
Description
Workers AI's billing unit, as reported with the answer. Approximate; not an invoice.

AiMessage

AiMessage
Field	Type	Description
rolerequired	string	one of "user", "assistant"
contentrequired	string	1 to 16000 characters

rolerequired
Type
string
Description
one of "user", "assistant"
contentrequired
Type
string
Description
1 to 16000 characters

AiPersona

AiPersona
Field	Type	Description
name	string	What the assistant calls itself.1 to 64 characters
tone	string	1 to 200 characters
language	string	Reply in this language whatever the person writes in. Omit to mirror them.1 to 32 characters
instructions	string	Free-form operator instructions. They cannot override the platform's rules for assistants.1 to 8000 characters

name
Type
string
Description
What the assistant calls itself.1 to 64 characters
tone
Type
string
Description
1 to 200 characters
language
Type
string
Description
Reply in this language whatever the person writes in. Omit to mirror them.1 to 32 characters
instructions
Type
string
Description
Free-form operator instructions. They cannot override the platform's rules for assistants.1 to 8000 characters

AiKnowledge

AiKnowledge
Field	Type	Description
id	string	matches ^[a-z0-9-]{1,48}$
titlerequired	string	1 to 200 characters
bodyrequired	string	1 to 8000 characters
url	string, uri	up to 2048 characters
keywords	array of string	up to 20 items

id
Type
string
Description
matches ^[a-z0-9-]{1,48}$
titlerequired
Type
string
Description
1 to 200 characters
bodyrequired
Type
string
Description
1 to 8000 characters
url
Type
string, uri
Description
up to 2048 characters
keywords
Type
array of string
Description
up to 20 items

AiBoundaries

AiBoundaries
Field	Type	Description
never	array of string	Topics the assistant must not discuss. A prompt, not a guarantee: keep anything secret out of the request entirely.up to 30 items
refusal	string	What the assistant replies, word for word, when a message touches one of those topics.1 to 500 characters
stayOnTopic	one of boolean, string	Decline anything off one subject. `true` means RSX when `awareness` is `rsx`.

never
Type
array of string
Description
Topics the assistant must not discuss. A prompt, not a guarantee: keep anything secret out of the request entirely.up to 30 items
refusal
Type
string
Description
What the assistant replies, word for word, when a message touches one of those topics.1 to 500 characters
stayOnTopic
Type
one of boolean, string
Description
Decline anything off one subject. true means RSX when awareness is rsx.

AiContext

AiContext
Field	Type	Description
surface	string	1 to 200 characters
page	string	1 to 2048 characters
viewer	map of one of string, number, boolean, any, or null, any, or null	Non-secret facts about the person asking, such as their handle or whether their email is verified. Never a token, key or password.
{key}	one of string, number, boolean, any, or null, any, or null

surface
Type
string
Description
1 to 200 characters
page
Type
string
Description
1 to 2048 characters
viewer
Type
map of one of string, number, boolean, any, or null, any, or null
Description
Non-secret facts about the person asking, such as their handle or whether their email is verified. Never a token, key or password.
{key}
Type
one of string, number, boolean, any, or null, any, or null
Description

AiToolRequest

one of AiToolName, object

AiLimits

AiLimits
Field	Type	Description
maxSteps	integer	Model calls in the turn, including the one that answers. Tools need at least 2. Default 6.1 to 8
maxOutputTokens	integer	Per model call. Reasoning counts against it. Default 4096.256 to 8192

maxSteps
Type
integer
Description
Model calls in the turn, including the one that answers. Tools need at least 2. Default 6.1 to 8
maxOutputTokens
Type
integer
Description
Per model call. Reasoning counts against it. Default 4096.256 to 8192

AiRespond

AiRespond
Field	Type	Description
model	string	A tier (`fast`, `balanced`, `deep`) or a model id from `models/list`.1 to 128 characters · default "balanced"
messagesrequired	array of AiMessage	The conversation so far, oldest first. The service keeps none of it.1 to 50 items
rolerequired	string	one of "user", "assistant"
contentrequired	string	1 to 16000 characters
awareness	string	`rsx` gives the assistant RSX's identity and knowledge of how its products work.one of "none", "rsx" · default "none"
audience	string	Which RSX knowledge it may use. `staff` needs the `ai:knowledge:staff` scope.one of "public", "staff" · default "public"
persona	AiPersona
name	string	What the assistant calls itself.1 to 64 characters
tone	string	1 to 200 characters
language	string	Reply in this language whatever the person writes in. Omit to mirror them.1 to 32 characters
instructions	string	Free-form operator instructions. They cannot override the platform's rules for assistants.1 to 8000 characters
knowledge	array of AiKnowledge	up to 50 items
id	string	matches ^[a-z0-9-]{1,48}$
titlerequired	string	1 to 200 characters
bodyrequired	string	1 to 8000 characters
url	string, uri	up to 2048 characters
keywords	array of string	up to 20 items
boundaries	AiBoundaries
never	array of string	Topics the assistant must not discuss. A prompt, not a guarantee: keep anything secret out of the request entirely.up to 30 items
refusal	string	What the assistant replies, word for word, when a message touches one of those topics.1 to 500 characters
stayOnTopic	one of boolean, string	Decline anything off one subject. `true` means RSX when `awareness` is `rsx`.
context	AiContext
surface	string	1 to 200 characters
page	string	1 to 2048 characters
viewer	map of one of string, number, boolean, any, or null, any, or null	Non-secret facts about the person asking, such as their handle or whether their email is verified. Never a token, key or password.
{key}	one of string, number, boolean, any, or null, any, or null
tools	array of AiToolRequest	up to 3 items
thinking	object	The reasoning the tier runs with when a request does not choose. `null` leaves it to the model.
limits	AiLimits
maxSteps	integer	Model calls in the turn, including the one that answers. Tools need at least 2. Default 6.1 to 8
maxOutputTokens	integer	Per model call. Reasoning counts against it. Default 4096.256 to 8192
includeReasoning	boolean	Return the model's reasoning with the answer. It is written for the model, not for people.default false
stream	boolean	Answer as `text/event-stream` instead of one JSON document, so text arrives as the model writes it. The events are described on the 200 response.default false

model
Type
string
Description
A tier (fast, balanced, deep) or a model id from models/list.1 to 128 characters · default "balanced"
messagesrequired
Type
array of AiMessage
Description
The conversation so far, oldest first. The service keeps none of it.1 to 50 items
rolerequired
Type
string
Description
one of "user", "assistant"
contentrequired
Type
string
Description
1 to 16000 characters
awareness
Type
string
Description
rsx gives the assistant RSX's identity and knowledge of how its products work.one of "none", "rsx" · default "none"
audience
Type
string
Description
Which RSX knowledge it may use. staff needs the ai:knowledge:staff scope.one of "public", "staff" · default "public"
persona
Type
AiPersona
Description
name
Type
string
Description
What the assistant calls itself.1 to 64 characters
tone
Type
string
Description
1 to 200 characters
language
Type
string
Description
Reply in this language whatever the person writes in. Omit to mirror them.1 to 32 characters
instructions
Type
string
Description
Free-form operator instructions. They cannot override the platform's rules for assistants.1 to 8000 characters
knowledge
Type
array of AiKnowledge
Description
up to 50 items
id
Type
string
Description
matches ^[a-z0-9-]{1,48}$
titlerequired
Type
string
Description
1 to 200 characters
bodyrequired
Type
string
Description
1 to 8000 characters
url
Type
string, uri
Description
up to 2048 characters
keywords
Type
array of string
Description
up to 20 items
boundaries
Type
AiBoundaries
Description
never
Type
array of string
Description
Topics the assistant must not discuss. A prompt, not a guarantee: keep anything secret out of the request entirely.up to 30 items
refusal
Type
string
Description
What the assistant replies, word for word, when a message touches one of those topics.1 to 500 characters
stayOnTopic
Type
one of boolean, string
Description
Decline anything off one subject. true means RSX when awareness is rsx.
context
Type
AiContext
Description
surface
Type
string
Description
1 to 200 characters
page
Type
string
Description
1 to 2048 characters
viewer
Type
map of one of string, number, boolean, any, or null, any, or null
Description
Non-secret facts about the person asking, such as their handle or whether their email is verified. Never a token, key or password.
{key}
Type
one of string, number, boolean, any, or null, any, or null
Description
tools
Type
array of AiToolRequest
Description
up to 3 items
thinking
Type
object
Description
The reasoning the tier runs with when a request does not choose. null leaves it to the model.
limits
Type
AiLimits
Description
maxSteps
Type
integer
Description
Model calls in the turn, including the one that answers. Tools need at least 2. Default 6.1 to 8
maxOutputTokens
Type
integer
Description
Per model call. Reasoning counts against it. Default 4096.256 to 8192
includeReasoning
Type
boolean
Description
Return the model's reasoning with the answer. It is written for the model, not for people.default false
stream
Type
boolean
Description
Answer as text/event-stream instead of one JSON document, so text arrives as the model writes it. The events are described on the 200 response.default false

AiBudget

AiBudget
Field	Type	Description
keyIdrequired	string
dailyNeuronsrequired	integer, or null	This key's own daily budget. `null` follows the default. `0` switches the key off.
maxConcurrentrequired	integer, or null	This key's own cap on turns in flight. `null` follows the default.
noterequired	string, or null
effectiveDailyNeuronsrequired	integer
effectiveMaxConcurrentrequired	integer
updatedAtrequired	string, date-time, or null
updatedByrequired	string, or null

keyIdrequired
Type
string
Description
dailyNeuronsrequired
Type
integer, or null
Description
This key's own daily budget. null follows the default. 0 switches the key off.
maxConcurrentrequired
Type
integer, or null
Description
This key's own cap on turns in flight. null follows the default.
noterequired
Type
string, or null
Description
effectiveDailyNeuronsrequired
Type
integer
Description
effectiveMaxConcurrentrequired
Type
integer
Description
updatedAtrequired
Type
string, date-time, or null
Description
updatedByrequired
Type
string, or null
Description

AiDayUsage

AiDayUsage
Field	Type	Description
dayrequired	string	A UTC date.
turnsrequired	integer
refusedrequired	integer	Turns refused for the budget or the concurrency cap.
neuronsrequired	number
inputTokensrequired	integer
outputTokensrequired	integer

dayrequired
Type
string
Description
A UTC date.
turnsrequired
Type
integer
Description
refusedrequired
Type
integer
Description
Turns refused for the budget or the concurrency cap.
neuronsrequired
Type
number
Description
inputTokensrequired
Type
integer
Description
outputTokensrequired
Type
integer
Description

AiKeyUsage

AiKeyUsage
Field	Type	Description
keyIdrequired	string
budgetrequired	AiBudget
keyIdrequired	string
dailyNeuronsrequired	integer, or null	This key's own daily budget. `null` follows the default. `0` switches the key off.
maxConcurrentrequired	integer, or null	This key's own cap on turns in flight. `null` follows the default.
noterequired	string, or null
effectiveDailyNeuronsrequired	integer
effectiveMaxConcurrentrequired	integer
updatedAtrequired	string, date-time, or null
updatedByrequired	string, or null
inFlightrequired	integer
todayrequired	AiDayUsage
dayrequired	string	A UTC date.
turnsrequired	integer
refusedrequired	integer	Turns refused for the budget or the concurrency cap.
neuronsrequired	number
inputTokensrequired	integer
outputTokensrequired	integer
daysrequired	array of AiDayUsage	Newest first. Days without a turn are absent.
dayrequired	string	A UTC date.
turnsrequired	integer
refusedrequired	integer	Turns refused for the budget or the concurrency cap.
neuronsrequired	number
inputTokensrequired	integer
outputTokensrequired	integer
lastTurnAtrequired	string, date-time, or null

keyIdrequired
Type
string
Description
budgetrequired
Type
AiBudget
Description
keyIdrequired
Type
string
Description
dailyNeuronsrequired
Type
integer, or null
Description
This key's own daily budget. null follows the default. 0 switches the key off.
maxConcurrentrequired
Type
integer, or null
Description
This key's own cap on turns in flight. null follows the default.
noterequired
Type
string, or null
Description
effectiveDailyNeuronsrequired
Type
integer
Description
effectiveMaxConcurrentrequired
Type
integer
Description
updatedAtrequired
Type
string, date-time, or null
Description
updatedByrequired
Type
string, or null
Description
inFlightrequired
Type
integer
Description
todayrequired
Type
AiDayUsage
Description
dayrequired
Type
string
Description
A UTC date.
turnsrequired
Type
integer
Description
refusedrequired
Type
integer
Description
Turns refused for the budget or the concurrency cap.
neuronsrequired
Type
number
Description
inputTokensrequired
Type
integer
Description
outputTokensrequired
Type
integer
Description
daysrequired
Type
array of AiDayUsage
Description
Newest first. Days without a turn are absent.
dayrequired
Type
string
Description
A UTC date.
turnsrequired
Type
integer
Description
refusedrequired
Type
integer
Description
Turns refused for the budget or the concurrency cap.
neuronsrequired
Type
number
Description
inputTokensrequired
Type
integer
Description
outputTokensrequired
Type
integer
Description
lastTurnAtrequired
Type
string, date-time, or null
Description

AiUsageList

AiUsageList
Field	Type	Description
dayrequired	string
resetsAtrequired	string, date-time	When today's budgets reset: the next midnight UTC.
defaultsrequired	object
dailyNeuronsrequired	integer
maxConcurrentrequired	integer
keysrequired	array of AiKeyUsage	Every key with a turn in the period or a budget of its own, most spent today first.
keyIdrequired	string
budgetrequired	AiBudget
inFlightrequired	integer
todayrequired	AiDayUsage
daysrequired	array of AiDayUsage	Newest first. Days without a turn are absent.
lastTurnAtrequired	string, date-time, or null

dayrequired
Type
string
Description
resetsAtrequired
Type
string, date-time
Description
When today's budgets reset: the next midnight UTC.
defaultsrequired
Type
object
Description
dailyNeuronsrequired
Type
integer
Description
maxConcurrentrequired
Type
integer
Description
keysrequired
Type
array of AiKeyUsage
Description
Every key with a turn in the period or a budget of its own, most spent today first.
keyIdrequired
Type
string
Description
budgetrequired
Type
AiBudget
Description
inFlightrequired
Type
integer
Description
todayrequired
Type
AiDayUsage
Description
daysrequired
Type
array of AiDayUsage
Description
Newest first. Days without a turn are absent.
lastTurnAtrequired
Type
string, date-time, or null
Description

AiAuditEvent

AiAuditEvent
Field	Type	Description
idrequired	string
actorrequired	string
actionrequired	string	one of "budget.updated"
targetTyperequired	string	one of "key"
targetIdrequired	string
targetLabelrequired	string, or null
atrequired	string, date-time
detailrequired	string, or null

idrequired
Type
string
Description
actorrequired
Type
string
Description
actionrequired
Type
string
Description
one of "budget.updated"
targetTyperequired
Type
string
Description
one of "key"
targetIdrequired
Type
string
Description
targetLabelrequired
Type
string, or null
Description
atrequired
Type
string, date-time
Description
detailrequired
Type
string, or null
Description

AiUpdateBudget

AiUpdateBudget
Field	Type	Description
keyIdrequired	string	1 to 64 characters
keyLabel	string, or null	The key's name, recorded with the change so the trail still reads after the key is revoked.1 to 120 characters · default null
dailyNeuronsrequired	integer, or null	0 to 100000000
maxConcurrentrequired	integer, or null	1 to 100
note	string, or null	1 to 280 characters · default null

keyIdrequired
Type
string
Description
1 to 64 characters
keyLabel
Type
string, or null
Description
The key's name, recorded with the change so the trail still reads after the key is revoked.1 to 120 characters · default null
dailyNeuronsrequired
Type
integer, or null
Description
0 to 100000000
maxConcurrentrequired
Type
integer, or null
Description
1 to 100
note
Type
string, or null
Description
1 to 280 characters · default null