> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search videos

> Search the authenticated user's direct video library by title or indexed transcript sentences.



## OpenAPI

````yaml /openapi.json get /v1/videos/search
openapi: 3.0.3
info:
  description: >-
    The Tella Public API allows you to programmatically access your videos and
    playlists, including transcripts, chapters, and thumbnails.


    ## Authentication


    All requests require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer tella_pk_xxxxx...

    ```


    API keys can be generated in your Tella workspace settings.


    ## Rate Limiting


    The API is rate-limited to 100 requests per minute per user within a
    workspace.

    Rate limit information is returned in response headers:

    - `RateLimit-Policy`: Named quota, request limit, and window in seconds

    - `RateLimit`: Remaining quota and seconds until reset

    - `X-RateLimit-Limit`: Maximum requests per window

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets


    A `429 Too Many Requests` response also includes `Retry-After` in seconds.
  title: Tella Public API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.tella.com
security: []
tags:
  - description: Video operations
    name: Videos
  - description: Sections of a video
    name: Clips
  - description: Playlist operations
    name: Playlists
  - description: Sidebar groups for organizing playlists
    name: Playlist Groups
  - description: Tags for categorizing and filtering videos
    name: Tags
  - description: Personal, workspace, and default video backgrounds
    name: Backgrounds
  - description: >-
      Reusable media saved to a workspace, plus Tella's curated sound effect
      catalog — the same items the editor's media panels show
    name: Library
  - description: Webhook endpoint management
    name: Webhooks
externalDocs:
  description: API versioning and deprecation policy
  url: https://www.tella.com/docs/versioning
paths:
  /v1/videos/search:
    get:
      tags:
        - Videos
      summary: Search videos
      description: >-
        Search the authenticated user's direct video library by title or indexed
        transcript sentences.
      operationId: searchVideos
      parameters:
        - description: Words to find in video titles or indexed transcript sentences
          in: query
          name: query
          required: true
          schema:
            description: Words to find in video titles or indexed transcript sentences
            maxLength: 200
            minLength: 1
            type: string
        - description: 'Fields to search (default: all)'
          in: query
          name: searchIn
          schema:
            description: 'Fields to search (default: all)'
            enum:
              - all
              - title
              - transcript
            type: string
        - description: >-
            Upper bound on results per page (default: 20, max: 100). A page can
            be shorter once results the caller cannot see are removed, so keep
            paging while hasMore is true.
          in: query
          name: limit
          schema:
            description: >-
              Upper bound on results per page (default: 20, max: 100). A page
              can be shorter once results the caller cannot see are removed, so
              keep paging while hasMore is true.
            maximum: 100
            minimum: 1
            type: integer
        - description: Opaque pagination cursor from the previous response
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from the previous response
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchVideosResponse'
          description: Matching videos
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '400':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: bad_request
                message: The request was malformed or contained invalid parameters.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The request was malformed or contained invalid parameters.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '401':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: unauthorized
                message: Authentication is required. Provide a valid API key.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication is required. Provide a valid API key.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '403':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: forbidden
                message: You don't have permission to access this resource.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: You don't have permission to access this resource.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '404':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: not_found
                message: The requested resource was not found.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The requested resource was not found.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '429':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: rate_limited
                message: You have exceeded the rate limit. Please slow down.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: You have exceeded the rate limit. Please slow down.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '500':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: server_error
                message: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An unexpected error occurred
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
        '501':
          content:
            application/json:
              example:
                docsUrl: https://docs.tella.com/
                error: not_implemented
                message: The requested operation is not implemented.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The requested operation is not implemented.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
      security:
        - BearerAuth: []
components:
  schemas:
    SearchVideosResponse:
      additionalProperties: false
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        results:
          items:
            $ref: '#/components/schemas/SearchVideoResult'
          type: array
      required:
        - results
        - pagination
      type: object
    ErrorResponse:
      additionalProperties: false
      description: Standard error response format
      properties:
        docsUrl:
          description: Link to Tella API documentation
          example: https://docs.tella.com/
          format: uri
          type: string
        error:
          description: Machine-readable error code
          enum:
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - rate_limited
            - server_error
            - not_implemented
          example: not_found
          type: string
        message:
          description: Human-readable error message
          example: Resource not found
          type: string
      required:
        - error
        - message
        - docsUrl
      type: object
    Pagination:
      additionalProperties: false
      description: >-
        Pagination metadata for list responses. Results are sorted by updatedAt
        descending.
      properties:
        hasMore:
          description: Whether there are more items to fetch
          example: true
          type: boolean
        nextCursor:
          description: >-
            Cursor for next page. Pass this value as the 'cursor' query
            parameter to fetch the next page. Null if no more pages. This is an
            opaque value - do not decode or modify it.
          example: eyJpZCI6IjEyMyJ9
          nullable: true
          type: string
      required:
        - nextCursor
        - hasMore
      type: object
    SearchVideoResult:
      additionalProperties: false
      properties:
        matches:
          items:
            $ref: '#/components/schemas/SearchMatch'
          type: array
        video:
          $ref: '#/components/schemas/VideoListItem'
      required:
        - video
        - matches
      type: object
    SearchMatch:
      additionalProperties: false
      properties:
        endSeconds:
          description: >-
            End of the matching transcript sentence, in seconds. Null for title
            matches.
          nullable: true
          type: number
        field:
          enum:
            - title
            - transcript
          type: string
        matchedTokens:
          items:
            type: string
          type: array
        snippet:
          description: Plain-text matching excerpt
          type: string
        startSeconds:
          description: >-
            Start of the matching transcript sentence, in seconds. Null for
            title matches.
          nullable: true
          type: number
      required:
        - field
        - snippet
        - matchedTokens
        - startSeconds
        - endSeconds
      type: object
    VideoListItem:
      additionalProperties: false
      description: Video item in a list response
      properties:
        aspectRatio:
          description: Video aspect ratio (e.g., '16:9', '9:16')
          example: '16:9'
          type: string
        autoRatio:
          description: >-
            Whether the canvas is in Auto ratio (sized from the video's
            recording and following it as layouts change), the editor's Setup →
            Size → Auto.
          example: false
          type: boolean
        createdAt:
          description: ISO 8601 datetime
          example: '2024-01-15T10:30:00.000Z'
          format: date-time
          type: string
        description:
          description: Video description
          example: Learn how to create and share your first video
          maxLength: 5000
          type: string
        dimensions:
          additionalProperties: false
          description: Canvas size in pixels
          example:
            height: 1080
            width: 1920
          properties:
            height:
              type: number
            width:
              type: number
          required:
            - width
            - height
          type: object
        id:
          description: Unique video identifier
          example: vid_abc123def456
          type: string
        links:
          allOf:
            - $ref: '#/components/schemas/VideoLinks'
          description: Related URLs for the video
        name:
          description: Video title
          example: Getting Started with Tella
          maxLength: 255
          minLength: 1
          type: string
        updatedAt:
          description: ISO 8601 datetime
          example: '2024-01-15T14:45:00.000Z'
          format: date-time
          type: string
        views:
          description: Total view count
          example: 1234
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
        - id
        - name
        - description
        - views
        - aspectRatio
        - dimensions
        - autoRatio
        - createdAt
        - updatedAt
        - links
      type: object
    VideoLinks:
      additionalProperties: false
      description: URLs related to a video
      properties:
        embedPage:
          description: URL for embedding the video
          example: https://www.tella.tv/video/vid_abc123def456/embed
          format: uri
          type: string
        viewPage:
          description: URL to view the video on Tella
          example: https://www.tella.tv/video/vid_abc123def456/view
          format: uri
          type: string
      required:
        - viewPage
        - embedPage
      type: object
  headers:
    Deprecation:
      description: Indicates that an API operation is deprecated, following RFC 9745
      example: '@1767225600'
      schema:
        type: string
    RateLimit:
      description: >-
        Current quota with remaining requests (`r`) and seconds until reset
        (`t`)
      example: '"public-api";r=95;t=42'
      schema:
        type: string
    RateLimitPolicy:
      description: >-
        Named quota policy with the request limit (`q`) and window in seconds
        (`w`)
      example: '"public-api";q=100;w=60'
      schema:
        type: string
    Sunset:
      description: >-
        Indicates when a deprecated API operation will become unavailable,
        following RFC 8594
      example: Tue, 30 Jun 2026 23:59:59 GMT
      schema:
        type: string
    XRateLimitLimit:
      description: Maximum requests allowed in the current window
      example: 100
      schema:
        type: integer
    XRateLimitRemaining:
      description: Requests remaining in the current window
      example: 95
      schema:
        type: integer
    XRateLimitReset:
      description: Unix timestamp in milliseconds when the window resets
      example: 1704067200000
      schema:
        format: int64
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying a rate-limited request
      example: 45
      schema:
        minimum: 1
        type: integer
  securitySchemes:
    BearerAuth:
      description: API key obtained from your Tella account settings
      scheme: bearer
      type: http

````

## Related topics

- [Model Context Protocol (MCP)](/docs/mcp-server.md)
- [Tella MCP Server](/docs/help/integrations/mcp-server.md)
- [Public API and webhooks](/docs/help/integrations/public-api-and-webhooks.md)
- [Product Changelog](/docs/changelog.md)
- [Edit with the transcript](/docs/help/editing/edit-the-transcript-of-a-tella-video.md)