{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mammoth-io/json-schema/mammoth-io-agent-chat-request-schema.json",
  "title": "AgentChatRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mammoth-io-agents-api-openapi.yml#/components/schemas/AgentChatRequest",
  "properties": {
    "request_key": {
      "type": "string",
      "maxLength": 128,
      "minLength": 1
    },
    "agent_key": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "maxLength": 80
    },
    "session_id": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "maxLength": 128
    },
    "message": {
      "type": "string",
      "maxLength": 20000,
      "default": ""
    },
    "scope": {
      "$ref": "#/$defs/AgentScope"
    },
    "client_context": {
      "additionalProperties": {},
      "type": "object"
    },
    "selection": {
      "oneOf": [
        {
          "$ref": "#/$defs/AgentSelection"
        },
        {
          "type": "null"
        }
      ]
    },
    "is_system_event": {
      "type": "boolean",
      "default": false
    },
    "email_copy": {
      "type": "boolean",
      "default": true
    },
    "attachments": {
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/DatasetAttachment"
          },
          {
            "$ref": "#/$defs/BiWorkbookAttachment"
          },
          {
            "$ref": "#/$defs/SourceFileAttachment"
          },
          {
            "$ref": "#/$defs/ImageAttachment"
          },
          {
            "$ref": "#/$defs/DocumentAttachment"
          }
        ]
      },
      "type": "array",
      "maxItems": 10
    },
    "plan_ref": {
      "oneOf": [
        {
          "$ref": "#/$defs/PlanRef"
        },
        {
          "type": "null"
        }
      ]
    },
    "credentials": {
      "oneOf": [
        {
          "additionalProperties": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "selected_columns": {
      "oneOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "type": "object",
  "required": [
    "request_key",
    "scope"
  ],
  "$defs": {
    "AgentScope": {
      "properties": {
        "type": {
          "$ref": "#/$defs/ScopeType"
        },
        "workspace_id": {
          "oneOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "user_id": {
          "oneOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object",
      "required": [
        "type"
      ],
      "title": "AgentScope"
    },
    "AgentSelection": {
      "properties": {
        "request_id": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "answers": {
          "oneOf": [
            {
              "additionalProperties": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "widget_id": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "maxLength": 128
        },
        "kind": {
          "oneOf": [
            {
              "$ref": "#/$defs/WidgetKind"
            },
            {
              "type": "null"
            }
          ]
        },
        "value": {}
      },
      "type": "object",
      "required": [],
      "title": "AgentSelection"
    },
    "BiWorkbookAttachment": {
      "properties": {
        "kind": {
          "type": "string",
          "const": "bi_workbook"
        },
        "attachment_id": {
          "type": "integer",
          "exclusiveMinimum": 0.0
        },
        "filename": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1
        },
        "name": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1
        }
      },
      "type": "object",
      "required": [
        "attachment_id",
        "filename",
        "kind",
        "name"
      ],
      "title": "BiWorkbookAttachment"
    },
    "DatasetAttachment": {
      "properties": {
        "dataset_id": {
          "type": "integer",
          "exclusiveMinimum": 0.0
        },
        "name": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1
        },
        "view_id": {
          "oneOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object",
      "required": [
        "dataset_id",
        "name"
      ],
      "title": "DatasetAttachment"
    },
    "DocumentAttachment": {
      "properties": {
        "kind": {
          "type": "string",
          "const": "document"
        },
        "ref": {
          "type": "string"
        },
        "name": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1
        },
        "workspace_id": {
          "oneOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object",
      "required": [
        "kind",
        "name",
        "ref"
      ],
      "title": "DocumentAttachment"
    },
    "ImageAttachment": {
      "properties": {
        "kind": {
          "type": "string",
          "const": "image"
        },
        "ref": {
          "type": "string"
        },
        "name": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1
        }
      },
      "type": "object",
      "required": [
        "kind",
        "name",
        "ref"
      ],
      "title": "ImageAttachment"
    },
    "PlanRef": {
      "properties": {
        "plan_id": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1
        },
        "n": {
          "oneOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "action": {
          "type": [
            "null",
            "string"
          ],
          "enum": [
            "skip",
            "discard",
            "build",
            null
          ]
        },
        "leave_out": {
          "items": {
            "type": "integer"
          },
          "type": "array",
          "maxItems": 20
        }
      },
      "type": "object",
      "required": [
        "plan_id"
      ],
      "title": "PlanRef"
    },
    "ScopeType": {
      "type": "string",
      "enum": [
        "workspace",
        "user",
        "account"
      ],
      "title": "ScopeType",
      "description": "What a chat session is fundamentally scoped to.\n\n``WORKSPACE`` — the most common shape; chat is bound to a single\nworkspace_id (the FE page lives inside that workspace).\n``USER`` — questions about the user themselves (cross-workspace\nprofile, activity, etc.).\n``ACCOUNT`` — questions spanning the user's account-level visibility\n(rarely used; account-scope queries fall back to per-domain\nuser-scoped filters or trigger the required-context hint).\n"
    },
    "SourceFileAttachment": {
      "properties": {
        "kind": {
          "type": "string",
          "const": "source_file"
        },
        "file_id": {
          "type": "integer",
          "exclusiveMinimum": 0.0
        },
        "name": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1
        },
        "reading": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "maxLength": 20
        }
      },
      "type": "object",
      "required": [
        "file_id",
        "kind",
        "name"
      ],
      "title": "SourceFileAttachment"
    },
    "WidgetKind": {
      "type": "string",
      "enum": [
        "CHOICE",
        "NEW_DATA_CHOICE",
        "ADD_DATA",
        "DATA_FINDER",
        "CONNECTOR_CREDENTIAL",
        "CONNECTOR_RECIPE",
        "CONNECTOR_VALIDATE",
        "SAMPLE_PICKER",
        "PUBLIC_DATA_PICKER",
        "PASTE_INPUT",
        "WEBHOOK_SETUP",
        "COMPARE_GATE",
        "COMBINE",
        "COLLECTOR",
        "INTERPRETER",
        "AUTOMATION_CHOICE",
        "AUTOMATION_SCHEDULE",
        "DASHBOARD_OPTIONS",
        "CONNECTOR_SPEC_PREVIEW",
        "DELIVERY_PREVIEW",
        "DELIVERY_TEST_SEND",
        "BUILD_PICKER",
        "ANSWER",
        "CONTACT_SUPPORT",
        "EXPLORE_CARDS",
        "DATA_PROFILE",
        "DASHBOARD_BRIEF",
        "CONNECTOR_DRAFT_CARD"
      ],
      "title": "WidgetKind",
      "description": "Every inline interactive card the agent can attach to a block.\n\nWire values are frozen ``UPPER_SNAKE`` keys mirroring ``WIDGET_KIND`` in the\nfrontend's ``agent-chat.constants.js``; member names deliberately match them\nso the two cannot drift. Every kind is declared even where no rendering\ncomponent exists yet — emitting an unbuilt kind is safe (the card renders\nnothing and the block's prose still shows), but a *misspelled* kind is\nindistinguishable from that, which is why nothing may build one by hand.\n\nThe mapping from this project's design catalog names (``resource_selection``\n→ ``DATA_FINDER``, ``connector_validation`` → ``CONNECTOR_VALIDATE``, …)\nlives in the initiative's contract-reconciliation document, not here.\n"
    }
  }
}