vidocu-ai AI Recorder API

openapi: 3.2.0
info:
  title: Vidocu Ai AI Recorder API
  version: 1.14.0
  contact:
    name: Vidocu Support
    url: https://vidocu.ai
  license:
    name: Proprietary
    url: https://vidocu.ai/terms
  description: 'Operations tagged AI Recorder across 2 of this provider''s published API definitions: support-vidocu-openapi.json, vidocu-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.vidocu.ai
  description: Production
security:
- bearerAuth: []
- oauth2: []
tags:
- name: AI Recorder
paths:
  /v1/recordings:
    get:
      tags:
      - AI Recorder
      summary: List recordings
      description: '**Scope:** `recordings:read`'
      operationId: getV1Recordings
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
      responses:
        '200':
          description: Success
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - AI Recorder
      summary: Start a recording
      description: 'Describe a flow and the agent records it. Long-running — poll the job. Billed per minute of finished video; failed and aborted jobs are free. On a site with a saved login, pass sessionId to pick one; omit it to use the site''s default session.


        **Scope:** `recordings:write`


        **Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)'
      operationId: postV1Recordings
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 50000
                  description: What the recording should show, up to 50,000 characters
                name:
                  type: string
                  maxLength: 200
                  description: Display name for the recording in lists; absent = show the prompt
                url:
                  type: string
                  format: uri
                device:
                  type: string
                  enum:
                  - desktop
                  - mobile
                pacing:
                  type: string
                  enum:
                  - relaxed
                  - standard
                  - brisk
                maxDurationSec:
                  type: number
                  minimum: 0
                  maximum: 1800
                  description: Max finished-video length in seconds; 0 or absent = no limit
                removeLoading:
                  type: boolean
                  description: Cut page-load waits (the first load, navigations, loads after a click) out of the video. Default false
                mode:
                  type: string
                  enum:
                  - regular
                  - follow
                  - steps
                steps:
                  type: array
                  items:
                    type: object
                    properties:
                      instruction:
                        type: string
                        minLength: 1
                        maxLength: 2000
                      url:
                        type: string
                        format: uri
                    required:
                    - instruction
                    additionalProperties: false
                  maxItems: 50
                sessionId:
                  type: string
                  pattern: ^[0-9a-f]{24}$
                  description: The saved login to start signed in with, by id from GET /v1/recorder-sessions. A site can have several (e.g. "Sandbox" and "Admin user"). Omit it to use the site's default session.
              required:
              - prompt
              additionalProperties: false
      responses:
        '202':
          description: Recording started
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The recorder judged the prompt not actionable
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.vidocu.ai
      description: Production
  /v1/recordings/{jobId}:
    get:
      tags:
      - AI Recorder
      summary: Get a recording
      description: 'Includes the aborted and partial flags.


        **Scope:** `recordings:read`'
      operationId: getV1RecordingsJobId
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - AI Recorder
      summary: Rename a recording
      description: 'Sets the display name shown instead of the prompt. Send null or an empty string to clear it. The prompt never changes.


        **Scope:** `recordings:write`


        **Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)'
      operationId: patchV1RecordingsJobId
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type:
                  - string
                  - 'null'
                  maxLength: 200
                  description: Display name shown instead of the prompt. null or an empty string clears it.
              required:
              - name
              additionalProperties: false
      responses:
        '200':
          description: Success
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - AI Recorder
      summary: Delete a recording
      description: '**Scope:** `recordings:write`


        **Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)'
      operationId: deleteV1RecordingsJobId
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                    enum:
                    - true
                  jobId:
                    type: string
                required:
                - deleted
                - jobId
                additionalProperties: false
                description: Recording deleted.
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.vidocu.ai
      description: Production
  /v1/recordings/{jobId}/download:
    get:
      tags:
      - AI Recorder
      summary: Get a download URL
      description: 'Time-limited URL for the finished file.


        **Scope:** `recordings:read`'
      operationId: getV1RecordingsJobIdDownload
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The recording hasn't completed
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.vidocu.ai
      description: Production
  /v1/recordings/{jobId}/input:
    post:
      tags:
      - AI Recorder
      summary: Answer a blocked recording
      description: 'Supply a value the agent paused for, such as a one-time code.


        **Scope:** `recordings:write`


        **Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)'
      operationId: postV1RecordingsJobIdInput
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  minLength: 1
                  maxLength: 500
              required:
              - value
              additionalProperties: false
      responses:
        '200':
          description: Success
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.vidocu.ai
      description: Production
  /v1/recorder-sessions:
    get:
      tags:
      - AI Recorder
      summary: List saved logins
      description: 'A site can have several saved sessions (e.g. "Sandbox" and "Admin user"). Each item has an id, a name, createdBy, and isDefault: exactly one per domain is the default, used when a recording names no sessionId. Each also carries its setupPrompt (off-camera setup run before every recording and screenshot on that site, or null), its context (who the login is and what it sees, or null) and ttlDays. Stored cookies are never returned.


        **Scope:** `recordings:read`'
      operationId: getV1Recorder-sessions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Session id. Use it in /v1/recorder-sessions/{session} and as sessionId on POST /v1/recordings.
                        domain:
                          type: string
                        name:
                          type: string
                          description: Label, e.g. "Sandbox". The domain for sessions saved before names existed.
                        isDefault:
                          type: boolean
                          description: The session a recording on this site uses when it names no sessionId. Exactly one per domain.
                        createdBy:
                          type:
                          - string
                          - 'null'
                          description: User id of whoever saved it. null for older sessions.
                        setupPrompt:
                          type:
                          - string
                          - 'null'
                        context:
                          type:
                          - string
                          - 'null'
                          description: 'Who this login is and what it sees, e.g. "Teacher account: manages classes". Descriptive only, never performed. null when unset.'
                        ttlDays:
                          type: integer
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                          description: When the login was last refreshed (saved, or used by a recording).
                        expiresAt:
                          type: string
                          format: date-time
                      required:
                      - id
                      - domain
                      - name
                      - isDefault
                      - createdBy
                      - setupPrompt
                      - context
                      - ttlDays
                      - createdAt
                      - updatedAt
                      - expiresAt
                      additionalProperties: false
                required:
                - sessions
                additionalProperties: false
                description: Saved logins, most recently refreshed first.
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.vidocu.ai
      description: Production
  /v1/recorder-sessions/{session}:
    patch:
      tags:
      - AI Recorder
      summary: Update a saved login
      description: '`session` is a session id, or a domain meaning that site''s default session. Rename it, make it the site''s default (isDefault: true), set its setup instructions or its context (who the login is and what it sees; null clears either) or change how long it is kept. Send at least one field. 404 when there is no such session.


        **Scope:** `recordings:write`


        **Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)'
      operationId: patchV1Recorder-sessionsSession
      parameters:
      - name: session
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 80
                  description: A label for the session, e.g. "Sandbox" or "Admin user". Up to 80 characters. An empty string resets it to the domain.
                isDefault:
                  type: boolean
                  enum:
                  - true
                  description: 'true makes this the site''s default session: the one a recording uses when it names no session. Only true is accepted. A site always has a default, so to change it, make another session the default.'
                setupPrompt:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
                  description: Steps the recorder performs on this site before every recording and screenshot, off camera (e.g. "Switch to the Acme workspace and close the welcome banner"). null clears it. A recording request's own setupPrompt takes precedence.
                context:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
                  description: 'Who this login is and what it can see and do, e.g. "Teacher account: manages classes, assigns lessons, sees grades". Descriptive only: it is never performed as steps. Pulse uses it to write docs for the right audience, and recordings with this session read it as background. null clears it.'
                ttlDays:
                  type: integer
                  description: 'How many days the saved login is kept after it was last used: 14 (default), 30, 90, 180 or 365. The expiry is recomputed from the last use, so shortening it can expire an old session right away. The site''s own sign-out rules still apply.'
              additionalProperties: false
      responses:
        '200':
          description: Updated
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - AI Recorder
      summary: Forget a saved login
      description: '`session` is a session id, or a domain. By domain only works when the site has one session; with several it answers 409 and lists them, so delete by id. Deleting the default makes the most recently used remaining session for that site the new default.


        **Scope:** `recordings:write`


        **Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)'
      operationId: deleteV1Recorder-sessionsSession
      parameters:
      - name: session
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                    enum:
                    - true
                  id:
                    type: string
                    description: The deleted session's id.
                  domain:
                    type: string
                required:
                - deleted
                - id
                - domain
                additionalProperties: false
                description: Saved recorder session deleted.
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The domain has several saved sessions; the error lists them (`sessions`). Delete by id.
        '429':
          description: Rate limit exceeded (60 req/min)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.vidocu.ai
      description: Production
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable code, e.g. `validation_error`, `insufficient_role`, `locked`
            message:
              type: string
          required:
          - code
          - message
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`vdo_live_...`) or an OAuth 2.0 access token (`vdo_oat_...`).
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://vidocu.ai/oauth/authorize
          tokenUrl: https://api.vidocu.ai/oauth/token
          scopes:
            videos:read: View videos in the workspace
            videos:write: Upload and modify videos
            projects:read: View project folders
            projects:write: Create, update, and delete project folders
            subtitles:read: View subtitles
            subtitles:write: Generate and edit subtitles
            export:write: Export videos
            translate:write: Translate videos
            voiceover:write: Generate voiceovers
            article:read: View help articles
            article:write: Generate help articles
            analyze:write: Analyze videos
            tools:read: List and view tools
            tools:write: Execute tools
            jobs:read: View job status
            courses:read: View courses and their storyboards
            courses:write: Create courses and run planning, storyboarding and generation
            studio:read: View Studio projects and templates
            studio:write: Create, edit and share Studio projects
            modules:read: View training modules, results and qualifications
            modules:write: Create, edit and translate training modules; record attempts and sign-offs
            remixes:read: View remixes and their analysis
            remixes:write: Create remixes and run analysis
            recordings:read: View AI Recorder jobs and saved logins
            recordings:write: Start recordings and manage saved logins
            knowledge_base:read: View the knowledge base, its articles and analytics
            knowledge_base:write: Create and edit knowledge base content
            brand_kit:read: View Brand Kit settings, skills and glossary
            brand_kit:write: Change Brand Kit settings, skills and glossary
            usage:read: View usage statistics
            voices:read: List available voices
            voices:write: Delete cloned voices
            avatars:read: List available AI avatars
            avatars:write: Create custom AI avatars
            webhooks:read: View webhook subscriptions
            webhooks:write: Create, update, and delete webhooks
            process:write: Use one-shot process endpoint
            approvals:read: View approval rounds and requests
            approvals:write: Request, decide and withdraw approvals
            comments:read: View comments on videos
            comments:write: Add and delete comments
            locks:write: Lock and unlock videos and modules
x-refined-from:
- support-vidocu-openapi.json
- vidocu-ai-openapi.json