TurnRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/amigo/main/json-schema/amigo-turn-request-schema.json",
  "title": "TurnRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/amigo-conversations-api-openapi.yml#/components/schemas/TurnRequest",
  "properties": {
    "message": {
      "type": "string",
      "maxLength": 10000,
      "title": "Message",
      "default": ""
    },
    "content": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/ContentPartPayload"
          },
          "type": "array",
          "maxItems": 20
        },
        {
          "type": "null"
        }
      ],
      "title": "Content"
    },
    "media_url": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2048
        },
        {
          "type": "null"
        }
      ],
      "title": "Media Url"
    },
    "media_type": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 128
        },
        {
          "type": "null"
        }
      ],
      "title": "Media Type"
    },
    "context": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100000
        },
        {
          "type": "null"
        }
      ],
      "title": "Context",
      "description": "Injected into the agent's prompt as caller/patient context for this turn."
    },
    "viewport_width": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 500.0,
          "minimum": 20.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Viewport Width"
    },
    "viewport_height": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 500.0,
          "minimum": 5.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Viewport Height"
    },
    "wait_for_final": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Wait For Final",
      "description": "Synchronous callers only: when a turn hands work to a background tool (``background_pending``), await the real answer inline (bounded, ~30s) instead of returning the acknowledgement immediately. On completion the response carries the final answer with ``background_pending=false``; on timeout it returns ``background_pending=true`` — resolve it later with ``poll=true``. ``null`` (default) inherits the channel policy (web = do not wait). Ignored with ``poll=true`` (422)."
    },
    "suppress_filler": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Suppress Filler",
      "description": "Synchronous callers only: when a turn ends ``background_pending``, omit the filler/acknowledgement text from ``output`` so a batch caller never mistakes the ack for the answer (``output`` is empty; ``background_pending=true`` is the poll-later signal). ``null`` (default) inherits the channel policy. Ignored with ``poll=true`` (422)."
    }
  },
  "type": "object",
  "$defs": {
    "ContentPartPayload": {
      "properties": {
        "type": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1,
          "pattern": "^[a-z][a-z0-9._-]*$",
          "title": "Type",
          "default": "text"
        },
        "text": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 10000
            },
            {
              "type": "null"
            }
          ],
          "title": "Text"
        },
        "url": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 2048
            },
            {
              "type": "null"
            }
          ],
          "title": "Url"
        },
        "media_type": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 128
            },
            {
              "type": "null"
            }
          ],
          "title": "Media Type"
        },
        "provider_id": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 256
            },
            {
              "type": "null"
            }
          ],
          "title": "Provider Id"
        },
        "metadata": {
          "additionalProperties": true,
          "type": "object",
          "maxProperties": 50,
          "title": "Metadata"
        }
      },
      "type": "object",
      "title": "ContentPartPayload",
      "description": "HTTP/WebSocket shape for a modality-neutral conversation content part."
    }
  }
}