CallIngest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/zelto/main/json-schema/zelto-call-ingest-schema.json",
  "title": "CallIngest",
  "description": "Zelto's canonical call upload shape (`X-Zelto-Provider: zelto`). Provide either `agent.externalId` (find-or-create) or `agentId` (attach to an existing agent).",
  "x-generated": "2026-10-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/zelto-openapi.json#/components/schemas/CallIngest",
  "type": "object",
  "required": [
    "call"
  ],
  "properties": {
    "agent": {
      "type": "object",
      "description": "Find-or-create an agent by your own id. Required unless `agentId` is given.",
      "properties": {
        "externalId": {
          "type": "string",
          "minLength": 1
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Used only when the agent is first created."
        }
      }
    },
    "agentId": {
      "type": "string",
      "format": "uuid",
      "description": "Attach to an existing Zelto agent. Takes precedence over `agent.externalId`."
    },
    "version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Release label of the agent that actually handled this call. Optional for ingestion; send it on every call for reliable experiments. Case-sensitive, 1–255 characters after trimming. The same agent and label reuse a version; a new label creates one on the first processed call. Keep the agent ID stable and change this label for prompt or pipeline changes. Preserve the original label on retries. This is a top-level field, not metadata.version. See /docs/agent-versions."
    },
    "companyExternalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Your stable per-call id for the client or brand this call belongs to. When Companies is enabled, Zelto maps it to a company; otherwise the agent's default company is used when available."
    },
    "call": {
      "type": "object",
      "required": [
        "externalId"
      ],
      "properties": {
        "externalId": {
          "type": "string",
          "minLength": 1,
          "description": "Your call id. Dedup key — re-uploading the same id updates the call in place."
        },
        "startedAt": {
          "type": "string",
          "format": "date-time"
        },
        "endedAt": {
          "type": "string",
          "format": "date-time"
        },
        "durationSeconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Derived from startedAt/endedAt when omitted."
        },
        "endedReason": {
          "type": "string",
          "maxLength": 100
        },
        "cost": {
          "type": "number",
          "minimum": 0,
          "description": "Cost in dollars."
        },
        "recordingUrl": {
          "type": "string",
          "maxLength": 2048
        },
        "recordingUploadId": {
          "type": "string",
          "format": "uuid",
          "description": "Opaque id returned by POST /v1/recording-uploads after direct upload of a local recording. Mutually exclusive with recordingUrl."
        },
        "customer": {
          "type": "object",
          "properties": {
            "number": {
              "type": "string",
              "maxLength": 50,
              "description": "Inbound caller number; used to resolve a receiver."
            },
            "name": {
              "type": "string",
              "maxLength": 255
            }
          }
        }
      }
    },
    "transcript": {
      "type": "object",
      "required": [
        "turns"
      ],
      "properties": {
        "turns": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/CallIngestTurn"
          }
        }
      }
    },
    "systemPrompt": {
      "type": "string",
      "description": "Actual system prompt of the version that handled this call. A leading system transcript turn is used if omitted. Available text is captured when a version is first observed, or fills a missing prompt later; an existing prompt snapshot is not overwritten. A version label alone does not supply a prompt."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Free-form metadata stored on the conversation."
    },
    "versionConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/AgentVersionConfig"
        }
      ],
      "description": "Context for the version that handled this call. Requires the version field. Captured when the version is observed; does not overwrite an existing configuration snapshot. Use config when registering through POST /v1/agents/{id}/versions."
    }
  },
  "$defs": {
    "AgentVersionConfig": {
      "type": "object",
      "additionalProperties": true,
      "description": "Complete version context as a JSON object, up to 64 KiB serialized as UTF-8. Can include llm, stt, tts, tools, workflows, retrieval, and custom settings. Records context only; does not deploy or execute this configuration. Do not include secrets."
    },
    "CallIngestTurn": {
      "type": "object",
      "required": [
        "role",
        "content"
      ],
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "user",
            "assistant",
            "system",
            "tool"
          ]
        },
        "content": {
          "type": "string",
          "minLength": 1
        },
        "startSeconds": {
          "type": "number",
          "minimum": 0
        },
        "endSeconds": {
          "type": "number",
          "minimum": 0
        },
        "words": {
          "type": "array",
          "description": "Optional word-level audio timing used for synchronized transcript playback.",
          "items": {
            "type": "object",
            "required": [
              "word",
              "startSeconds"
            ],
            "properties": {
              "word": {
                "type": "string",
                "minLength": 1
              },
              "startSeconds": {
                "type": "number",
                "minimum": 0
              },
              "endSeconds": {
                "type": "number",
                "minimum": 0
              }
            }
          }
        }
      }
    }
  }
}