{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/roark/json-schema/roark-agent-version-response-schema.json",
  "title": "AgentVersionResponse",
  "description": "One version of a Roark-hosted agent's configuration. Null settings use the runtime default.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/roark-agent-api-openapi.yml#/components/schemas/AgentVersionResponse",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "agentId": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "DRAFT",
        "PUBLISHED",
        "DISCARDED"
      ],
      "description": "DRAFT while being edited, PUBLISHED once it has been live."
    },
    "versionNumber": {
      "type": [
        "integer",
        "null"
      ],
      "description": "v1, v2, ... assigned on publish; null on a draft."
    },
    "revision": {
      "type": "integer",
      "description": "Increases with every edit to a draft. Send it back as expectedRevision when you publish."
    },
    "baseVersionId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The published version a draft started from."
    },
    "rolledBackFromVersionId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Set when this version rolls the agent back to an older one."
    },
    "summary": {
      "type": [
        "string",
        "null"
      ],
      "description": "What changed, written on publish."
    },
    "createdByType": {
      "type": "string",
      "enum": [
        "USER",
        "API",
        "CONFIG",
        "AUTOIMPROVE",
        "INTEGRATION",
        "SYSTEM"
      ]
    },
    "createdById": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "publishedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601."
    },
    "publishedByType": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "USER",
        "API",
        "CONFIG",
        "AUTOIMPROVE",
        "INTEGRATION",
        "SYSTEM"
      ]
    },
    "publishedById": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "createdAt": {
      "type": "string",
      "description": "ISO 8601."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO 8601."
    },
    "modalities": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "call",
          "chat"
        ]
      },
      "description": "Whether the agent takes calls, chats, or both."
    },
    "language": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 639-1, e.g. en."
    },
    "firstMessageMode": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "SPEAK_TEXT",
        "PLAY_AUDIO",
        "WAIT_FOR_CALLER"
      ]
    },
    "firstMessage": {
      "type": [
        "string",
        "null"
      ],
      "description": "What the agent says first, with firstMessageMode SPEAK_TEXT."
    },
    "firstMessageAudioUrl": {
      "type": [
        "string",
        "null"
      ],
      "description": "The audio a call opens with, with firstMessageMode PLAY_AUDIO."
    },
    "llmProvider": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "OPENAI",
        "ANTHROPIC",
        "GOOGLE",
        "XAI",
        "ULTRAVOX",
        "AWS",
        "ELEVENLABS"
      ]
    },
    "llmModel": {
      "type": [
        "string",
        "null"
      ],
      "description": "Any model id the provider accepts. One model serves every speaker."
    },
    "llmTemperature": {
      "type": [
        "number",
        "null"
      ],
      "description": "0 to 2."
    },
    "llmMaxTokens": {
      "type": [
        "integer",
        "null"
      ]
    },
    "llmBackendModel": {
      "type": [
        "string",
        "null"
      ],
      "description": "OpenAI Live models only: the text model they delegate to."
    },
    "llmVoice": {
      "type": [
        "string",
        "null"
      ],
      "description": "Speech-to-speech models only: the model's own voice."
    },
    "sttProvider": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "DEEPGRAM",
        "OPENAI_WHISPER",
        "SPEECHMATICS",
        "ASSEMBLYAI",
        "ELEVENLABS"
      ]
    },
    "sttModel": {
      "type": [
        "string",
        "null"
      ]
    },
    "sttKeyterms": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Words and phrases the transcriber should listen for."
    },
    "sttSmartFormat": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "sttEndpointingMs": {
      "type": [
        "integer",
        "null"
      ]
    },
    "sttTurnDetection": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "pipeline",
        "provider"
      ]
    },
    "interruptionMode": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "ALLOW",
        "BLOCK"
      ]
    },
    "vadStartSecs": {
      "type": [
        "number",
        "null"
      ]
    },
    "vadStopSecs": {
      "type": [
        "number",
        "null"
      ]
    },
    "callMaxDurationSeconds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "callSilenceTimeoutSeconds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "idleTimeoutSeconds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "idleMaxCount": {
      "type": [
        "integer",
        "null"
      ]
    },
    "idleMessages": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "endDetectionPhrases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Phrases that end the call when the caller says them, matched anywhere in what they say."
    },
    "endDetectionReasons": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "When the agent may decide to end the call itself."
    },
    "endCallGoodbyeMessage": {
      "type": [
        "string",
        "null"
      ]
    },
    "backgroundNoise": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "NONE",
        "AIRPORT",
        "CHILDREN_PLAYING",
        "CITY",
        "COFFEE_SHOP",
        "CONSTRUCTION",
        "CRYING_BABY",
        "DRIVING",
        "LIBRARY",
        "OFFICE",
        "THUNDERSTORM",
        "TRAIN"
      ],
      "description": "A background preset."
    },
    "backgroundNoiseUrl": {
      "type": [
        "string",
        "null"
      ],
      "description": "A custom background recording, instead of a preset."
    },
    "backgroundNoiseVolume": {
      "type": [
        "number",
        "null"
      ],
      "description": "0 to 1."
    },
    "chatMaxDurationSeconds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "chatInactivityTimeoutSeconds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "subAgents": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentVersionSubAgent"
      },
      "description": "The main agent (key `main`) first, then the sub-agents it can hand the call to."
    },
    "issues": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentVersionIssue"
      },
      "description": "Why this version cannot run; empty when it can be published. Returned when reading one version."
    }
  },
  "required": [
    "id",
    "agentId",
    "status",
    "versionNumber",
    "revision",
    "baseVersionId",
    "rolledBackFromVersionId",
    "summary",
    "createdByType",
    "createdById",
    "publishedAt",
    "publishedByType",
    "publishedById",
    "createdAt",
    "updatedAt",
    "modalities",
    "language",
    "firstMessageMode",
    "firstMessage",
    "firstMessageAudioUrl",
    "llmProvider",
    "llmModel",
    "llmTemperature",
    "llmMaxTokens",
    "llmBackendModel",
    "llmVoice",
    "sttProvider",
    "sttModel",
    "sttKeyterms",
    "sttSmartFormat",
    "sttEndpointingMs",
    "sttTurnDetection",
    "interruptionMode",
    "vadStartSecs",
    "vadStopSecs",
    "callMaxDurationSeconds",
    "callSilenceTimeoutSeconds",
    "idleTimeoutSeconds",
    "idleMaxCount",
    "idleMessages",
    "endDetectionPhrases",
    "endDetectionReasons",
    "endCallGoodbyeMessage",
    "backgroundNoise",
    "backgroundNoiseUrl",
    "backgroundNoiseVolume",
    "chatMaxDurationSeconds",
    "chatInactivityTimeoutSeconds",
    "subAgents"
  ],
  "$defs": {
    "AgentVersionHandoff": {
      "type": "object",
      "properties": {
        "to": {
          "type": "string",
          "description": "The key of the sub-agent that takes over; `main` for the main agent."
        },
        "description": {
          "type": "string",
          "description": "When to hand off, in the words the model is given."
        },
        "once": {
          "type": "boolean",
          "description": "At most once per call."
        },
        "history": {
          "type": "string",
          "enum": [
            "SHARED",
            "NONE"
          ],
          "description": "SHARED: the new speaker hears the conversation so far. NONE: it starts fresh."
        },
        "note": {
          "type": [
            "string",
            "null"
          ],
          "description": "Added to the new speaker's prompt at the handoff, such as a warm-transfer brief."
        }
      },
      "required": [
        "to",
        "description",
        "once",
        "history",
        "note"
      ]
    },
    "AgentVersionIssue": {
      "type": "object",
      "properties": {
        "field": {
          "type": "string",
          "description": "The setting the issue is about."
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "field",
        "message"
      ],
      "description": "Something that stops a version from running."
    },
    "AgentVersionSubAgent": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "`main` for the main agent; otherwise letters, digits, `_` or `-`."
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "How the agent refers to this speaker."
        },
        "systemPrompt": {
          "type": [
            "string",
            "null"
          ],
          "description": "The speaker's prompt."
        },
        "isInitial": {
          "type": "boolean",
          "description": "The call opens as this sub-agent instead of the main agent."
        },
        "ttsProvider": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "CARTESIA",
            "ELEVENLABS",
            "OPENAI",
            "RIME"
          ]
        },
        "ttsModel": {
          "type": [
            "string",
            "null"
          ]
        },
        "ttsVoiceId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Any voice id the provider accepts, including your own voices."
        },
        "ttsSpeed": {
          "type": [
            "number",
            "null"
          ],
          "description": "0.5 to 2."
        },
        "ttsStability": {
          "type": [
            "number",
            "null"
          ],
          "description": "0 to 1, ElevenLabs."
        },
        "ttsSimilarityBoost": {
          "type": [
            "number",
            "null"
          ],
          "description": "0 to 1, ElevenLabs."
        },
        "tools": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentVersionTool"
          }
        },
        "handoffs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentVersionHandoff"
          }
        }
      },
      "required": [
        "key",
        "name",
        "systemPrompt",
        "isInitial",
        "ttsProvider",
        "ttsModel",
        "ttsVoiceId",
        "ttsSpeed",
        "ttsStability",
        "ttsSimilarityBoost",
        "tools",
        "handoffs"
      ],
      "description": "A speaker in the conversation. On a sub-agent, null voice settings use the main agent's."
    },
    "AgentVersionTool": {
      "type": "object",
      "properties": {
        "toolDefinitionId": {
          "type": "string",
          "format": "uuid"
        },
        "pinnedVersion": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The tool version the agent runs; null runs the tool's latest declared version."
        }
      },
      "required": [
        "toolDefinitionId",
        "pinnedVersion"
      ]
    }
  }
}