Audioscrape Search API

openapi: 3.2.0
info:
  title: Audioscrape Com Search API
  version: '2026-05-16'
  contact:
    name: Audioscrape
    url: https://www.audioscrape.com
    email: lukas@audioscrape.com
  license:
    name: ''
  description: 'Operations tagged Search across 2 of this provider''s published API definitions: audioscrape-com-openapi.json, audioscrape-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.audioscrape.com
  description: Production
tags:
- name: Search
  description: Hybrid, text, and semantic search across all audio content, regardless of source type
paths:
  /api/search:
    post:
      tags:
      - Search
      summary: Hybrid, text, or semantic search
      description: 'Searches the audio corpus and returns segment-level results with timestamps, highlights, and the parent episode + podcast.

        The default `search_type` of `hybrid` combines keyword scoring with semantic vector matching; use `text` for boolean queries

        and quoted phrases, `semantic` for natural-language questions. Filter by podcast, speaker, or publish-date range via the

        `filters` object.'
      operationId: search_api_v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request (e.g. empty query)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '402':
          description: No active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: 'Semantic search requires a Pro/Enterprise plan (`code: FEATURE_NOT_AVAILABLE`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '429':
          description: 'Monthly text-search or semantic-search quota exhausted (`code: SEARCH_LIMIT_EXCEEDED` or `SEMANTIC_SEARCH_LIMIT_EXCEEDED`, body includes `usage: { current, limit }`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    servers:
    - url: https://www.audioscrape.com
      description: Production
components:
  schemas:
    ResultUrls:
      type: object
      required:
      - segment
      - episode
      properties:
        episode:
          type: string
        segment:
          type: string
    SortOptions:
      type: object
      properties:
        field:
          type:
          - string
          - 'null'
          description: '`"relevance"` or `"date"`.'
        order:
          type:
          - string
          - 'null'
          description: '`"asc"` or `"desc"`.'
    ApiErrorBody:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine-readable error code (UPPERCASE_SNAKE_CASE).
          example: SEARCH_LIMIT_EXCEEDED
        message:
          type: string
          description: Human-readable error message.
          example: Monthly search limit reached
        usage:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/UsageInfo'
            description: Present on rate-limit / quota errors. Omitted otherwise.
    SearchRequest:
      type: object
      description: API v1 Search Request - simplified for external API users
      required:
      - query
      properties:
        filters:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SearchFilters'
        limit:
          type: integer
          description: Results to return, 1–100; outside that range is a 400. Page with `offset`.
          default: 20
          example: 20
          maximum: 100
          minimum: 1
        offset:
          type: integer
          description: Result offset for pagination.
          default: 0
          example: 0
          minimum: 0
        query:
          type: string
          description: Natural-language or keyword query.
          example: supply chain disruption semiconductor
        search_type:
          type:
          - string
          - 'null'
          description: 'One of `"text"`, `"semantic"`, or `"hybrid"`. Defaults to auto-detect:

            queries with boolean operators / quoted phrases use `"text"`, others `"hybrid"`.'
          example: hybrid
        sort:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SortOptions'
    SearchFilters:
      type: object
      properties:
        content_types:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Restrict to content types (`phone_call`, `meeting`, `interview`,

            `government_meeting`, `podcast_episode`, ...) — the typed audio axis.'
        date_from:
          type:
          - string
          - 'null'
          description: 'Filter by publish date (ISO 8601 format: "2024-01-01" or "2024-01-01T00:00:00Z").'
        date_to:
          type:
          - string
          - 'null'
          description: 'Filter by publish date (ISO 8601 format: "2024-12-31" or "2024-12-31T23:59:59Z").'
        podcast_ids:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Restrict to specific podcast IDs.
        speakers:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Restrict to specific speakers (exact match on speaker name).
        visibility:
          type:
          - string
          - 'null'
          description: 'Tenancy scope: `all` (default: the public corpus plus your own data) |

            `public` (the public corpus only) | `workspace` (your own data only;

            with an API key, the key''s workspace). It only narrows what you may

            read, never widens it; any other value is a 400. `workspace` also

            relaxes the short-segment floor and scopes semantic retrieval.'
    UsageInfo:
      type: object
      required:
      - current
      - limit
      properties:
        current:
          type: integer
          format: int64
          description: Current usage value (e.g., calls consumed this period).
        limit:
          type: integer
          format: int64
          description: Configured limit for the period.
    Podcast:
      type: object
      required:
      - id
      - title
      - slug
      - image_url
      properties:
        id:
          type: string
        image_url:
          type: string
        slug:
          type: string
        title:
          type: string
    SearchResponse:
      type: object
      description: API v1 Search Response - clean, stable structure
      required:
      - meta
      - results
      properties:
        meta:
          $ref: '#/components/schemas/SearchMeta'
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
    Timestamp:
      type: object
      required:
      - start
      - end
      properties:
        end:
          type: number
          format: double
        start:
          type: number
          format: double
    SearchMeta:
      type: object
      required:
      - query
      - total
      - limit
      - offset
      - has_more
      - took_ms
      properties:
        has_more:
          type: boolean
        limit:
          type: integer
          minimum: 0
        offset:
          type: integer
          minimum: 0
        query:
          type: string
        sort_scope:
          type:
          - string
          - 'null'
          description: 'GH#423: present when sort.field=date was honored. "global" = the whole

            match set was date-ordered server-side (text search); "retrieved_window"

            = the similarity-retrieved window was date-ordered (semantic/hybrid,

            where a global date order isn''t defined for kNN retrieval).'
        took_ms:
          type: integer
          format: int64
          minimum: 0
        total:
          type: integer
          format: int64
          minimum: 0
    Episode:
      type: object
      required:
      - id
      - title
      - slug
      - publish_date
      properties:
        id:
          type: string
        publish_date:
          type: string
        slug:
          type: string
        title:
          type: string
    SearchResult:
      type: object
      required:
      - segment_id
      - score
      - text
      - timestamp
      - episode
      - podcast
      - urls
      properties:
        episode:
          $ref: '#/components/schemas/Episode'
        highlighted_text:
          type:
          - string
          - 'null'
        podcast:
          $ref: '#/components/schemas/Podcast'
        score:
          type: number
          format: double
        segment_id:
          type: string
        speaker:
          type:
          - string
          - 'null'
        text:
          type: string
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        urls:
          $ref: '#/components/schemas/ResultUrls'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key, format `sk_<base64(32 random bytes)>`
      description: 'Workspace-scoped API key. Pass as `Authorization: Bearer <key>`. The `?api_key=<key>` query parameter is deprecated: a key in a URL ends up in browser history, proxy logs and Referer headers.'
x-refined-from:
- audioscrape-com-openapi.json
- audioscrape-com-openapi.json