> ## 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. # Start a durable agent run > Starts a new session when sessionId is omitted. Follow-up requests reuse the Durable Object selected by the supplied sessionId and inherit bounded memory from completed ancestor turns. Without parentMessageId, the latest completed assistant turn is selected automatically. The response is an asynchronous run receipt. Each accepted POST creates a new run. Retrieve existing work using the returned sessionId and runId, or find it in the session dashboard if the receipt was lost. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agent 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: post: tags: - Agents summary: Start a durable agent run description: >- Starts a new session when sessionId is omitted. Follow-up requests reuse the Durable Object selected by the supplied sessionId and inherit bounded memory from completed ancestor turns. Without parentMessageId, the latest completed assistant turn is selected automatically. The response is an asynchronous run receipt. Each accepted POST creates a new run. Retrieve existing work using the returned sessionId and runId, or find it in the session dashboard if the receipt was lost. operationId: startAgentRun parameters: - 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentRequest' responses: '202': description: >- Agent run admitted. Compact receipts omit execution metadata unless diagnostics is requested. content: application/json: schema: oneOf: - $ref: '#/components/schemas/AgentRunReceipt' - $ref: '#/components/schemas/CompactAgentRun' headers: X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Remaining: $ref: '#/components/headers/CreditsRemaining' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerApiKey: [] - sessionCookie: [] - cliSession: [] - apiKey: [] - demoUser: [] components: schemas: AgentRequest: type: object required: - message properties: message: type: string minLength: 1 maxLength: 10000 sessionId: type: string format: uuid description: Continue an existing agent session. conversationId: type: string format: uuid deprecated: true description: >- Deprecated request alias for sessionId. If both are supplied, they must match. Responses return only sessionId. parentMessageId: type: string format: uuid description: >- Optional completed assistant message to use as the parent. Omit it to continue from the latest completed turn. 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 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 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 headers: CreditsCharged: description: Credits settled for this operation. schema: type: integer minimum: 0 CreditsRemaining: description: Current balance in the owning user account after the request is metered. schema: type: integer responses: Unauthorized: description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/Error' InsufficientCredits: description: >- The user account does not have enough credits. Error code: INSUFFICIENT_CREDITS. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Remaining: $ref: '#/components/headers/CreditsRemaining' Forbidden: description: The caller is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: The request conflicts with the current state of the conversation. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: The request failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: The public rate limit was exceeded. 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. ````