openapi: 3.0.0
info:
  title: YouTube Post API
  description: |
    Retrieve a single YouTube community post from its URL or post ID. Returns the post text with resolved links,
    exact like counts, channel details, polls, quizzes with correct answers, and image, video, and
    playlist attachments.

    **Cross-linking**: The `channel.id` and `channel.handle` returned by this API can be used with the
    YouTube Channel API (`channel_id` parameter). Video attachment `id` values can be used with the
    YouTube Video API (`video_id` parameter).
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: YouTube Post
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Parameter defines the engine that will be used to retrieve real-time data. It must be set to `youtube_post`.
          schema:
            type: string
            default: "youtube_post"
        - name: url
          in: query
          required: false
          description: 'The URL of the YouTube community post. Required unless `post_id` is passed. Accepts post URLs in the format `https://www.youtube.com/post/POST_ID` and community tab permalinks like `https://www.youtube.com/@HANDLE/community?lb=POST_ID` or `https://www.youtube.com/channel/CHANNEL_ID/community?lb=POST_ID`.'
          schema:
            type: string
            maxLength: 2048
        - name: post_id
          in: query
          required: false
          description: 'The ID of the YouTube community post, such as `UgkxZusu9I1Z-VuU5PGZNA2gclHi8V9CJVZk`. Required unless `url` is passed. Use the `id` returned by the YouTube Channel Posts API. Cannot be combined with `url`.'
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Post not found, YouTube returned no results, or we could not retrieve results in 90 seconds. The request is not billed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        post:
          $ref: '#/components/schemas/Post'
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "YouTube community post URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: The search engine used
        url:
          type: string
          description: The YouTube community post URL, when the search was made with `url`
        post_id:
          type: string
          description: The YouTube community post ID, when the search was made with `post_id`
    Post:
      type: object
      required: [id, link]
      properties:
        id:
          type: string
          description: Community post identifier
        link:
          type: string
          description: Canonical URL of the post
        channel:
          $ref: '#/components/schemas/Channel'
        content:
          type: string
          description: Full post text. Absent on image-only posts without text
        content_links:
          type: array
          description: Links found in the post text with full destination URLs resolved (post text truncates long URLs)
          items:
            $ref: '#/components/schemas/ContentLink'
        hashtags:
          type: array
          description: Hashtags used in the post text, without the leading `#`
          items:
            type: string
        likes:
          type: string
          description: Abbreviated like count as displayed (e.g. "98K"). Absent on the repost wrapper
        extracted_likes:
          type: integer
          description: Exact like count
        published_time:
          type: string
          description: Relative publish time (e.g. "1 month ago"). YouTube does not expose an exact timestamp
        is_edited:
          type: boolean
          description: Present and `true` when the post was edited after publishing
        is_members_only:
          type: boolean
          description: Present and `true` when the post is visible to channel members only
        is_comments_disabled:
          type: boolean
          description: Present and `true` when comments are turned off for the post
        poll:
          $ref: '#/components/schemas/Poll'
        quiz:
          $ref: '#/components/schemas/Quiz'
        attachments:
          type: array
          description: Image, video, or playlist attachments
          items:
            oneOf:
              - $ref: '#/components/schemas/ImageAttachment'
              - $ref: '#/components/schemas/VideoAttachment'
              - $ref: '#/components/schemas/PlaylistAttachment'
        is_repost:
          type: boolean
          description: Present and `true` when the post is a repost of another community post
        original_post:
          type: object
          description: The complete original post when `is_repost` is `true`. Same structure as `post`
    Channel:
      type: object
      required: [id, title, link]
      properties:
        id:
          type: string
          description: Channel identifier
        title:
          type: string
          description: Channel name
        handle:
          type: string
          description: 'Channel handle including the `@` prefix (e.g. "@MrBeast")'
        link:
          type: string
          description: Channel URL
        thumbnail:
          type: string
          description: Channel avatar URL
    ContentLink:
      type: object
      properties:
        text:
          type: string
          description: The link text as displayed in the post (may be truncated)
        link:
          type: string
          description: Full destination URL
    Poll:
      type: object
      properties:
        total_votes:
          type: string
          description: Total votes as displayed (e.g. "1.7M votes")
        extracted_total_votes:
          type: integer
          description: Total votes as a number
        choices:
          type: array
          items:
            $ref: '#/components/schemas/PollChoice'
    PollChoice:
      type: object
      properties:
        text:
          type: string
          description: Choice text
        image:
          type: string
          description: Choice image URL. Present on image polls only
    Quiz:
      type: object
      properties:
        total_answers:
          type: string
          description: Total answers as displayed (e.g. "17K answered")
        extracted_total_answers:
          type: integer
          description: Total answers as a number
        explanation:
          type: string
          description: Explanation shown after answering
        choices:
          type: array
          items:
            $ref: '#/components/schemas/QuizChoice'
    QuizChoice:
      type: object
      properties:
        text:
          type: string
          description: Choice text
        is_correct:
          type: boolean
          description: Whether this choice is the correct answer
    ImageAttachment:
      type: object
      properties:
        type:
          type: string
          enum: ["image"]
        image:
          type: string
          description: Image URL in the highest available resolution
    VideoAttachment:
      type: object
      properties:
        type:
          type: string
          enum: ["video"]
        id:
          type: string
          description: Video identifier
        title:
          type: string
          description: Video title
        description:
          type: string
          description: Video description snippet
        link:
          type: string
          description: Video URL. Absent when the video is no longer publicly available
        is_unavailable:
          type: boolean
          description: Present and `true` when the video is no longer publicly available; only `title` and `thumbnail` are returned
        length:
          type: string
          description: 'Video duration (e.g. "14:17")'
        views:
          type: integer
          description: View count
        published_time:
          type: string
          description: Relative publish time of the video
        thumbnail:
          type: string
          description: Video thumbnail URL
        channel:
          type: object
          description: Channel the video belongs to
          properties:
            id:
              type: string
              description: Channel identifier
            title:
              type: string
              description: Channel name
            link:
              type: string
              description: Channel URL
            is_verified:
              type: boolean
              description: Present and `true` when the channel is verified
    PlaylistAttachment:
      type: object
      properties:
        type:
          type: string
          enum: ["playlist"]
        id:
          type: string
          description: Playlist identifier
        title:
          type: string
          description: Playlist title
        link:
          type: string
          description: Playlist URL
        video_count:
          type: integer
          description: Number of videos in the playlist
        thumbnail:
          type: string
          description: Playlist thumbnail URL
        channel:
          type: object
          description: Channel the playlist belongs to
          properties:
            id:
              type: string
              description: Channel identifier
            title:
              type: string
              description: Channel name
            link:
              type: string
              description: Channel URL
        videos:
          type: array
          description: Preview of the playlist's videos
          items:
            type: object
            properties:
              id:
                type: string
                description: Video identifier
              title:
                type: string
                description: Video title
              length:
                type: string
                description: Video duration
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong