IngestPayload

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/okareo/json-schema/okareo-ingest-payload-schema.json",
  "title": "IngestPayload",
  "description": "Top-level ingest request with project context.\n\nThis is the monitoring path - conversations are ingested and monitored\nbased on filter groups, not associated with a specific MUT like test runs.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/okareo-monitoring-api-openapi.yml#/components/schemas/IngestPayload",
  "properties": {
    "project_id": {
      "type": "string",
      "format": "uuid",
      "title": "Project Id",
      "description": "Okareo project ID"
    },
    "mut_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mut Id",
      "description": "Optional model under test ID. If not provided, datapoints are created without a MUT association (monitoring path)."
    },
    "conversations": {
      "items": {
        "$ref": "#/$defs/ConversationIngestRequest"
      },
      "type": "array",
      "title": "Conversations",
      "description": "List of conversations to ingest (1+)"
    }
  },
  "type": "object",
  "required": [
    "project_id",
    "conversations"
  ],
  "$defs": {
    "ConversationAudio": {
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "url",
            "voice_file_id",
            "inline_b64"
          ],
          "title": "Type",
          "description": "Audio reference type"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Url",
          "description": "Externally hosted audio URL when type='url'"
        },
        "voice_file_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Voice File Id",
          "description": "Existing Okareo voice file identifier when type='voice_file_id'"
        },
        "inline_b64": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Inline B64",
          "description": "Base64-encoded audio bytes when type='inline_b64'"
        }
      },
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ConversationAudio",
      "description": "Audio attachment for a conversation ingest request."
    },
    "ConversationIngestRequest": {
      "properties": {
        "call_id": {
          "type": "string",
          "title": "Call Id",
          "description": "Platform-specific call identifier"
        },
        "context_token": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Context Token",
          "description": "Optional context token for correlation. Defaults to call_id if not provided."
        },
        "conversation_start_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Conversation Start At",
          "description": "Absolute conversation start timestamp in UTC. Use this with per-turn timestamp_ms values to derive wall-clock message times."
        },
        "audio": {
          "anyOf": [
            {
              "$ref": "#/$defs/ConversationAudio"
            },
            {
              "type": "null"
            }
          ],
          "description": "Audio reference for the conversation. Prefer URL or voice_file_id over inline base64."
        },
        "recording_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Recording Url",
          "description": "Legacy compatibility field. Prefer audio={type:'url', url: ...}."
        },
        "recording_bytes_b64": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Recording Bytes B64",
          "description": "Legacy compatibility field. Prefer audio={type:'inline_b64', inline_b64: ...}."
        },
        "transcript": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/ConversationTurn"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Transcript",
          "description": "Pre-parsed transcript as a list of turns. Optional for audio-only sources."
        },
        "diarization": {
          "type": "boolean",
          "title": "Diarization",
          "description": "When transcript is absent, run diarization + ASR on the audio before creating the datapoint.",
          "default": true
        },
        "metadata": {
          "additionalProperties": true,
          "type": "object",
          "title": "Metadata",
          "description": "Platform-specific metadata"
        },
        "tags": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Tags",
          "description": "Tags for monitor matching"
        },
        "first_turn": {
          "type": "string",
          "title": "First Turn",
          "description": "For audio-only diarization: 'user' or 'assistant' spoke first",
          "default": "assistant"
        }
      },
      "type": "object",
      "required": [
        "call_id"
      ],
      "title": "ConversationIngestRequest",
      "description": "Request payload for ingesting voice conversations."
    },
    "ConversationTurn": {
      "properties": {
        "role": {
          "type": "string",
          "title": "Role",
          "description": "Speaker role: 'user' or 'assistant'"
        },
        "content": {
          "type": "string",
          "title": "Content",
          "description": "Text content of the utterance"
        },
        "timestamp_ms": {
          "type": "integer",
          "title": "Timestamp Ms",
          "description": "Timestamp in milliseconds from conversation start",
          "default": 0
        }
      },
      "type": "object",
      "required": [
        "role",
        "content"
      ],
      "title": "ConversationTurn",
      "description": "A single turn in a conversation (user or assistant utterance)."
    }
  }
}