{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/codai-ro/json-schema/codai-ro-chat-completion-request-schema.json",
  "title": "Chat completion request",
  "description": "OpenAI Chat Completions body. Unknown fields are accepted (passthrough) and forwarded to OpenAI-compatible upstreams; Anthropic upstreams ignore them.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/codai-ro-gateway-openapi.yml#/components/schemas/ChatCompletionRequest",
  "type": "object",
  "required": [
    "messages"
  ],
  "additionalProperties": true,
  "properties": {
    "model": {
      "type": "string",
      "default": "codai",
      "description": "Logical model. `codai` is the smart router and the only publicly addressable model; any unrecognised name is coerced to `codai`."
    },
    "messages": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20000,
      "description": "Conversation so far. Above 2 000 messages the gateway trims the middle (system head + recent tail kept); above 20 000 the request is rejected with 400.",
      "items": {
        "$ref": "#/$defs/ChatMessage"
      }
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "`true` returns `text/event-stream` chunks. The final usage chunk is always emitted."
    },
    "stream_options": {
      "type": "object",
      "description": "Accepted for OpenAI compatibility; `include_usage` is effectively always on.",
      "properties": {
        "include_usage": {
          "type": "boolean"
        }
      }
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1,
      "description": "Maximum completion tokens (legacy name)."
    },
    "max_completion_tokens": {
      "type": "integer",
      "minimum": 1,
      "description": "Maximum completion tokens (current OpenAI name). Either name is honoured."
    },
    "temperature": {
      "type": "number"
    },
    "top_p": {
      "type": "number"
    },
    "top_k": {
      "type": "integer",
      "description": "codai extension forwarded to Anthropic upstreams."
    },
    "stop": {
      "description": "One stop string or an array of stop strings.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "tools": {
      "type": "array",
      "description": "Function tools. Presence switches the request to the multi-turn loop path (streams are buffered and replayed). A `codai_sandbox` item lets the gateway run bash and Python server-side in an isolated sandbox (see the Sandboxes tag).",
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/ChatTool"
          },
          {
            "$ref": "#/$defs/ChatSandboxTool"
          }
        ]
      }
    },
    "tool_choice": {
      "description": "`auto` | `none` | `required` | `{type: function, function: {name}}`. `required` and named choices are downgraded to `auto` on models that reject forced tool use (Fable 5.x); `none` suppresses tools entirely.",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "auto",
            "none",
            "required"
          ]
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "response_format": {
      "$ref": "#/$defs/ChatResponseFormat"
    },
    "reasoning_effort": {
      "type": "string",
      "enum": [
        "minimal",
        "low",
        "medium",
        "high",
        "max"
      ],
      "description": "Test-time-compute effort tier (OpenAI vocabulary plus codai `max`; `none` accepted as `minimal`). The `x-codai-effort` header wins when both are present."
    },
    "n": {
      "type": "integer",
      "description": "Accepted for compatibility and forwarded only to OpenAI-compatible upstreams; codai always returns a single choice."
    },
    "user": {
      "type": "string",
      "maxLength": 255,
      "description": "End-user identifier. When no `x-codai-session-id` header is present a non-empty `user` under 256 chars is used as the session id."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Accepted for compatibility (passthrough); not interpreted by the gateway."
    }
  },
  "$defs": {
    "ChatContentPart": {
      "title": "Chat content part",
      "description": "One part of a multi-part message content array. Only `text` and `image_url` parts are interpreted; other part types are dropped by the provider translation.",
      "oneOf": [
        {
          "type": "object",
          "required": [
            "type",
            "text"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "text"
              ]
            },
            "text": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "type",
            "image_url"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "image_url"
              ]
            },
            "image_url": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "description": "HTTPS URL or `data:image/...;base64,...` URI."
                }
              }
            }
          }
        }
      ]
    },
    "ChatMessage": {
      "title": "Chat message",
      "description": "OpenAI chat message. `content` is a string or an array of content parts; assistant messages may carry `tool_calls`, `tool` messages must carry `tool_call_id`.",
      "type": "object",
      "required": [
        "role"
      ],
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "system",
            "developer",
            "user",
            "assistant",
            "tool",
            "function"
          ]
        },
        "content": {
          "description": "Message text, or an array of text / image_url parts. May be `null` on assistant messages that only carry `tool_calls`.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ChatContentPart"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "name": {
          "type": "string"
        },
        "tool_call_id": {
          "type": "string",
          "description": "Required on `tool` messages — the id of the call being answered."
        },
        "tool_calls": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChatToolCall"
          }
        }
      }
    },
    "ChatResponseFormat": {
      "title": "Chat response format",
      "description": "Structured-output control. `json_object` / `json_schema` inject a system instruction and validate the output at serve time; `json_schema` also carries the schema.",
      "type": "object",
      "required": [
        "type"
      ],
      "additionalProperties": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "text",
            "json_object",
            "json_schema"
          ]
        },
        "json_schema": {
          "type": "object",
          "description": "Only for `type: json_schema`.",
          "properties": {
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "schema": {
              "type": "object",
              "additionalProperties": true
            },
            "strict": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "ChatSandboxTool": {
      "title": "codai sandbox tool",
      "description": "Server-side tool: the gateway replaces it with `sandbox_bash`, `sandbox_python`, `sandbox_edit` and `sandbox_files`, runs them in one sandbox per `x-codai-session-id` (1 h sliding TTL) and appends `codai_sandbox.artifacts` plus signed links to the final message. Needs tool level `l3_sandbox`.",
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "codai_sandbox"
          ]
        },
        "egress": {
          "$ref": "#/$defs/SandboxEgress"
        },
        "template": {
          "type": "string",
          "enum": [
            "codai-base"
          ]
        }
      }
    },
    "ChatTool": {
      "title": "Chat tool definition",
      "type": "object",
      "required": [
        "type",
        "function"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "function"
          ]
        },
        "function": {
          "type": "object",
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "parameters": {
              "type": "object",
              "description": "JSON Schema of the arguments object.",
              "additionalProperties": true
            }
          }
        }
      }
    },
    "ChatToolCall": {
      "title": "Chat tool call",
      "type": "object",
      "required": [
        "id",
        "type",
        "function"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "function"
          ]
        },
        "function": {
          "type": "object",
          "required": [
            "name",
            "arguments"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "arguments": {
              "type": "string",
              "description": "JSON-encoded arguments string."
            }
          }
        }
      }
    },
    "SandboxEgress": {
      "title": "Sandbox egress policy",
      "description": "Outbound network, on both backends. `none` (default) has no network at all; `allowlist` lets HTTPS reach at most 20 domains through the codai egress proxy (no IP literals, no internal hosts); `preset` opens a curated list (`pypi`, `npm`). The proxy opens plain tunnels and never injects credentials; v2 forks inherit the parent policy.",
      "oneOf": [
        {
          "type": "object",
          "title": "No network",
          "required": [
            "mode"
          ],
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "none"
              ]
            }
          }
        },
        {
          "type": "object",
          "title": "Domain allowlist",
          "required": [
            "mode",
            "domains"
          ],
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "allowlist"
              ]
            },
            "domains": {
              "type": "array",
              "minItems": 1,
              "maxItems": 20,
              "items": {
                "type": "string",
                "maxLength": 253
              },
              "description": "Host names, e.g. `api.anaf.ro`."
            }
          }
        },
        {
          "type": "object",
          "title": "Preset",
          "required": [
            "mode",
            "preset"
          ],
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "preset"
              ]
            },
            "preset": {
              "type": "string",
              "enum": [
                "pypi",
                "npm"
              ]
            }
          }
        }
      ]
    }
  }
}