openapi: 3.0.3
info:
  title: DumplingAI API
  version: "1.0.0"
  description: |
    REST API for DumplingAI's content intelligence and automation platform.
    All endpoints are grouped under `/api/v1`; most are secured via Bearer API keys unless an operation explicitly sets `security: []`.
servers:
  - url: https://app.dumplingai.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: YouTube
    description: Access metadata, search results, and transcripts from YouTube.
  - name: TikTok
    description: Retrieve TikTok profile, video, follower, and transcript data.
  - name: LinkedIn
    description: Programmatically fetch LinkedIn company and profile data.
  - name: Search
    description: Search-orientated endpoints spanning web, news, maps, and autocomplete.
  - name: Google
    description: Integrations with Google business listings and location data.
  - name: Scraping
    description: Webpage capture, crawling, and structured content extraction utilities.
  - name: Documents
    description: Document processing, conversion, and metadata utilities.
  - name: AI
    description: DumplingAI agent and knowledge base endpoints.
  - name: Developer Tools
    description: Utilities for executing sandboxed code via API.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable description of what went wrong.
      required:
        - error
    RequestSource:
      type: string
      description: Optional identifier describing where the API request originated.
      enum:
        - API
        - WEB
        - MAKE_DOT_COM
        - ZAPIER
        - N8N
        - PLAYGROUND
        - DEFAULT_AUTOMATION
        - AGENT_PREVIEW
        - AGENT_LIVE
        - AUTOPILOT
        - STUDIO
    YouTubeChannelRequest:
      type: object
      description: >
        Identify the YouTube channel to fetch. Provide at least one identifier (channelId, handle, or url).
      properties:
        channelId:
          type: string
          description: YouTube channel ID (e.g., UCxcTeAKWJca6XyJ37_ZoKIQ).
        handle:
          type: string
          description: YouTube handle beginning with `@`.
        url:
          type: string
          format: uri
          description: Full YouTube channel URL.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    YouTubeChannelResponse:
      type: object
      description: Detailed metadata about a YouTube channel.
      properties:
        channelId:
          type: string
        channel:
          type: string
          description: Canonical handle with leading `@`.
        name:
          type: string
        description:
          type: string
        subscriberCount:
          type: integer
          nullable: true
        subscriberCountText:
          type: string
          nullable: true
        videoCountText:
          type: string
          nullable: true
        viewCountText:
          type: string
          nullable: true
        joinedDateText:
          type: string
          nullable: true
        tags:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        store:
          type: string
          format: uri
          nullable: true
        twitter:
          type: string
          format: uri
          nullable: true
        instagram:
          type: string
          format: uri
          nullable: true
        links:
          type: array
          items:
            type: string
            format: uri
        country:
          type: string
          nullable: true
        avatar:
          type: object
          description: Structured avatar data as returned by YouTube.
          additionalProperties: true
      additionalProperties: true
    YouTubeVideoSummary:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        thumbnail:
          type: string
          format: uri
        url:
          type: string
          format: uri
        type:
          type: string
          description: Video type such as `video` or `short`.
        publishDateText:
          type: string
          nullable: true
        publishDate:
          type: string
          format: date-time
          nullable: true
        viewCountText:
          type: string
          nullable: true
        viewCountInt:
          type: integer
          nullable: true
        lengthText:
          type: string
          nullable: true
        channel:
          type: object
          additionalProperties: true
      additionalProperties: true
    YouTubeChannelVideosRequest:
      type: object
      description: Fetch videos from a channel with optional pagination. Supply either channelId or handle.
      properties:
        channelId:
          type: string
        handle:
          type: string
        continuationToken:
          type: string
          description: Token from a previous response for pagination.
        sort:
          type: string
          description: Sort order for the result set.
          enum:
            - latest
            - popular
            - newest
        includeExtras:
          type: string
          description: Optional upstream flag forwarded to the provider to request additional metadata.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    YouTubeChannelShortsRequest:
      type: object
      description: Fetch Shorts from a channel with optional pagination. Supply either channelId or handle.
      properties:
        channelId:
          type: string
        handle:
          type: string
        continuationToken:
          type: string
          description: Token from a previous response for pagination.
        sort:
          type: string
          description: Sort order for the result set.
          enum:
            - latest
            - popular
            - newest
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    YouTubeChannelVideosResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Present on some responses from the upstream provider.
        videos:
          type: array
          description: Present when returning long-form uploads.
          items:
            $ref: '#/components/schemas/YouTubeVideoSummary'
        shorts:
          type: array
          description: Present when returning Shorts.
          items:
            $ref: '#/components/schemas/YouTubeVideoSummary'
        continuationToken:
          type: string
          nullable: true
      additionalProperties: true
    YouTubeVideoRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Full YouTube video URL.
        get_transcript:
          type: boolean
          description: When true, include transcript segments.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TranscriptSegment:
      type: object
      properties:
        text:
          type: string
        startMs:
          type: string
        endMs:
          type: string
        startTimeText:
          type: string
      additionalProperties: true
    YouTubeVideoResponse:
      type: object
      properties:
        id:
          type: string
        thumbnail:
          type: string
          format: uri
        type:
          type: string
        title:
          type: string
        description:
          type: string
        commentCountText:
          type: string
          nullable: true
        commentCountInt:
          type: integer
          nullable: true
        likeCountText:
          type: string
          nullable: true
        likeCountInt:
          type: integer
          nullable: true
        viewCountText:
          type: string
          nullable: true
        viewCountInt:
          type: integer
          nullable: true
        publishDateText:
          type: string
          nullable: true
        publishDate:
          type: string
          format: date-time
          nullable: true
        channel:
          type: object
          additionalProperties: true
        durationMs:
          type: integer
          nullable: true
        durationFormatted:
          type: string
          nullable: true
        watchNextVideos:
          type: array
          items:
            $ref: '#/components/schemas/YouTubeVideoSummary'
        keywords:
          type: array
          items:
            type: string
        transcript:
          type: array
          items:
            $ref: '#/components/schemas/TranscriptSegment'
        transcript_only_text:
          type: string
          nullable: true
      additionalProperties: true
    YouTubeCommentsRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        continuationToken:
          type: string
          description: Token to fetch the next page of comments.
        order:
          type: string
          enum:
            - top
            - newest
          default: top
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    YouTubeComment:
      type: object
      properties:
        id:
          type: string
        content:
          type: string
        publishedTimeText:
          type: string
          nullable: true
        publishedTime:
          type: string
          format: date-time
          nullable: true
        replyLevel:
          type: integer
          minimum: 0
        author:
          type: object
          properties:
            name:
              type: string
            channelId:
              type: string
            isVerified:
              type: boolean
            isCreator:
              type: boolean
            avatarUrl:
              type: string
              format: uri
            channelUrl:
              type: string
              format: uri
          additionalProperties: true
        engagement:
          type: object
          properties:
            likes:
              type: integer
              nullable: true
            replies:
              type: integer
              nullable: true
          additionalProperties: false
      additionalProperties: true
    YouTubeCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/YouTubeComment'
        continuationToken:
          type: string
          nullable: true
      additionalProperties: true
    YouTubeSearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        uploadDate:
          type: string
          description: Optional upload-date filter forwarded to the upstream provider.
        sortBy:
          type: string
          description: Optional sort mode forwarded to the upstream provider.
        filter:
          type: string
          description: Optional result filter forwarded to the upstream provider.
        continuationToken:
          type: string
        includeExtras:
          type: string
          description: Optional upstream flag forwarded to request additional metadata.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    YouTubeSearchResponse:
      type: object
      properties:
        videos:
          type: array
          items:
            $ref: '#/components/schemas/YouTubeVideoSummary'
        channels:
          type: array
          items:
            type: object
            additionalProperties: true
        playlists:
          type: array
          items:
            type: object
            additionalProperties: true
        shorts:
          type: array
          items:
            $ref: '#/components/schemas/YouTubeVideoSummary'
        continuationToken:
          type: string
          nullable: true
      additionalProperties: true
    YouTubeTranscriptRequest:
      type: object
      required:
        - videoUrl
      properties:
        videoUrl:
          type: string
          format: uri
          description: Full YouTube video URL.
        preferredLanguage:
          type: string
          description: Preferred transcript language code. If unavailable, DumplingAI falls back to the first available transcript language for the video.
        includeTimestamps:
          type: boolean
          description: Include timestamps in the transcript output.
        timestampsToCombine:
          type: integer
          minimum: 1
          description: Number of consecutive transcript segments to merge.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    YouTubeTranscriptResponse:
      type: object
      properties:
        language:
          type: string
          description: Transcript language returned by the API. This may differ from `preferredLanguage` when DumplingAI falls back to the first available transcript.
        transcript:
          type: string
          description: Transcript formatted as newline separated segments.
      additionalProperties: true
    TikTokProfileRequest:
      type: object
      required:
        - handle
      properties:
        handle:
          type: string
          description: TikTok username without the leading @.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokProfileResponse:
      type: object
      properties:
        user:
          type: object
          additionalProperties: true
        stats:
          type: object
          additionalProperties: true
        itemList:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    TikTokVideoSummary:
      type: object
      properties:
        aweme_id:
          type: string
        id:
          type: string
        desc:
          type: string
          nullable: true
        create_time:
          type: integer
          nullable: true
        statistics:
          type: object
          additionalProperties: true
        video:
          type: object
          additionalProperties: true
        author:
          type: object
          additionalProperties: true
      additionalProperties: true
    TikTokProfileVideosRequest:
      type: object
      required:
        - handle
      properties:
        handle:
          type: string
        maxCursor:
          type: string
          description: Cursor for pagination.
        trim:
          type: boolean
          description: When true, returns a simplified payload.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokProfileVideosResponse:
      type: object
      properties:
        aweme_list:
          type: array
          items:
            $ref: '#/components/schemas/TikTokVideoSummary'
        max_cursor:
          type: string
          nullable: true
        min_cursor:
          type: string
          nullable: true
        has_more:
          type: integer
          nullable: true
        hasMore:
          type: boolean
          nullable: true
        extra:
          type: object
          additionalProperties: true
      additionalProperties: true
    TikTokVideoRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokVideoResponse:
      type: object
      properties:
        id:
          type: string
        desc:
          type: string
        createTime:
          type: integer
          nullable: true
        createTimeISO:
          type: string
          format: date-time
          nullable: true
        video:
          type: object
          additionalProperties: true
        author:
          type: object
          additionalProperties: true
        music:
          type: object
          additionalProperties: true
        challenges:
          type: array
          items:
            type: object
            additionalProperties: true
        stats:
          type: object
          additionalProperties: true
        textExtra:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    TikTokVideoCommentsRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        cursor:
          type: number
          description: Cursor for pagination.
        count:
          type: number
          description: Number of comments per page.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokComment:
      type: object
      properties:
        cid:
          type: string
        text:
          type: string
        create_time:
          type: integer
          nullable: true
        digg_count:
          type: integer
          nullable: true
        reply_comment_total:
          type: integer
          nullable: true
        user:
          type: object
          additionalProperties: true
        reply_comment:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    TikTokVideoCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/TikTokComment'
        cursor:
          type: number
          nullable: true
        hasMore:
          type: boolean
          nullable: true
        total:
          type: integer
          nullable: true
      additionalProperties: true
    TikTokFollowersRequest:
      type: object
      required:
        - handle
      properties:
        handle:
          type: string
        minTime:
          type: number
          description: Cursor for pagination.
        count:
          type: number
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokFollowersResponse:
      type: object
      properties:
        followers:
          type: array
          items:
            type: object
            additionalProperties: true
        maxCursor:
          type: number
          nullable: true
        minCursor:
          type: number
          nullable: true
        hasMore:
          type: boolean
          nullable: true
        total:
          type: integer
          nullable: true
      additionalProperties: true
    TikTokFollowingRequest:
      type: object
      required:
        - handle
      properties:
        handle:
          type: string
        minTime:
          type: number
        count:
          type: number
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokFollowingResponse:
      type: object
      properties:
        followingList:
          type: array
          items:
            type: object
            additionalProperties: true
        maxCursor:
          type: number
          nullable: true
        minCursor:
          type: number
          nullable: true
        hasMore:
          type: boolean
          nullable: true
        total:
          type: integer
          nullable: true
      additionalProperties: true
    TikTokTranscriptRequest:
      type: object
      required:
        - videoUrl
      properties:
        videoUrl:
          type: string
          format: uri
        preferredLanguage:
          type: string
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokTranscriptResponse:
      type: object
      properties:
        transcript:
          type: string
        language:
          type: string
        id:
          type: string
          nullable: true
        originalUrl:
          type: string
          format: uri
          nullable: true
      additionalProperties: true
    TikTokUserSearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        cursor:
          type: number
        count:
          type: number
        requestSource:
          $ref: '#/components/schemas/RequestSource'
    TikTokUserSearchResponse:
      type: object
      properties:
        userList:
          type: array
          items:
            type: object
            additionalProperties: true
        cursor:
          type: number
          nullable: true
        hasMore:
          type: boolean
          nullable: true
      additionalProperties: true
    ScrapeRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: The URL to scrape
        format:
          type: string
          enum:
            - markdown
            - html
            - screenshot
          default: markdown
          description: Output format for the scraped content
        cleaned:
          type: boolean
          default: true
          description: Whether to return cleaned/simplified content
        renderJs:
          type: boolean
          default: true
          description: Whether to execute JavaScript on the page before scraping
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ScrapeResponse:
      type: object
      properties:
        title:
          type: string
          description: Page title
        url:
          type: string
          format: uri
          description: Final URL after redirects
        content:
          type: string
          description: Scraped content in requested format
        metadata:
          type: object
          additionalProperties: true
          description: Additional page metadata
      additionalProperties: true
    MessageContentPart:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: Type of message part such as `text`, `image`, or `tool-call`.
        text:
          type: string
          description: Text content for `text` message parts.
        data:
          type: object
          additionalProperties: true
          description: Additional structured data associated with the part.
      additionalProperties: true
    ModelMessage:
      type: object
      description: Message exchanged with an agent or language model.
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: Role of the message author.
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          description: Message content. Accepts simple strings or structured message parts.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/MessageContentPart'
            - type: object
              additionalProperties: true
        providerOptions:
          type: object
          additionalProperties: true
          description: Provider-specific metadata passed through to the underlying language model.
      additionalProperties: false
    AgentCompletionRequest:
      type: object
      description: Parameters required to request an agent completion.
      required:
        - agentId
        - messages
      properties:
        agentId:
          type: string
          description: Identifier of the agent to run.
        threadId:
          type: string
          description: Optional thread identifier for continuing a previous conversation.
        messages:
          type: array
          description: Ordered conversation history sent to the agent.
          items:
            $ref: '#/components/schemas/ModelMessage'
        parseJson:
          type: boolean
          description: When true, attempt to parse the final response as JSON.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    AgentCompletionUsage:
      type: object
      required:
        - promptTokens
        - completionTokens
        - totalTokens
      properties:
        promptTokens:
          type: integer
        completionTokens:
          type: integer
        totalTokens:
          type: integer
      additionalProperties: false
    AgentCompletionToolCall:
      type: object
      required:
        - type
        - toolCallId
        - toolName
      properties:
        type:
          type: string
          enum:
            - tool-call
        toolCallId:
          type: string
        toolName:
          type: string
        args:
          type: object
          additionalProperties: true
      additionalProperties: false
    AgentCompletionToolResult:
      type: object
      required:
        - toolCallId
        - toolName
      properties:
        toolCallId:
          type: string
        toolName:
          type: string
        result:
          type: object
          additionalProperties: true
      additionalProperties: false
    AgentCompletionStep:
      type: object
      required:
        - finishReason
        - usage
      properties:
        text:
          type: string
          nullable: true
        toolCalls:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AgentCompletionToolCall'
        toolResults:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AgentCompletionToolResult'
        finishReason:
          type: string
        usage:
          $ref: '#/components/schemas/AgentCompletionUsage'
      additionalProperties: false
    AgentCompletionResponse:
      type: object
      required:
        - text
        - stepsTaken
        - steps
        - tokenUsage
        - creditUsage
        - threadId
      properties:
        text:
          type: string
        stepsTaken:
          type: integer
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AgentCompletionStep'
        tokenUsage:
          $ref: '#/components/schemas/AgentCompletionUsage'
        creditUsage:
          type: integer
        threadId:
          type: string
        parsedJson:
          description: Parsed JSON extracted from the final assistant text when `parseJson` is true.
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items: {}
      additionalProperties: false
    AiImageInput:
      type: object
      description: Model-specific parameters for AI image generation. Fields vary by selected model.
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: Text description of the desired image.
        seed:
          type: integer
          description: Random seed to reproduce a previous generation.
        num_outputs:
          type: integer
          minimum: 1
          maximum: 4
          description: Number of images to generate.
        aspect_ratio:
          type: string
          description: Desired aspect ratio (e.g., `1:1`, `16:9`).
        output_format:
          type: string
          enum:
            - webp
            - jpg
            - png
          description: File format for generated images.
        output_quality:
          type: integer
          minimum: 0
          maximum: 100
          description: Quality level for lossy image formats.
        num_inference_steps:
          type: integer
          minimum: 1
          description: Number of denoising steps to perform.
        guidance:
          type: number
          description: Guidance scale to balance creativity versus prompt adherence.
        prompt_strength:
          type: number
          minimum: 0
          maximum: 1
          description: Strength of the prompt when using image-to-image workflows.
        image:
          type: string
          format: uri
          description: Input image URL for image-to-image generation.
        input_image:
          type: string
          format: uri
          description: Reference image URL when using edit models.
        steps:
          type: integer
          description: Number of diffusion steps for certain models.
        width:
          type: integer
          description: Output width in pixels when using custom aspect ratios.
        height:
          type: integer
          description: Output height in pixels when using custom aspect ratios.
        interval:
          type: number
          description: Controls output variance for FLUX Pro models.
        disable_safety_checker:
          type: boolean
          description: Disable the upstream model safety checker where supported.
        go_fast:
          type: boolean
          description: Run the model in a speed-optimized configuration when available.
        megapixels:
          type: string
          description: Approximate megapixel target for the generated image.
        safety_tolerance:
          type: integer
          description: Safety threshold for filtering sensitive generations.
        prompt_upsampling:
          type: boolean
          description: Allow the provider to enhance the prompt for higher quality results.
        size:
          type: string
          description: Canvas dimensions for models that accept fixed sizes (e.g., `1024x1024`).
        style:
          type: string
          description: Artistic style preset for Recraft models.
        num_images:
          type: integer
          minimum: 1
          description: Legacy field for number of images (maps to `num_outputs`).
        image_size:
          type: string
          description: Legacy field used by some automation templates to express aspect ratio.
      additionalProperties: true
    GenerateAiImageRequest:
      type: object
      description: Parameters used to generate AI images through DumplingAI providers.
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Identifier of the image model to run.
          enum:
            - FLUX.1-schnell
            - FLUX.1-dev
            - FLUX.1-pro
            - FLUX.1.1-pro
            - FLUX.1-kontext-pro
            - recraft-v3
        input:
          $ref: '#/components/schemas/AiImageInput'
        permanent:
          type: boolean
          description: When true, request permanent storage of generated assets.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    GenerateAiImageResponse:
      type: object
      required:
        - images
        - prompt
        - creditUsage
        - model
      properties:
        images:
          type: array
          items:
            type: object
            required:
              - url
            properties:
              url:
                type: string
                format: uri
            additionalProperties: false
        prompt:
          type: string
        creditUsage:
          type: integer
        model:
          type: string
      additionalProperties: false
    CodeExecutionRequest:
      type: object
      description: Request payload for sandboxed code execution.
      required:
        - code
      properties:
        code:
          type: string
          description: Source code to execute inside the sandbox.
        commands:
          type: array
          description: Shell commands to run before executing the code.
          items:
            type: string
        parseJson:
          type: boolean
          description: Attempt to parse stdout/stderr as JSON arrays.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    CodeExecutionLogValue:
      description: Captured log output, returned either as raw lines or parsed JSON when `parseJson` is enabled.
      oneOf:
        - type: array
          items:
            type: string
        - type: object
          additionalProperties: true
        - type: array
          items: {}
        - type: string
        - type: number
        - type: boolean
    CodeExecutionResponse:
      type: object
      required:
        - logs
      properties:
        logs:
          type: object
          required:
            - stdout
            - stderr
          properties:
            stdout:
              $ref: '#/components/schemas/CodeExecutionLogValue'
            stderr:
              $ref: '#/components/schemas/CodeExecutionLogValue'
          additionalProperties: false
      additionalProperties: false
    CrawlRequest:
      type: object
      description: Parameters controlling a crawl job.
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Root URL to crawl.
        depth:
          type: integer
          minimum: 1
          default: 2
          description: Maximum crawl depth.
        limit:
          type: integer
          minimum: 1
          default: 5
          description: Maximum number of pages to fetch.
        format:
          type: string
          enum:
            - markdown
            - text
            - raw
          default: markdown
          description: Output format for the crawled pages.
        requestSource:
          type: string
          description: Optional request source identifier.
      additionalProperties: false
    CrawlResponse:
      type: object
      required:
        - url
        - format
        - depth
        - limit
        - pages
        - results
        - creditUsage
      properties:
        url:
          type: string
          format: uri
        format:
          type: string
          enum:
            - markdown
            - text
            - raw
        depth:
          type: integer
        limit:
          type: integer
        pages:
          type: integer
        results:
          type: array
          items:
            type: object
            additionalProperties: true
        creditUsage:
          type: integer
      additionalProperties: false
    ScreenshotViewport:
      type: object
      description: Browser viewport size in pixels.
      required:
        - width
        - height
      properties:
        width:
          type: integer
          minimum: 1
          maximum: 3840
        height:
          type: integer
          minimum: 1
          maximum: 10240
      additionalProperties: false
    ScreenshotClipRectangle:
      type: object
      description: Clipping rectangle when capturing a partial screenshot.
      required:
        - top
        - left
        - width
        - height
      properties:
        top:
          type: number
        left:
          type: number
        width:
          type: number
        height:
          type: number
      additionalProperties: false
    ScreenshotRequest:
      type: object
      description: Options for capturing a screenshot of a webpage.
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Fully-qualified URL to capture.
        fullPage:
          type: boolean
          default: false
          description: Capture the entire scrollable page.
        viewport:
          $ref: '#/components/schemas/ScreenshotViewport'
        clipRectangle:
          $ref: '#/components/schemas/ScreenshotClipRectangle'
        blockCookieBanners:
          type: boolean
          default: true
          description: Attempt to hide cookie banners before capturing the screenshot.
        wait:
          type: integer
          minimum: 0
          maximum: 5000
          default: 0
          description: Delay in milliseconds before capturing, allowing the page to finish loading.
        autoScroll:
          type: boolean
          default: false
          description: Scroll the page to trigger lazy-loaded content before capturing.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ScreenshotResponse:
      type: object
      required:
        - screenshotUrl
      properties:
        screenshotUrl:
          type: string
          format: uri
          description: Temporary download URL for the generated screenshot.
      additionalProperties: false
    FileInputMethod:
      type: string
      description: Indicates whether binary content is supplied via URL or base64-encoded string.
      enum:
        - url
        - base64
    ExtractRequest:
      type: object
      required:
        - url
        - schema
      properties:
        url:
          type: string
          format: uri
          description: Fully-qualified URL to extract content from.
        schema:
          type: object
          description: JSON schema describing the structure of the extracted data.
          additionalProperties: true
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ExtractResponse:
      type: object
      required:
        - screenshotUrl
        - results
      properties:
        screenshotUrl:
          type: string
          format: uri
          description: Temporary URL pointing to the captured screenshot of the source page.
        results:
          type: object
          description: Data extracted according to the provided schema.
          additionalProperties: true
      additionalProperties: true
    ExtractDocumentRequest:
      type: object
      required:
        - inputMethod
        - files
        - prompt
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        files:
          type: array
          minItems: 1
          description: Array of publicly accessible URLs or base64-encoded document contents.
          items:
            type: string
        fileExtension:
          type: string
          description: "File extension for the provided documents (e.g., '.pdf', '.docx', or 'autodetect'). Defaults to '.pdf'."
        prompt:
          type: string
          description: Instructions that describe the structured data to extract from the documents.
        jsonMode:
          type: boolean
          description: When true, requests the model to respond with JSON-formatted output.
          default: false
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ExtractDocumentResponse:
      type: object
      required:
        - results
        - prompt
        - pages
        - fileCount
        - creditUsage
      properties:
        results:
          type: string
          description: Model output returned from the extraction prompt.
        prompt:
          type: string
          description: Prompt that was sent to the extraction model.
        pages:
          type: integer
          description: Total number of document pages processed.
        fileCount:
          type: integer
          description: Number of documents included in the request.
        creditUsage:
          type: integer
          description: Credits consumed while processing the request.
      additionalProperties: false
    ExtractPdfRequest:
      type: object
      description: Extract structured information from one or more PDF files using Gemini.
      required:
        - inputMethod
        - files
        - prompt
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        files:
          type: array
          minItems: 1
          description: Array of PDF URLs or base64-encoded strings.
          items:
            type: string
        prompt:
          type: string
          description: Instructions describing the structure to extract from the PDFs.
        jsonMode:
          type: boolean
          default: false
          description: When true, requests a JSON-formatted response from the model.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ExtractPdfResponse:
      type: object
      properties:
        results:
          type: string
          description: Model response generated from the supplied prompt.
        prompt:
          type: string
          description: Prompt echoed back for reference.
        pages:
          type: integer
          description: Total number of PDF pages processed.
        fileCount:
          type: integer
          description: Number of PDF files included in the request.
        creditUsage:
          type: integer
          description: Credits consumed while processing the PDFs.
      required:
        - results
        - prompt
        - pages
        - fileCount
        - creditUsage
      additionalProperties: false
    ExtractImageRequest:
      type: object
      required:
        - inputMethod
        - images
        - prompt
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        images:
          type: array
          minItems: 1
          description: Array of image URLs or base64-encoded strings to analyze.
          items:
            type: string
        prompt:
          type: string
          description: Instructions that describe the insights to extract from the images.
        jsonMode:
          type: boolean
          description: When true, requests the model to respond with JSON-formatted output.
          default: false
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ExtractImageResponse:
      type: object
      required:
        - results
        - prompt
        - imageCount
        - creditUsage
      properties:
        results:
          type: string
          description: Model output returned from the extraction prompt.
        prompt:
          type: string
        imageCount:
          type: integer
          description: Number of images processed.
        creditUsage:
          type: integer
          description: Credits consumed while processing the request.
      additionalProperties: false
    ExtractVideoRequest:
      type: object
      required:
        - inputMethod
        - video
        - prompt
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        video:
          type: string
          description: Video URL or base64-encoded video content to analyze.
        prompt:
          type: string
          description: Instructions describing the insights to extract from the video.
        jsonMode:
          type: boolean
          description: When true, requests the model to respond with JSON-formatted output.
          default: false
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ExtractVideoResponse:
      type: object
      required:
        - results
        - prompt
        - videoDuration
        - creditUsage
      properties:
        results:
          type: string
          description: Model output returned from the extraction prompt.
        prompt:
          type: string
        videoDuration:
          type: number
          format: float
          description: Duration of the processed video in seconds.
        creditUsage:
          type: integer
          description: Credits consumed while processing the request.
      additionalProperties: false
    ExtractAudioRequest:
      type: object
      required:
        - inputMethod
        - audio
        - prompt
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        audio:
          type: string
          description: Audio URL or base64-encoded audio content to analyze.
        prompt:
          type: string
          description: Instructions describing the insights to extract from the audio.
        jsonMode:
          type: boolean
          description: When true, requests the model to respond with JSON-formatted output.
          default: false
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ExtractAudioResponse:
      type: object
      required:
        - results
        - prompt
        - audioDuration
        - creditUsage
      properties:
        results:
          type: string
          description: Model output returned from the extraction prompt.
        prompt:
          type: string
        audioDuration:
          type: number
          format: float
          description: Duration of the processed audio in seconds.
        creditUsage:
          type: integer
          description: Credits consumed while processing the request.
      additionalProperties: false
    DocToTextRequest:
      type: object
      required:
        - inputMethod
        - file
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        file:
          type: string
          description: Document URL or base64-encoded file content to convert to text.
        pages:
          type: string
          description: "Optional page ranges to extract (e.g., '1-3,5')."
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    DocToTextResponse:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Plain text extracted from the source document.
      additionalProperties: false
    ConvertToPdfRequest:
      type: object
      required:
        - inputMethod
        - file
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        file:
          type: string
          description: Document URL or base64-encoded content to convert to PDF.
      additionalProperties: false
    ConvertToPdfResponse:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Temporary download URL for the converted PDF.
      additionalProperties: false
    MergePdfsRequest:
      type: object
      required:
        - inputMethod
        - files
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        files:
          type: array
          minItems: 2
          description: Array of PDF URLs or base64-encoded PDF contents to merge.
          items:
            type: string
        metadata:
          type: object
          description: Optional metadata map to embed within the merged PDF.
          additionalProperties: true
        pdfa:
          type: string
          description: Optional PDF/A compliance level to apply when merging.
          enum:
            - PDF/A-1b
            - PDF/A-2b
            - PDF/A-3b
        pdfua:
          type: boolean
          description: Whether to attempt enabling PDF/UA compliance.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    MergePdfsResponse:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Temporary download URL for the merged PDF.
      additionalProperties: false
    TrimVideoRequest:
      type: object
      required:
        - videoUrl
        - startTimestamp
        - endTimestamp
      properties:
        videoUrl:
          type: string
          format: uri
          description: Publicly accessible MP4 URL to trim.
        startTimestamp:
          type: string
          description: Start timecode for the trim in HH:MM:SS or HH:MM:SS.mmm format.
        endTimestamp:
          type: string
          description: End timecode for the trim in HH:MM:SS or HH:MM:SS.mmm format.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    TrimVideoResponse:
      type: object
      required:
        - trimmedVideoUrl
        - creditsUsed
      properties:
        trimmedVideoUrl:
          type: string
          format: uri
          description: Temporary download URL for the trimmed video asset.
        creditsUsed:
          type: integer
          description: Credits consumed while processing the request.
      additionalProperties: false
    ReadPdfMetadataRequest:
      type: object
      required:
        - inputMethod
        - files
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        files:
          type: array
          minItems: 1
          description: Array of PDF URLs or base64-encoded PDF contents whose metadata should be read.
          items:
            type: string
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    ReadPdfMetadataResponse:
      type: object
      description: Metadata extracted for each supplied PDF file.
      additionalProperties: true
    WritePdfMetadataRequest:
      type: object
      required:
        - inputMethod
        - files
        - metadata
      properties:
        inputMethod:
          $ref: '#/components/schemas/FileInputMethod'
        files:
          type: array
          minItems: 1
          description: Array of PDF URLs or base64-encoded PDF contents to update.
          items:
            type: string
        metadata:
          type: object
          description: Key-value metadata pairs to write into the PDF.
          additionalProperties: true
      additionalProperties: false
    WritePdfMetadataResponse:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Temporary download URL for the updated PDF (or ZIP when multiple files are provided).
      additionalProperties: false
    AutocompleteRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: Search phrase to autocomplete.
        location:
          type: string
          description: Free-form location context used by the upstream provider.
        country:
          type: string
          description: 2-letter country code forwarded to the provider as `gl`.
        language:
          type: string
          description: Language code forwarded to the provider as `hl`.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    AutocompleteSuggestion:
      type: object
      properties:
        value:
          type: string
      required:
        - value
      additionalProperties: false
    AutocompleteResponse:
      type: object
      properties:
        searchParameters:
          type: object
          properties:
            q:
              type: string
            gl:
              type: string
              nullable: true
            hl:
              type: string
              nullable: true
            type:
              type: string
              nullable: true
            location:
              type: string
              nullable: true
            engine:
              type: string
              nullable: true
          required:
            - q
          additionalProperties: true
        suggestions:
          type: array
          items:
            $ref: '#/components/schemas/AutocompleteSuggestion'
      required:
        - searchParameters
        - suggestions
      additionalProperties: true
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        country:
          type: string
          description: 2-letter country code forwarded as `gl`.
        location:
          type: string
          description: Free-form location context forwarded to the provider.
        language:
          type: string
          description: Interface language forwarded as `hl`.
        dateRange:
          type: string
          description: Temporal filter applied to the search results.
          enum:
            - pastHour
            - pastDay
            - pastWeek
            - pastMonth
            - pastYear
            - anyTime
        page:
          type: integer
          minimum: 1
        scrapeResults:
          type: boolean
          default: false
          description: When true, the service will scrape top organic results for rich content.
        numResultsToScrape:
          type: integer
          minimum: 1
          maximum: 10
          default: 3
        scrapeOptions:
          type: object
          properties:
            format:
              type: string
              enum:
                - markdown
                - html
                - screenshot
            cleaned:
              type: boolean
          additionalProperties: false
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    SearchScrapeOutput:
      type: object
      properties:
        title:
          type: string
        metadata:
          type: object
          additionalProperties: true
        url:
          type: string
          format: uri
        format:
          type: string
        cleaned:
          type: boolean
        content:
          type: string
      additionalProperties: true
    SearchOrganicResult:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
          format: uri
        snippet:
          type: string
        position:
          type: integer
        sitelinks:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              link:
                type: string
                format: uri
            required:
              - title
              - link
            additionalProperties: false
        date:
          type: string
          nullable: true
        scrapeOutput:
          $ref: '#/components/schemas/SearchScrapeOutput'
      required:
        - title
        - link
        - snippet
        - position
      additionalProperties: true
    SearchFeaturedSnippet:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
          format: uri
        snippet:
          type: string
        position:
          type: integer
        type:
          type: string
      required:
        - title
        - link
        - snippet
        - position
        - type
      additionalProperties: true
    SearchPeopleAlsoAsk:
      type: object
      properties:
        question:
          type: string
        snippet:
          type: string
        title:
          type: string
        link:
          type: string
          format: uri
      required:
        - question
        - snippet
        - title
        - link
      additionalProperties: true
    SearchResponse:
      type: object
      properties:
        searchParameters:
          type: object
          properties:
            q:
              type: string
            type:
              type: string
            engine:
              type: string
            gl:
              type: string
              nullable: true
            hl:
              type: string
              nullable: true
          required:
            - q
            - type
            - engine
          additionalProperties: true
        organic:
          type: array
          items:
            $ref: '#/components/schemas/SearchOrganicResult'
        featuredSnippet:
          $ref: '#/components/schemas/SearchFeaturedSnippet'
        relatedSearches:
          type: array
          items:
            type: object
            properties:
              query:
                type: string
            required:
              - query
            additionalProperties: false
        peopleAlsoAsk:
          type: array
          items:
            $ref: '#/components/schemas/SearchPeopleAlsoAsk'
      required:
        - searchParameters
        - organic
      additionalProperties: true
    NewsSearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        country:
          type: string
        location:
          type: string
        language:
          type: string
        dateRange:
          type: string
          enum:
            - pastHour
            - pastDay
            - pastWeek
            - pastMonth
            - pastYear
            - anyTime
        page:
          type: integer
          minimum: 1
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    NewsArticle:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
          format: uri
        snippet:
          type: string
        date:
          type: string
        source:
          type: string
        imageUrl:
          type: string
          format: uri
          nullable: true
        position:
          type: integer
      required:
        - title
        - link
        - snippet
        - date
        - source
        - position
      additionalProperties: false
    NewsSearchResponse:
      type: object
      properties:
        searchParameters:
          type: object
          properties:
            q:
              type: string
            gl:
              type: string
              nullable: true
            type:
              type: string
            location:
              type: string
              nullable: true
            engine:
              type: string
          required:
            - q
            - type
            - engine
          additionalProperties: true
        news:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
      required:
        - searchParameters
        - news
      additionalProperties: true
    PlacesSearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        country:
          type: string
        location:
          type: string
        language:
          type: string
        page:
          type: integer
          minimum: 1
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    PlacesResult:
      type: object
      properties:
        position:
          type: integer
        title:
          type: string
        address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        website:
          type: string
          format: uri
          nullable: true
        cid:
          type: string
        rating:
          type: number
          nullable: true
        ratingCount:
          type: integer
          nullable: true
        category:
          type: string
          nullable: true
        phoneNumber:
          type: string
          nullable: true
      required:
        - position
        - title
        - address
        - latitude
        - longitude
        - cid
      additionalProperties: false
    PlacesSearchResponse:
      type: object
      properties:
        searchParameters:
          type: object
          properties:
            q:
              type: string
            gl:
              type: string
              nullable: true
            type:
              type: string
            location:
              type: string
              nullable: true
            engine:
              type: string
          required:
            - q
            - type
            - engine
          additionalProperties: true
        places:
          type: array
          items:
            $ref: '#/components/schemas/PlacesResult'
      required:
        - searchParameters
        - places
      additionalProperties: true
    MapsSearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        gpsPositionZoom:
          type: string
          description: Combined latitude,longitude,zoom string forwarded as `ll`.
        placeId:
          type: string
        cid:
          type: string
        language:
          type: string
        page:
          type: integer
          minimum: 1
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    MapsPlaceResult:
      type: object
      properties:
        position:
          type: integer
        title:
          type: string
        address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        type:
          type: string
          nullable: true
        types:
          type: array
          items:
            type: string
        website:
          type: string
          format: uri
          nullable: true
        openingHours:
          type: object
          additionalProperties:
            type: string
        thumbnailUrl:
          type: string
          format: uri
          nullable: true
        cid:
          type: string
        fid:
          type: string
          nullable: true
        placeId:
          type: string
          nullable: true
      required:
        - position
        - title
        - address
        - latitude
        - longitude
        - cid
      additionalProperties: true
    MapsSearchResponse:
      type: object
      properties:
        searchParameters:
          type: object
          properties:
            q:
              type: string
            type:
              type: string
            engine:
              type: string
          required:
            - q
            - type
            - engine
          additionalProperties: true
        ll:
          type: string
          nullable: true
        places:
          type: array
          items:
            $ref: '#/components/schemas/MapsPlaceResult'
      required:
        - searchParameters
        - places
      additionalProperties: true
    GoogleReviewsRequest:
      type: object
      description: >
        Parameters for fetching Google Business reviews. Provide at least one identifier (keyword, cid, or placeId).
      properties:
        keyword:
          type: string
          description: Business name or query string.
        cid:
          type: string
          description: Google CID identifier for the business.
        placeId:
          type: string
          description: Google Place ID for the business.
        reviews:
          type: integer
          minimum: 1
          default: 10
          description: Maximum number of reviews to return.
        language:
          type: string
          default: en
          description: ISO language code for the review content.
        location:
          type: string
          default: London,England,United Kingdom
          description: Location bias used when searching by keyword.
        sortBy:
          type: string
          enum:
            - relevant
            - newest
            - highest_rating
            - lowest_rating
          default: relevant
          description: Sorting strategy for returned reviews.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    GoogleReviewRating:
      type: object
      properties:
        rating_type:
          type: string
        value:
          type: number
        votes_count:
          type: integer
          nullable: true
        rating_max:
          type: number
      required:
        - rating_type
        - value
        - rating_max
      additionalProperties: false
    GoogleReviewImage:
      type: object
      properties:
        type:
          type: string
        alt:
          type: string
          nullable: true
        url:
          type: string
          format: uri
        image_url:
          type: string
          format: uri
      required:
        - type
        - url
        - image_url
      additionalProperties: false
    GoogleReview:
      type: object
      properties:
        type:
          type: string
        rank_group:
          type: integer
        rank_absolute:
          type: integer
        position:
          type: string
        review_text:
          type: string
        original_review_text:
          type: string
          nullable: true
        time_ago:
          type: string
        timestamp:
          type: string
        rating:
          $ref: '#/components/schemas/GoogleReviewRating'
        reviews_count:
          type: integer
        photos_count:
          type: integer
        local_guide:
          type: boolean
        profile_name:
          type: string
        profile_url:
          type: string
          format: uri
        review_url:
          type: string
          format: uri
        profile_image_url:
          type: string
          format: uri
        owner_answer:
          type: string
          nullable: true
        original_owner_answer:
          type: string
          nullable: true
        owner_time_ago:
          type: string
          nullable: true
        owner_timestamp:
          type: string
          nullable: true
        review_id:
          type: string
        images:
          type: array
          items:
            $ref: '#/components/schemas/GoogleReviewImage'
          nullable: true
      required:
        - type
        - rank_group
        - rank_absolute
        - position
        - review_text
        - time_ago
        - timestamp
        - rating
        - reviews_count
        - photos_count
        - local_guide
        - profile_name
        - profile_url
        - review_url
        - profile_image_url
        - review_id
      additionalProperties: false
    GoogleReviewsResponse:
      type: object
      properties:
        keyword:
          type: string
          nullable: true
        type:
          type: string
        se_domain:
          type: string
        location_code:
          type: integer
        language_code:
          type: string
        check_url:
          type: string
          format: uri
        datetime:
          type: string
        title:
          type: string
        sub_title:
          type: string
        rating:
          $ref: '#/components/schemas/GoogleReviewRating'
        feature_id:
          type: string
        place_id:
          type: string
        cid:
          type: string
        reviews_count:
          type: integer
        items_count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/GoogleReview'
      required:
        - type
        - se_domain
        - location_code
        - language_code
        - check_url
        - datetime
        - title
        - rating
        - feature_id
        - place_id
        - cid
        - reviews_count
        - items_count
        - items
      additionalProperties: true
    LinkedInProfileRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Full LinkedIn profile URL (`https://www.linkedin.com/in/...`).
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    LinkedInProfileResponse:
      type: object
      properties:
        success:
          type: boolean
        name:
          type: string
        image:
          type: string
          format: uri
          nullable: true
        location:
          type: string
          nullable: true
        followers:
          type: integer
          nullable: true
        connections:
          type: string
          nullable: true
        about:
          type: string
          nullable: true
        recentPosts:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              activityType:
                type: string
                nullable: true
              link:
                type: string
                format: uri
                nullable: true
              image:
                type: string
                format: uri
                nullable: true
            required:
              - title
            additionalProperties: false
        activity:
          type: array
          items:
            type: object
            additionalProperties: true
        experience:
          type: array
          items:
            type: object
            additionalProperties: true
        articles:
          type: array
          items:
            type: object
            additionalProperties: true
        education:
          type: array
          items:
            type: object
            additionalProperties: true
        publications:
          type: array
          items:
            type: object
            additionalProperties: true
        projects:
          type: array
          items:
            type: object
            additionalProperties: true
        recommendations:
          type: array
          items:
            type: object
            additionalProperties: true
        similarProfiles:
          type: array
          items:
            type: object
            additionalProperties: true
      required:
        - success
      additionalProperties: true
    LinkedInCompanyRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Full LinkedIn company page URL (`https://www.linkedin.com/company/...`).
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    LinkedInCompanyResponse:
      type: object
      properties:
        success:
          type: boolean
        name:
          type: string
        description:
          type: string
          nullable: true
        location:
          type: object
          properties:
            city:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            country:
              type: string
              nullable: true
          additionalProperties: false
        employeeCount:
          type: integer
          nullable: true
        website:
          type: string
          format: uri
          nullable: true
        logo:
          type: string
          format: uri
          nullable: true
        slogan:
          type: string
          nullable: true
        posts:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
              datePublished:
                type: string
                nullable: true
              text:
                type: string
                nullable: true
            required:
              - url
            additionalProperties: false
        industry:
          type: string
          nullable: true
        size:
          type: string
          nullable: true
        founded:
          type: integer
          nullable: true
        headquarters:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        specialties:
          type: array
          items:
            type: string
        employees:
          type: array
          items:
            type: object
            additionalProperties: true
      required:
        - success
      additionalProperties: true
paths:
  /api/v1/youtube/channel:
    post:
      tags:
        - YouTube
      summary: Get YouTube channel details
      operationId: getYouTubeChannel
      description: >-
        Retrieve rich metadata, social links, and statistics for a YouTube channel.
        Supply a channel ID, handle, or full URL; at least one identifier is required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YouTubeChannelRequest'
            examples:
              byHandle:
                summary: Lookup by handle
                value:
                  handle: '@ThePatMcAfeeShow'
      responses:
        '200':
          description: Channel metadata retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeChannelResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '502':
          description: Upstream YouTube data provider returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/youtube/channel-videos:
    post:
      tags:
        - YouTube
      summary: List channel videos
      operationId: listYouTubeChannelVideos
      description: >-
        Return uploaded long-form videos for a channel with pagination support.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YouTubeChannelVideosRequest'
            examples:
              byChannelId:
                summary: First page by channel ID
                value:
                  channelId: 'UCxcTeAKWJca6XyJ37_ZoKIQ'
      responses:
        '200':
          description: A page of channel videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeChannelVideosResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '502':
          description: Upstream YouTube data provider returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/youtube/channel/shorts:
    post:
      tags:
        - YouTube
      summary: List channel shorts
      operationId: listYouTubeChannelShorts
      description: >-
        Return YouTube Shorts for a given channel with pagination support.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YouTubeChannelShortsRequest'
      responses:
        '200':
          description: A page of channel shorts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeChannelVideosResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '502':
          description: Upstream YouTube data provider returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/youtube/video:
    post:
      tags:
        - YouTube
      summary: Get YouTube video
      operationId: getYouTubeVideo
      description: >-
        Retrieve detailed metadata, statistics, related videos, and optionally transcripts for a YouTube video or short.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YouTubeVideoRequest'
            examples:
              includeTranscript:
                summary: Fetch video with transcript
                value:
                  url: 'https://www.youtube.com/watch?v=PkZNo7MFNFg'
                  get_transcript: true
      responses:
        '200':
          description: Video details retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeVideoResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '502':
          description: Upstream YouTube data provider returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/youtube/video/comments:
    post:
      tags:
        - YouTube
      summary: List YouTube video comments
      operationId: listYouTubeVideoComments
      description: >-
        Retrieve public comments for a video with pagination and sorting controls.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YouTubeCommentsRequest'
      responses:
        '200':
          description: Comments retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeCommentsResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '502':
          description: Upstream YouTube data provider returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/youtube/search:
    post:
      tags:
        - YouTube
      summary: Search YouTube
      operationId: searchYouTube
      description: >-
        Perform keyword searches across videos, shorts, or channels with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YouTubeSearchRequest'
      responses:
        '200':
          description: Search results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeSearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '502':
          description: Upstream YouTube data provider returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-youtube-transcript:
    post:
      tags:
        - YouTube
      summary: Get YouTube transcript
      operationId: getYouTubeTranscript
      description: >-
        Retrieve transcript segments for a YouTube video using DumplingAI's transcript service. If the requested preferred language is unavailable but captions exist in another language, the first available transcript is returned instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YouTubeTranscriptRequest'
      responses:
        '200':
          description: Transcript retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeTranscriptResponse'
        '204':
          description: Transcripts disabled for the requested video.
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '404':
          description: No transcript available for the requested video.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream transcript provider returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-tiktok-profile:
    post:
      tags:
        - TikTok
      summary: Get TikTok profile
      operationId: getTikTokProfile
      description: Fetch public profile metadata and aggregated stats for a TikTok handle.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokProfileRequest'
            examples:
              default:
                summary: Lookup profile
                value:
                  handle: stoolpresidente
      responses:
        '200':
          description: TikTok profile retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokProfileResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient credits to fulfill the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Profile not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream profile service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-tiktok-profile-videos:
    post:
      tags:
        - TikTok
      summary: List TikTok profile videos
      operationId: listTikTokProfileVideos
      description: Retrieve a paginated feed of videos posted by a TikTok handle.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokProfileVideosRequest'
      responses:
        '200':
          description: TikTok videos retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokProfileVideosResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient credits to fulfill the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Videos not found for the provided handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream video service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-tiktok-video:
    post:
      tags:
        - TikTok
      summary: Get TikTok video
      operationId: getTikTokVideo
      description: Retrieve metadata, author details, and engagement stats for a TikTok video URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokVideoRequest'
            examples:
              default:
                summary: Fetch video details
                value:
                  url: https://www.tiktok.com/@stoolpresidente/video/7556301577875639583
      responses:
        '200':
          description: TikTok video retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokVideoResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient credits to fulfill the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Video not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream video service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-tiktok-video-comments:
    post:
      tags:
        - TikTok
      summary: List TikTok video comments
      operationId: listTikTokVideoComments
      description: Fetch comments and replies for a TikTok video with pagination support.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokVideoCommentsRequest'
      responses:
        '200':
          description: TikTok comments retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokVideoCommentsResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient credits to fulfill the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Comments not found for the provided URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream comments service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-tiktok-user-followers:
    post:
      tags:
        - TikTok
      summary: List TikTok followers
      operationId: listTikTokUserFollowers
      description: Retrieve followers for a TikTok account with pagination support.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokFollowersRequest'
      responses:
        '200':
          description: Followers retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokFollowersResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient credits to fulfill the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Followers not found for the provided handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream followers service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-tiktok-user-following:
    post:
      tags:
        - TikTok
      summary: List TikTok following
      operationId: listTikTokUserFollowing
      description: Retrieve accounts followed by a TikTok handle with pagination support.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokFollowingRequest'
      responses:
        '200':
          description: Following list retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokFollowingResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient credits to fulfill the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Following list not found for the provided handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream following service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-tiktok-transcript:
    post:
      tags:
        - TikTok
      summary: Get TikTok transcript
      operationId: getTikTokTranscript
      description: Retrieve a TikTok video's transcript in the requested language.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokTranscriptRequest'
      responses:
        '200':
          description: Transcript retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokTranscriptResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '404':
          description: Transcript not available for the provided video.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream transcript service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/search-tiktok-users:
    post:
      tags:
        - TikTok
      summary: Search TikTok users
      operationId: searchTikTokUsers
      description: Search for TikTok accounts matching a keyword with pagination support.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokUserSearchRequest'
      responses:
        '200':
          description: TikTok user search results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokUserSearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient credits to fulfill the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No users found for the search query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream search service returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/get-autocomplete:
    post:
      tags:
        - Search
      summary: Get autocomplete suggestions
      operationId: getAutocomplete
      description: Retrieve autocomplete suggestions for a partial query across DumplingAI's search providers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutocompleteRequest'
            examples:
              default:
                value:
                  query: dumpling
      responses:
        '200':
          description: Autocomplete suggestions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/search:
    post:
      tags:
        - Search
      summary: Search web content
      operationId: searchWeb
      description: Perform a federated web search returning organic results, snippets, and metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              default:
                value:
                  query: best running shoes
                  scrapeResults: true
      responses:
        '200':
          description: Search results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/search-news:
    post:
      tags:
        - Search
      summary: Search news articles
      operationId: searchNews
      description: Search global news sources and return structured article metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsSearchRequest'
            examples:
              default:
                value:
                  query: AI regulation
                  dateRange: pastWeek
      responses:
        '200':
          description: News results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsSearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/search-places:
    post:
      tags:
        - Search
      summary: Search places
      operationId: searchPlaces
      description: Search for places, businesses, and points of interest with structured metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlacesSearchRequest'
            examples:
              default:
                value:
                  query: coffee shop
                  location: Austin, TX
      responses:
        '200':
          description: Place results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacesSearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/search-maps:
    post:
      tags:
        - Search
      summary: Search maps
      operationId: searchMaps
      description: Retrieve map search results including coordinates and metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapsSearchRequest'
            examples:
              default:
                value:
                  query: dumpling restaurants
                  gpsPositionZoom: "@40.7128,-74.0060,13z"
                  language: en
      responses:
        '200':
          description: Map search results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapsSearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/get-google-reviews:
    post:
      tags:
        - Google
      summary: Get Google reviews
      operationId: getGoogleReviews
      description: Retrieve recent Google reviews, ratings, and review metadata for a business.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleReviewsRequest'
            examples:
              default:
                value:
                  placeId: ChIJN1t_tDeuEmsRUsoyG83frY4
      responses:
        '200':
          description: Google reviews returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleReviewsResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/google-locations:
    get:
      security: []
      tags:
        - Google
      summary: List Google location identifiers
      operationId: listGoogleLocations
      description: Retrieve supported geographic location metadata used for Google-based searches.
      responses:
        '200':
          description: Location catalog returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/linkedin/profile:
    post:
      tags:
        - LinkedIn
      summary: Get LinkedIn profile
      operationId: getLinkedInProfile
      description: Retrieve LinkedIn profile metadata, experience, and statistics for a public profile URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInProfileRequest'
            examples:
              default:
                value:
                  url: https://www.linkedin.com/in/elenaverna/
      responses:
        '200':
          description: LinkedIn profile returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkedInProfileResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/linkedin/company:
    post:
      tags:
        - LinkedIn
      summary: Get LinkedIn company
      operationId: getLinkedInCompany
      description: Retrieve company profile metadata, size, and industry information from LinkedIn.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInCompanyRequest'
            examples:
              default:
                value:
                  url: https://www.linkedin.com/company/checkboxai/
      responses:
        '200':
          description: LinkedIn company returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkedInCompanyResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/agents/generate-completion:
    post:
      tags:
        - AI
      summary: Generate agent completion
      operationId: generateAgentCompletion
      description: Generate a completion from a DumplingAI agent with streaming or sync support.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCompletionRequest'
            examples:
              default:
                value:
                  agentId: agnt_123
                  messages:
                    - role: user
                      content: Summarize this article
      responses:
        '200':
          description: Agent completion returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCompletionResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/generate-ai-image:
    post:
      tags:
        - AI
      summary: Generate AI image
      operationId: generateAIImage
      description: Generate an AI image using DumplingAI's image generation providers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAiImageRequest'
            examples:
              default:
                value:
                  model: FLUX.1-schnell
                  input:
                    prompt: "A dumpling-shaped rocket launching"
                    aspect_ratio: "16:9"
      responses:
        '200':
          description: Image generation task accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateAiImageResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/run-js-code:
    post:
      tags:
        - Developer Tools
      summary: Run JavaScript code
      operationId: runJsCode
      description: Execute sandboxed JavaScript and return stdout, stderr, and logs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodeExecutionRequest'
            examples:
              default:
                value:
                  code: "export default async function main() { return 'hello'; }"
      responses:
        '200':
          description: Execution results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeExecutionResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/run-python-code:
    post:
      tags:
        - Developer Tools
      summary: Run Python code
      operationId: runPythonCode
      description: Execute sandboxed Python code and return stdout, stderr, and logs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodeExecutionRequest'
            examples:
              default:
                value:
                  code: "def main():\n    return 'hi'"
      responses:
        '200':
          description: Execution results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeExecutionResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/scrape:
    post:
      tags:
        - Scraping
      summary: Scrape webpage
      operationId: scrapeWebpage
      description: Fetch structured data and HTML from a URL using DumplingAI's scraper.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeRequest'
            examples:
              default:
                value:
                  url: https://example.com/article
                  format: markdown
                  cleaned: true
                  renderJs: true
      responses:
        '200':
          description: Scraped content returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/crawl:
    post:
      tags:
        - Scraping
      summary: Crawl website
      operationId: crawlWebsite
      description: Crawl a site or sitemap and return captured pages with metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrawlRequest'
            examples:
              default:
                value:
                  url: https://example.com
                  limit: 5
                  depth: 2
      responses:
        '200':
          description: Crawl job accepted or results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/screenshot:
    post:
      tags:
        - Scraping
      summary: Screenshot webpage
      operationId: screenshotWebpage
      description: Capture a full-page screenshot, viewport screenshot, or PDF rendition of a URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenshotRequest'
            examples:
              default:
                value:
                  url: https://example.com
                  fullPage: true
                  viewport:
                    width: 1280
                    height: 720
                  wait: 1000
      responses:
        '200':
          description: Screenshot data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenshotResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/extract:
    post:
      tags:
        - Documents
      summary: Extract structured content
      operationId: extractStructuredContent
      description: Extract structured content from text, HTML, or URLs according to configured extractors.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
            examples:
              default:
                value:
                  url: https://example.com/product-page
                  schema:
                    title: string
                    description: string
                    price: number
                    rating: number
      responses:
        '200':
          description: Extracted content returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/extract-document:
    post:
      tags:
        - Documents
      summary: Extract document to structured JSON
      operationId: extractDocument
      description: Extract structured text and metadata from uploaded documents or document URLs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractDocumentRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  files:
                    - https://example.com/sample.pdf
                  prompt: "Extract the main topics and their summaries from this document."
                  jsonMode: false
      responses:
        '200':
          description: Document extraction returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractDocumentResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/extract-pdf:
    post:
      tags:
        - Documents
      summary: Extract PDF content
      operationId: extractPdf
      description: Extract structured information from PDF files using Gemini.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractPdfRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  files:
                    - https://example.com/report.pdf
                  prompt: "Summarize the key findings and financial metrics."
                  jsonMode: true
      responses:
        '200':
          description: PDF extraction returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractPdfResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/extract-image:
    post:
      tags:
        - Documents
      summary: Extract text from image
      operationId: extractImage
      description: Perform OCR on images to extract text and metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractImageRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  images:
                    - https://example.com/receipt.jpg
                    - https://example.com/menu.png
                  prompt: "Summarize the totals and highlight any discounts."
                  jsonMode: true
      responses:
        '200':
          description: OCR results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractImageResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/extract-video:
    post:
      tags:
        - Documents
      summary: Extract insights from video
      operationId: extractVideo
      description: Extract transcripts, frames, and metadata from video files or URLs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractVideoRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  video: https://example.com/demo.mp4
                  prompt: "Summarize the main takeaways and capture speaker quotes."
                  jsonMode: true
      responses:
        '200':
          description: Video extraction results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractVideoResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/extract-audio:
    post:
      tags:
        - Documents
      summary: Extract audio metadata
      operationId: extractAudio
      description: Extract transcripts and metadata from audio files or URLs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractAudioRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  audio: https://example.com/podcast.mp3
                  prompt: "Provide a summary and list the key action items discussed."
                  jsonMode: false
      responses:
        '200':
          description: Audio extraction results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractAudioResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/doc-to-text:
    post:
      tags:
        - Documents
      summary: Convert document to text
      operationId: docToText
      description: Convert documents such as PDFs, PowerPoints, or Word files into plain text.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocToTextRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  file: https://example.com/report.pdf
                  pages: "1-3,5"
      responses:
        '200':
          description: Plain text representation returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocToTextResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/convert-to-pdf:
    post:
      tags:
        - Documents
      summary: Convert to PDF
      operationId: convertToPdf
      description: Convert URLs or uploads into PDF documents using DumplingAI's conversion pipeline.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertToPdfRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  file: https://example.com/brochure.html
      responses:
        '200':
          description: PDF conversion job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertToPdfResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/merge-pdfs:
    post:
      tags:
        - Documents
      summary: Merge PDFs
      operationId: mergePdfs
      description: Merge multiple PDFs into a single document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergePdfsRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  files:
                    - https://example.com/cover.pdf
                    - https://example.com/appendix.pdf
                  metadata:
                    Title: 2025 Strategy Overview
      responses:
        '200':
          description: Merged PDF returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergePdfsResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/trim-video:
    post:
      tags:
        - Documents
      summary: Trim video
      operationId: trimVideo
      description: Trim a video to a specific start and end time and return the resulting asset.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrimVideoRequest'
            examples:
              default:
                value:
                  videoUrl: https://example.com/video.mp4
                  startTimestamp: "00:00:05"
                  endTimestamp: "00:00:20"
      responses:
        '200':
          description: Trimmed video returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrimVideoResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/read-pdf-metadata:
    post:
      tags:
        - Documents
      summary: Read PDF metadata
      operationId: readPdfMetadata
      description: Read metadata fields embedded in a PDF document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadPdfMetadataRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  files:
                    - https://example.com/report.pdf
      responses:
        '200':
          description: PDF metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadPdfMetadataResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/write-pdf-metadata:
    post:
      tags:
        - Documents
      summary: Write PDF metadata
      operationId: writePdfMetadata
      description: Update metadata fields embedded in a PDF document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WritePdfMetadataRequest'
            examples:
              default:
                value:
                  inputMethod: url
                  files:
                    - https://example.com/report.pdf
                  metadata:
                    Title: 2025 Strategy Overview
                    Author: DumplingAI
      responses:
        '200':
          description: PDF metadata updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritePdfMetadataResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'