> ## Documentation Index > Fetch the complete documentation index at: https://docs.video2ctx.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get a durable agent run > Reads the current status and, once complete, the persisted result from the conversation-scoped Durable Object. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agent/{sessionId}/runs/{runId} openapi: 3.1.0 info: title: video2ctx API version: 1.0.0 license: name: Apache License 2.0 identifier: Apache-2.0 description: >- Consumer-facing contract for the hosted video2ctx API. First-party application and operator routes are documented separately at https://docs.video2ctx.dev/internals/overview. servers: - url: https://api.video2ctx.dev description: Hosted video2ctx API security: [] tags: - name: System description: Service status and machine-readable documentation. - name: Authentication description: Better Auth entry points used by the web application. - name: Providers description: Supported external video providers and their capabilities. - name: Discovery description: Search, browse, and trend research. - name: Videos description: Video metadata and evidence. - name: Channels description: Channel inspection. - name: Playlists description: Playlist inspection. - name: Projects description: Private research projects and saved material. - name: Research description: Imports, jobs, cited answers, comparisons, and reports. - name: Agents description: >- Durable agent runs and results. Feature-flagged; access is restricted to verified, allowlisted tester accounts during the initial rollout. - name: Exports description: Project export creation and download. - name: Monitoring description: Monitors, notifications, and digest preferences. - name: Billing description: Plan, credit, and subscription status. - name: Account description: Account lifecycle operations. paths: /v1/agent/{sessionId}/runs/{runId}: get: tags: - Agents summary: Get a durable agent run description: >- Reads the current status and, once complete, the persisted result from the conversation-scoped Durable Object. operationId: getAgentRun parameters: - name: sessionId in: path required: true description: Session UUID returned by agent admission. schema: type: string minLength: 1 - name: runId in: path required: true description: Agent run UUID returned by agent admission. schema: type: string minLength: 1 - name: responseFormat in: query required: false description: >- Compact is the default: answer, deduplicated sources, outcome, and top-level billing. Use legacy explicitly for the previous detailed format. Applies only to this HTTP response. Does not change execution. schema: type: string enum: - legacy - compact default: compact - name: include in: query required: false description: >- Optional comma-separated details: artifacts,evidence,diagnostics. Requires responseFormat=compact. Evidence sourceId points to result.sources[].id. Details are omitted unless requested. schema: type: string maxLength: 100 example: evidence,diagnostics responses: '200': description: >- Current agent run state. Compact results distinguish answered, partial, insufficient_evidence, needs_clarification, and rejected; completed describes execution, not evidence quality or scope acceptance. content: application/json: schema: oneOf: - $ref: '#/components/schemas/AgentRun' - $ref: '#/components/schemas/CompactAgentRun' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerApiKey: [] - sessionCookie: [] - cliSession: [] - apiKey: [] - demoUser: [] components: schemas: AgentRun: allOf: - $ref: '#/components/schemas/AgentRunReceipt' - type: object properties: route: $ref: '#/components/schemas/AgentRouteDecision' result: $ref: '#/components/schemas/AgentTurnResult' error: type: string extractionDiagnostics: maxItems: 64 type: array items: type: object properties: version: type: number enum: - 1 kind: type: string enum: - storyboard - frames - transcript videoId: type: string pattern: ^[A-Za-z0-9_-]{11}$ extractionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ attempt: type: integer minimum: 1 maximum: 5 slot: type: integer minimum: 0 maximum: 3 backend: type: string enum: - worker - container egress: type: string enum: - direct - proxy recordedAt: type: integer minimum: 0 maximum: 9007199254740991 elapsedMs: type: number minimum: 0 maximum: 9007199254740991 status: type: integer minimum: 100 maximum: 599 outcome: type: string enum: - success - failed - fallback - transport_error failureKind: type: string enum: - timeout - canceled - transport - invalid_response - upstream capture: type: string enum: - available - missing - invalid - unavailable events: maxItems: 64 type: array items: type: object properties: stage: type: string enum: - player - player_response - download - complete - request - image_normalized - caption_metadata - caption_retry - media_candidates - media_http - media_transfer - media_retry - media_retry_skipped - ffmpeg - ffmpeg_success profile: type: string enum: - IOS - ANDROID_VR - MWEB - WEB - ios - android - android_vr - mweb - web outcome: type: string enum: - selected - skipped - error - success playabilityStatus: type: string enum: - OK - LOGIN_REQUIRED - UNPLAYABLE - ERROR - LIVE_STREAM_OFFLINE - CONTENT_CHECK_REQUIRED - AGE_CHECK_REQUIRED - UNKNOWN specState: type: string enum: - valid - missing - malformed code: type: string enum: - INVALID_INPUT - INVALID_RESPONSE - NOT_FOUND - CAPTIONS_UNAVAILABLE - UNAVAILABLE - UPSTREAM_ERROR - AUTH_REQUIRED - RATE_LIMITED - FRAME_EXTRACTION_FAILED - FRAME_TIMEOUT - FRAME_CANCELLED - MEDIA_UNAVAILABLE - UNKNOWN inputFormat: type: string enum: - webp - jpeg outputFormat: type: string enum: - webp - jpeg status: type: integer minimum: 100 maximum: 599 elapsedMs: type: number minimum: 0 maximum: 9007199254740991 timestampMs: type: integer minimum: 0 maximum: 9007199254740991 candidateIndex: type: integer minimum: 0 maximum: 9007199254740991 candidateCount: type: integer minimum: 0 maximum: 9007199254740991 attempt: type: integer minimum: 0 maximum: 9007199254740991 delayMs: type: number minimum: 0 maximum: 9007199254740991 sheetCount: type: integer minimum: 0 maximum: 9007199254740991 width: type: integer minimum: 0 maximum: 9007199254740991 height: type: integer minimum: 0 maximum: 9007199254740991 sourceWidth: type: integer minimum: 0 maximum: 9007199254740991 sourceHeight: type: integer minimum: 0 maximum: 9007199254740991 formatId: type: integer minimum: 0 maximum: 9007199254740991 inputBytes: type: integer minimum: 0 maximum: 9007199254740991 outputBytes: type: integer minimum: 0 maximum: 9007199254740991 exitCode: type: integer minimum: -255 maximum: 255 required: - stage additionalProperties: false droppedEvents: type: integer minimum: 0 maximum: 9007199254740991 toolCallId: type: string minLength: 1 maxLength: 300 required: - version - kind - videoId - extractionId - attempt - slot - recordedAt - elapsedMs - outcome - capture - events - droppedEvents - toolCallId additionalProperties: false extractionDiagnosticsTruncated: type: boolean transcriptDiagnostics: type: array items: type: object properties: version: type: number enum: - 1 stage: type: string enum: - transcript_analysis videoId: type: string pattern: ^[A-Za-z0-9_-]{11}$ modelCallId: type: string maxLength: 500 attemptId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ attempt: type: integer minimum: 1 maximum: 2 recordedAt: type: number outcome: type: string enum: - started - rejected - accepted - failed - canceled elapsedMs: type: number minimum: 0 code: type: string enum: - GROUNDING_REJECTED - INVALID_REFERENCE - OUTPUT_LIMIT - SCHEMA_INVALID - PROVIDER_ERROR - ANALYSIS_ERROR - ANALYSIS_TIMEOUT - CANCELED finishReason: type: string maxLength: 50 modelId: type: string maxLength: 200 inputTokens: type: number minimum: 0 outputTokens: type: number minimum: 0 cancellationReason: type: string maxLength: 50 statusCode: type: number issues: maxItems: 100 type: array items: type: object properties: code: type: string enum: - ENTITY_NOT_SUPPORTED - QUANTITY_NOT_SUPPORTED - UNIT_NOT_EXPLICIT - UNIT_MISMATCH - BASIS_NOT_SUPPORTED - UNCERTAINTY_MISSING - CLAIM_QUANTITY_NOT_SUPPORTED - UNKNOWN_WINDOW - OUTPUT_LIMIT - SCHEMA_INVALID findingIndex: description: Zero-based index in the rejected model output. type: integer minimum: 0 maximum: 9007199254740991 fieldIndex: type: integer minimum: 0 maximum: 9007199254740991 windowIndex: type: integer minimum: 0 maximum: 9007199254740991 message: type: string maxLength: 1000 required: - code - message additionalProperties: false issueCount: type: integer minimum: 0 maximum: 9007199254740991 repairFeedback: type: string maxLength: 4000 rejectedOutput: type: string maxLength: 24000 sourceContext: type: object properties: title: type: string maxLength: 500 channel: type: string maxLength: 300 additionalProperties: false sourceWindows: maxItems: 15 type: array items: type: object properties: index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 startMs: type: number endMs: type: number text: type: string maxLength: 2000 required: - index - startMs - endMs - text additionalProperties: false captureTruncated: type: boolean required: - version - stage - videoId - modelCallId - attemptId - attempt - recordedAt - outcome - elapsedMs additionalProperties: false CompactAgentRun: type: object properties: runId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ agentMessageId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string enum: - pending - running - completed - failed - cancelled request: description: >- Original stored user message for this run, not a model-generated restatement. type: object properties: message: type: string maxLength: 10000 required: - message additionalProperties: false sessionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ result: type: object properties: coverage: type: object properties: targetVideos: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 reviewedVideos: type: integer minimum: 0 maximum: 9007199254740991 requiredVideos: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - targetVideos - reviewedVideos additionalProperties: false outcome: type: string enum: - answered - partial - insufficient_evidence - needs_clarification - rejected description: >- Answer availability based on routing intent and persisted evidence warnings. Rejected means outside supported YouTube video research and synthesis. This is not a factual-confidence score. answer: type: string sources: type: array items: type: object properties: id: type: string description: Source number used by [1] references in this answer. videoId: type: string channelId: type: string playlistId: type: string title: type: string url: type: string format: uri required: - id - title additionalProperties: false warnings: type: array items: type: object properties: videoId: description: Video to which this source-specific caveat applies. type: string pattern: ^[A-Za-z0-9_-]{11}$ code: type: string minLength: 1 maxLength: 100 message: type: string minLength: 1 maxLength: 1000 required: - code - message additionalProperties: false artifacts: type: array items: type: object properties: type: type: string minLength: 1 maxLength: 100 title: type: string minLength: 1 maxLength: 500 data: type: object additionalProperties: {} required: - type - data additionalProperties: false evidence: description: >- Requested excerpts with original citation ids and timestamps. sourceId refers to the numbered source in this result. type: array items: type: object properties: id: type: string minLength: 1 maxLength: 300 sourceId: type: string minLength: 1 maxLength: 300 provider: type: string enum: - youtube videoId: type: string maxLength: 100 channelId: type: string maxLength: 200 playlistId: type: string maxLength: 200 title: type: string maxLength: 1000 url: type: string format: uri excerpt: type: string minLength: 1 maxLength: 2000 startMs: type: integer minimum: 0 maximum: 9007199254740991 endMs: type: integer minimum: 0 maximum: 9007199254740991 required: - id - sourceId - provider - excerpt additionalProperties: false required: - outcome - answer - sources - warnings additionalProperties: false billing: type: object properties: creditsCharged: type: integer minimum: 0 maximum: 9007199254740991 creditsRemaining: type: integer minimum: 0 maximum: 9007199254740991 required: - creditsCharged - creditsRemaining additionalProperties: false error: type: string diagnostics: type: object properties: userMessageId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ conversationTurn: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 modelStepCount: type: integer minimum: 0 maximum: 9007199254740991 toolCallCount: type: integer minimum: 0 maximum: 9007199254740991 route: oneOf: - type: object properties: route: type: string enum: - topic_research researchVideoCount: type: integer minimum: 1 maximum: 8 requiredVideoCount: type: integer minimum: 1 maximum: 100 researchBreadth: type: string enum: - focused - comparative searchQuery: type: string minLength: 1 maxLength: 500 channelId: type: string minLength: 1 maxLength: 200 pattern: ^(?:UC[A-Za-z0-9_-]{22}|@[A-Za-z0-9_.-]+)$ useStoryboard: type: boolean refreshEvidence: type: boolean refreshDynamicData: type: boolean answerDetail: type: string enum: - standard - detailed comparisonVideoIds: minItems: 2 maxItems: 8 type: array items: type: string pattern: ^[A-Za-z0-9_-]{11}$ numberedItemCount: type: integer minimum: 1 maximum: 100 required: - route additionalProperties: false - type: object properties: route: type: string enum: - inspect_video researchVideoCount: type: number enum: - 1 videoId: type: string pattern: ^[A-Za-z0-9_-]{11}$ useStoryboard: type: boolean refreshEvidence: type: boolean refreshDynamicData: type: boolean answerDetail: type: string enum: - standard - detailed comparisonVideoIds: minItems: 2 maxItems: 8 type: array items: type: string pattern: ^[A-Za-z0-9_-]{11}$ numberedItemCount: type: integer minimum: 1 maximum: 100 required: - route - videoId additionalProperties: false - type: object properties: route: type: string enum: - clarification question: type: string minLength: 1 maxLength: 1000 required: - route - question additionalProperties: false - type: object properties: route: type: string enum: - rejected reason: type: string minLength: 1 maxLength: 1000 required: - route - reason additionalProperties: false - type: object properties: route: type: string enum: - finalize responseIntent: type: string enum: - context_answer - clarification - rejected contextScope: type: string enum: - history - video - mixed historySelection: type: string enum: - first_user_message - all_user_messages - relevant_messages reason: type: string minLength: 1 maxLength: 1000 answerDetail: type: string enum: - standard - detailed comparisonVideoIds: minItems: 2 maxItems: 8 type: array items: type: string pattern: ^[A-Za-z0-9_-]{11}$ numberedItemCount: type: integer minimum: 1 maximum: 100 required: - route - responseIntent - reason additionalProperties: false transcriptAnalysis: type: array items: type: object properties: version: type: number enum: - 1 stage: type: string enum: - transcript_analysis videoId: type: string pattern: ^[A-Za-z0-9_-]{11}$ modelCallId: type: string maxLength: 500 attemptId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ attempt: type: integer minimum: 1 maximum: 2 recordedAt: type: number outcome: type: string enum: - started - rejected - accepted - failed - canceled elapsedMs: type: number minimum: 0 code: type: string enum: - GROUNDING_REJECTED - INVALID_REFERENCE - OUTPUT_LIMIT - SCHEMA_INVALID - PROVIDER_ERROR - ANALYSIS_ERROR - ANALYSIS_TIMEOUT - CANCELED finishReason: type: string maxLength: 50 modelId: type: string maxLength: 200 inputTokens: type: number minimum: 0 outputTokens: type: number minimum: 0 cancellationReason: type: string maxLength: 50 statusCode: type: number issues: maxItems: 100 type: array items: type: object properties: code: type: string enum: - ENTITY_NOT_SUPPORTED - QUANTITY_NOT_SUPPORTED - UNIT_NOT_EXPLICIT - UNIT_MISMATCH - BASIS_NOT_SUPPORTED - UNCERTAINTY_MISSING - CLAIM_QUANTITY_NOT_SUPPORTED - UNKNOWN_WINDOW - OUTPUT_LIMIT - SCHEMA_INVALID findingIndex: description: Zero-based index in the rejected model output. type: integer minimum: 0 maximum: 9007199254740991 fieldIndex: type: integer minimum: 0 maximum: 9007199254740991 windowIndex: type: integer minimum: 0 maximum: 9007199254740991 message: type: string maxLength: 1000 required: - code - message additionalProperties: false issueCount: type: integer minimum: 0 maximum: 9007199254740991 repairFeedback: type: string maxLength: 4000 rejectedOutput: type: string maxLength: 24000 sourceContext: type: object properties: title: type: string maxLength: 500 channel: type: string maxLength: 300 additionalProperties: false sourceWindows: maxItems: 15 type: array items: type: object properties: index: type: integer minimum: -9007199254740991 maximum: 9007199254740991 startMs: type: number endMs: type: number text: type: string maxLength: 2000 required: - index - startMs - endMs - text additionalProperties: false captureTruncated: type: boolean required: - version - stage - videoId - modelCallId - attemptId - attempt - recordedAt - outcome - elapsedMs additionalProperties: false extractions: maxItems: 64 type: array items: type: object properties: version: type: number enum: - 1 kind: type: string enum: - storyboard - frames - transcript videoId: type: string pattern: ^[A-Za-z0-9_-]{11}$ extractionId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ attempt: type: integer minimum: 1 maximum: 5 slot: type: integer minimum: 0 maximum: 3 backend: type: string enum: - worker - container egress: type: string enum: - direct - proxy recordedAt: type: integer minimum: 0 maximum: 9007199254740991 elapsedMs: type: number minimum: 0 maximum: 9007199254740991 status: type: integer minimum: 100 maximum: 599 outcome: type: string enum: - success - failed - fallback - transport_error failureKind: type: string enum: - timeout - canceled - transport - invalid_response - upstream capture: type: string enum: - available - missing - invalid - unavailable events: maxItems: 64 type: array items: type: object properties: stage: type: string enum: - player - player_response - download - complete - request - image_normalized - caption_metadata - caption_retry - media_candidates - media_http - media_transfer - media_retry - media_retry_skipped - ffmpeg - ffmpeg_success profile: type: string enum: - IOS - ANDROID_VR - MWEB - WEB - ios - android - android_vr - mweb - web outcome: type: string enum: - selected - skipped - error - success playabilityStatus: type: string enum: - OK - LOGIN_REQUIRED - UNPLAYABLE - ERROR - LIVE_STREAM_OFFLINE - CONTENT_CHECK_REQUIRED - AGE_CHECK_REQUIRED - UNKNOWN specState: type: string enum: - valid - missing - malformed code: type: string enum: - INVALID_INPUT - INVALID_RESPONSE - NOT_FOUND - CAPTIONS_UNAVAILABLE - UNAVAILABLE - UPSTREAM_ERROR - AUTH_REQUIRED - RATE_LIMITED - FRAME_EXTRACTION_FAILED - FRAME_TIMEOUT - FRAME_CANCELLED - MEDIA_UNAVAILABLE - UNKNOWN inputFormat: type: string enum: - webp - jpeg outputFormat: type: string enum: - webp - jpeg status: type: integer minimum: 100 maximum: 599 elapsedMs: type: number minimum: 0 maximum: 9007199254740991 timestampMs: type: integer minimum: 0 maximum: 9007199254740991 candidateIndex: type: integer minimum: 0 maximum: 9007199254740991 candidateCount: type: integer minimum: 0 maximum: 9007199254740991 attempt: type: integer minimum: 0 maximum: 9007199254740991 delayMs: type: number minimum: 0 maximum: 9007199254740991 sheetCount: type: integer minimum: 0 maximum: 9007199254740991 width: type: integer minimum: 0 maximum: 9007199254740991 height: type: integer minimum: 0 maximum: 9007199254740991 sourceWidth: type: integer minimum: 0 maximum: 9007199254740991 sourceHeight: type: integer minimum: 0 maximum: 9007199254740991 formatId: type: integer minimum: 0 maximum: 9007199254740991 inputBytes: type: integer minimum: 0 maximum: 9007199254740991 outputBytes: type: integer minimum: 0 maximum: 9007199254740991 exitCode: type: integer minimum: -255 maximum: 255 required: - stage additionalProperties: false droppedEvents: type: integer minimum: 0 maximum: 9007199254740991 toolCallId: type: string minLength: 1 maxLength: 300 required: - version - kind - videoId - extractionId - attempt - slot - recordedAt - elapsedMs - outcome - capture - events - droppedEvents - toolCallId additionalProperties: false extractionDiagnosticsTruncated: type: boolean required: - userMessageId - conversationTurn - modelStepCount - toolCallCount additionalProperties: false required: - runId - agentMessageId - status - sessionId additionalProperties: false AgentRunReceipt: type: object required: - runId - sessionId - userMessageId - agentMessageId - conversationTurn - modelStepCount - toolCallCount - status properties: runId: type: string format: uuid sessionId: type: string format: uuid userMessageId: type: string format: uuid description: Stable identifier assigned to the admitted user message. agentMessageId: type: string format: uuid description: Stable identifier reserved for the agent response. conversationTurn: type: integer minimum: 1 description: >- One-based position of this user and assistant turn within the conversation. modelStepCount: type: integer minimum: 0 description: >- Completed model steps in the main Agent Core loop. Classifier, transcript analyst, repair, and timeout-finalizer calls are excluded. toolCallCount: type: integer minimum: 0 description: >- Persisted tool calls for this run, including completed, failed, and finalization calls. status: type: string enum: - pending - running - completed - failed - cancelled AgentRouteDecision: oneOf: - type: object required: - route properties: route: const: topic_research researchBreadth: type: string enum: - focused - comparative searchQuery: type: string useStoryboard: type: boolean description: >- Classifier selection of visual evidence access. Absent on legacy routes. answerDetail: type: string enum: - standard - detailed description: >- Classifier selection of the output budget. Legacy routes default to standard. - type: object required: - route - videoId properties: route: const: inspect_video videoId: type: string useStoryboard: type: boolean description: >- Classifier selection of visual evidence access. Absent on legacy routes. answerDetail: type: string enum: - standard - detailed description: >- Classifier selection of the output budget. Legacy routes default to standard. - type: object required: - route - question properties: route: const: clarification question: type: string - type: object required: - route - reason properties: route: const: rejected reason: type: string AgentTurnResult: type: object required: - runId - sessionId - userMessageId - agentMessageId - answer - intent - confidence - citations - artifacts - warnings - billing properties: runId: type: string format: uuid sessionId: type: string format: uuid userMessageId: type: string format: uuid agentMessageId: type: string format: uuid answer: type: string intent: type: string enum: - topic_research - inspect_video - context_answer - clarification - rejected confidence: type: string enum: - high - medium - low citations: type: array items: $ref: '#/components/schemas/AgentCitation' artifacts: type: array items: type: object required: - type - data properties: type: type: string title: type: string data: type: object additionalProperties: true warnings: type: array items: type: object required: - code - message properties: code: type: string message: type: string billing: type: object required: - creditsCharged - creditsRemaining properties: creditsCharged: type: integer minimum: 0 creditsRemaining: type: integer minimum: 0 Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: QUERY_REQUIRED message: type: string details: {} requestId: type: string AgentCitation: type: object required: - id - sourceId - provider - excerpt properties: id: type: string sourceId: type: string provider: type: string videoId: type: string channelId: type: string playlistId: type: string title: type: string url: type: string format: uri excerpt: type: string startMs: type: integer minimum: 0 endMs: type: integer minimum: 0 responses: Unauthorized: description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The caller is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: The request failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: An upstream AI or YouTube service is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key description: >- Permanent personal API key created in the dashboard. Example: curl -H "Authorization: Bearer aty_…" https://your-host/v1/projects sessionCookie: type: apiKey in: cookie name: better-auth.session_token description: >- Better Auth session cookie. A production deployment may use the secure-prefixed cookie name; same-origin browser requests send it automatically. cliSession: type: http scheme: bearer bearerFormat: CLI session description: >- Short-lived, revocable session issued by the video2ctx device authorization flow. The official CLI stores and sends this value; never paste it into prompts or logs. apiKey: type: apiKey in: header name: X-API-Key description: >- Legacy-compatible header for a permanent personal API key. Prefer Authorization: Bearer aty_…. demoUser: type: apiKey in: header name: X-Demo-User description: >- Local development only. Any stable value selects an isolated demo account. Rejected in production. ````