---
title: "Hybrid, text, or semantic search"
method: POST
path: "/api/search"
tags: ["Search"]
---

# Hybrid, text, or semantic search

`POST /api/search`

## Request

- Base URL: `https://www.audioscrape.com`
- URL: `https://www.audioscrape.com/api/search`
- Auth: HTTP bearer

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.

## Request body

- SearchRequest: API v1 Search Request - simplified for external API users
  - `filters` SearchFilters
    - `content_types` string[], nullable: Restrict to content types (`phone_call`, `meeting`, `interview`, `government_meeting`, `podcast_episode`, ...) — the typed audio axis.
    - `date_from` string, nullable: Filter by publish date (ISO 8601 format: "2024-01-01" or "2024-01-01T00:00:00Z").
    - `date_to` string, nullable: Filter by publish date (ISO 8601 format: "2024-12-31" or "2024-12-31T23:59:59Z").
    - `podcast_ids` string[], nullable: Restrict to specific podcast IDs.
    - `speakers` string[], nullable: Restrict to specific speakers (exact match on speaker name).
    - `visibility` string, nullable: 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.
  - `limit` integer: Results to return, 1–100; outside that range is a 400. Page with `offset`.
  - `offset` integer: Result offset for pagination.
  - `query` string, required: Natural-language or keyword query.
  - `search_type` string, nullable: One of `"text"`, `"semantic"`, or `"hybrid"`. Defaults to auto-detect: queries with boolean operators / quoted phrases use `"text"`, others `"hybrid"`.
  - `sort` SortOptions
    - `field` string, nullable: `"relevance"` or `"date"`.
    - `order` string, nullable: `"asc"` or `"desc"`.

## Response `200`

Search results

- SearchResponse: API v1 Search Response - clean, stable structure
  - `meta` SearchMeta, required
    - `has_more` boolean, required
    - `limit` integer, required
    - `offset` integer, required
    - `query` string, required
    - `sort_scope` string, nullable: 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` integer, required
    - `total` integer, required
  - `results` SearchResult[], required
    - `episode` Episode, required
      - `id` string, required
      - `publish_date` string, required
      - `slug` string, required
      - `title` string, required
    - `highlighted_text` string, nullable
    - `podcast` Podcast, required
      - `id` string, required
      - `image_url` string, required
      - `slug` string, required
      - `title` string, required
    - `score` number, double, required
    - `segment_id` string, required
    - `speaker` string, nullable
    - `text` string, required
    - `timestamp` Timestamp, required
      - `end` number, double, required
      - `start` number, double, required
    - `urls` ResultUrls, required
      - `episode` string, required
      - `segment` string, required

## Other responses

- `400`: Invalid request (e.g. empty query)
- `401`: Missing or invalid API key
- `402`: No active subscription
- `403`: Semantic search requires a Pro/Enterprise plan (`code: FEATURE_NOT_AVAILABLE`)
- `429`: Monthly text-search or semantic-search quota exhausted (`code: SEARCH_LIMIT_EXCEEDED` or `SEMANTIC_SEARCH_LIMIT_EXCEEDED`, body includes `usage: { current, limit }`)

---

[API](https://skmtc.dev/audioscrape/apis/audioscrape-rest-api.md) · [All operations](https://skmtc.dev/audioscrape/apis/audioscrape-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/audioscrape/apis/audioscrape-rest-api/revisions/29b5788227cf?raw)