> ## 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.

# Replace video chapters

> Replaces the complete chapter list. Timestamps are seconds on the final video timeline and must be non-negative, ascending, and within the video duration. Pass an empty array to clear all chapters.



## OpenAPI

````yaml /openapi.json put /v1/videos/{id}/chapters
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 organization.

    Rate limit information is returned in response headers:

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

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

    - `X-RateLimit-Reset`: Unix timestamp when the window resets
  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: Webhook endpoint management
    name: Webhooks
paths:
  /v1/videos/{id}/chapters:
    put:
      tags:
        - Videos
      summary: Replace video chapters
      description: >-
        Replaces the complete chapter list. Timestamps are seconds on the final
        video timeline and must be non-negative, ascending, and within the video
        duration. Pass an empty array to clear all chapters.
      operationId: setVideoChapters
      parameters:
        - description: Unique video identifier
          in: path
          name: id
          required: true
          schema:
            description: Unique video identifier
            example: vid_abc123def456
            type: string
      requestBody:
        content:
          application/json:
            schema:
              description: Replace all chapters on a video
              properties:
                chapters:
                  description: >-
                    Complete replacement chapter list in ascending timestamp
                    order (maximum 100). Pass an empty array to clear all
                    chapters.
                  items:
                    $ref: '#/components/schemas/ChapterInput'
                  maxItems: 100
                  type: array
              required:
                - chapters
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                description: Video chapters
                properties:
                  chapters:
                    description: Chapters on the final video timeline, ordered by timestamp
                    items:
                      $ref: '#/components/schemas/Chapter'
                    type: array
                required:
                  - chapters
                type: object
          description: Chapters replaced
        '400':
          $ref: '#/components/responses/400ErrorResponse'
        '401':
          $ref: '#/components/responses/401ErrorResponse'
        '403':
          $ref: '#/components/responses/403ErrorResponse'
        '404':
          $ref: '#/components/responses/404ErrorResponse'
        '422':
          $ref: '#/components/responses/422ErrorResponse'
        '429':
          $ref: '#/components/responses/429ErrorResponse'
        '500':
          $ref: '#/components/responses/500ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    ChapterInput:
      description: A chapter accepted when replacing a video's chapters
      properties:
        description:
          description: >-
            Chapter description. Lines formatted like a timestamp followed by a
            title are not allowed.
          example: Overview of what we'll cover
          maxLength: 5000
          type: string
        timestampSeconds:
          description: Chapter start time in whole seconds
          example: 0
          maximum: 9007199254740991
          minimum: 0
          type: integer
        title:
          description: Single-line chapter title
          example: Introduction
          maxLength: 255
          minLength: 1
          pattern: ^[^\r\n]*$
          type: string
      required:
        - title
        - description
        - timestampSeconds
      type: object
    Chapter:
      additionalProperties: false
      description: A chapter/section within a video
      properties:
        description:
          description: Chapter description
          example: Overview of what we'll cover
          maxLength: 5000
          type: string
        timestampSeconds:
          description: Chapter start time in seconds
          example: 0
          minimum: 0
          type: number
        title:
          description: Chapter title
          example: Introduction
          maxLength: 255
          minLength: 1
          type: string
      required:
        - title
        - description
        - timestampSeconds
      type: object
    ErrorResponse:
      additionalProperties: false
      description: Standard error response format
      properties:
        error:
          additionalProperties: false
          description: Error details
          properties:
            code:
              description: Machine-readable error code
              enum:
                - bad_request
                - unauthorized
                - forbidden
                - not_found
                - unprocessable_entity
                - rate_limit_exceeded
                - internal_server_error
              example: not_found
              type: string
            doc_url:
              description: Link to documentation for this error
              example: https://tella.tv/docs/api-reference/errors#not-found
              format: uri
              type: string
            message:
              description: Human-readable error message
              example: The requested resource was not found.
              type: string
          required:
            - code
            - message
            - doc_url
          type: object
      required:
        - error
      type: object
  responses:
    400ErrorResponse:
      content:
        application/json:
          example:
            error:
              code: bad_request
              doc_url: https://tella.tv/docs/api-reference/errors#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.
    401ErrorResponse:
      content:
        application/json:
          example:
            error:
              code: unauthorized
              doc_url: https://tella.tv/docs/api-reference/errors#unauthorized
              message: Authentication is required. Provide a valid API key.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Authentication is required. Provide a valid API key.
    403ErrorResponse:
      content:
        application/json:
          example:
            error:
              code: forbidden
              doc_url: https://tella.tv/docs/api-reference/errors#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.
    404ErrorResponse:
      content:
        application/json:
          example:
            error:
              code: not_found
              doc_url: https://tella.tv/docs/api-reference/errors#not-found
              message: The requested resource was not found.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The requested resource was not found.
    422ErrorResponse:
      content:
        application/json:
          example:
            error:
              code: unprocessable_entity
              doc_url: https://tella.tv/docs/api-reference/errors#unprocessable-entity
              message: The request was well-formed but contained semantic errors.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The request was well-formed but contained semantic errors.
    429ErrorResponse:
      content:
        application/json:
          example:
            error:
              code: rate_limit_exceeded
              doc_url: https://tella.tv/docs/api-reference/errors#rate-limit-exceeded
              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.
    500ErrorResponse:
      content:
        application/json:
          example:
            error:
              code: internal_server_error
              doc_url: https://tella.tv/docs/api-reference/errors#internal-server-error
              message: An unexpected error occurred on the server.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: An unexpected error occurred on the server.
  securitySchemes:
    BearerAuth:
      description: API key obtained from your Tella account settings
      scheme: bearer
      type: http

````