Semantic search

Run semantic search over your indexed transcriptions using hybrid retrieval — dense embeddings (OpenAI text-embedding-3-large) combined with sparse BM25 vectors fused via Reciprocal Rank Fusion (RRF). Each hit returns the matched text excerpt, precise timestamps, and source media metadata.

Before searching, transcriptions must be indexed via an indexer job

Typical search flow

Complete a transcription job (serviceType: transcription), note the textSourceId (alias transcriptionId) from resultSummary.
Submit an indexer job (serviceType: indexer) with input.textSourceIds (one to 50 txt_… IDs). Unknown or empty transcripts are rejected at create (notFound / validationError) — see Create an indexer job. Wait for status: completed.
Optional: GET /v1/catalog/indexed-transcriptions to list what is in the vector index for the project.
Call POST /v1/catalog/search with your query and project scope.

Requires ai:search on the project API key. Each search consumes one AI search credit (1,000/month on Free). Indexer jobs require job:create and consume one indexing credit per indexed text source (txt_…) (100/month on Free).

Vectors are stored in the project's active Qdrant cluster (platform default or BYO). Configure the cluster in the dashboard or see Vector store. Listed transcripts reflect the live index on that cluster.

Responses use camelCase field names (same as the rest of the public API). The catalog worker returns snake_case internally; the Node API normalizes catalog payloads before they reach clients.

List indexed transcriptions

GET/v1/catalog/indexed-transcriptions

Returns which transcriptions have vectors in the project's hybrid search collection, with chunk counts and optional metadata copied from the indexer job at index time.

When to use

Search inventory — show what is searchable before running queries.
Automation — reconcile index state after bulk indexer jobs or before deleting stale entries.
Does not return chunk text — use search for excerpts or retrieve the transcript for full segments.

Requires permission

ai:search

Large collections may set truncated: true when the scan hits an internal point limit — treat the list as partial and paginate by re-indexing or filtering in your app if needed.

items[] fields:

Field	Type	Description
`transcriptionId`	string	Text source present in the index (txt_…; alias of textSourceId).
`chunkCount`	integer	Number of vector chunks indexed for this transcription.
`latestJobId`	string \| null	Most recent indexer job id that wrote vectors for this transcript.
`displayName`	string \| null	Display name copied from the transcript at index time.
`customerJobRef`	string \| null	Caller reference from indexer userMetadata.customerJobRef.

Query parameters

chunkTypestring, optional: Optional filter. Currently only transcription chunks are indexed.

Returns

collection, total, truncated, pointsScanned, and items[] with transcriptionId, chunkCount, optional latestJobId, displayName, and customerJobRef.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/catalog/indexed-transcriptions" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "collection": "perchat_proj_prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "total": 2,
  "truncated": false,
  "pointsScanned": 16,
  "items": [
    {
      "transcriptionId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
      "chunkCount": 8,
      "latestJobId": "job_02HX2K9V3JEK4WYZN6F0XQ2W8M",
      "displayName": "Q3 earnings call",
      "customerJobRef": "indexer-01HX2K9V3JEK4WYZ"
    },
    {
      "transcriptionId": "txt_02HX2K9V3JEK4WYZN6F0XQ2W8N",
      "chunkCount": 5,
      "latestJobId": "job_03HX2K9V3JEK4WYZN6F0XQ2W8N",
      "displayName": null,
      "customerJobRef": null
    }
  ]
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Remove from search index

DELETE/v1/catalog/indexed-transcriptions/{transcriptionId}

Deletes all vector chunks for one transcription from the project collection. The stored transcript and transcription job are unchanged — only search vectors are removed.

When to use

Opt out of search — remove a transcript from semantic search without deleting the transcript record.
Before re-index — optional cleanup; re-indexing also replaces vectors on success.
Idempotent for missing vectors — returns deletedCount: 0 when nothing was indexed.

Requires permission

ai:search

Parameters

transcriptionIdstring: Transcription to remove from the index (txt_…).

Query parameters

chunkTypestring, optional: Optional chunk-type filter (same as list).

Returns

transcriptionId, collection, and deletedCount (number of points removed).

curl -X DELETE "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/catalog/indexed-transcriptions/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "transcriptionId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "collection": "perchat_proj_prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "deletedCount": 8
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Search transcriptions

POST/v1/catalog/search

Hybrid semantic search over all indexed transcription chunks in the project. Combines dense vector similarity (OpenAI embeddings) with sparse BM25 keyword matching via RRF fusion. Returns ranked text excerpts with timestamps and source metadata.

When to use

Natural-language queries — find moments across many transcriptions without knowing exact wording (explain cache invalidation, mention of revenue target).
Deep-link to the moment — each result includes start / end seconds and startTimestamp / endTimestamp for video seek.
Optional reranking — set rerank: true when the catalog service is configured with a reranker (RERANKER=bge or flashrank or cohere) for higher-precision ordering at the cost of extra latency.

Requires permission

ai:search

Prefer groups[] for UI that shows one card per transcript with multiple moments underneath. Flat results[] mirrors the same hits in score order. The Node API adds groups[] and groupCount without removing results[].

Groups are ordered by topScore (best hit in that transcript). Hits inside a group are ordered by score descending. Group key is transcriptionId + displayName.

Resolve the parent transcription job with GET /v1/catalog/indexed-transcriptions → latestJobId, or GET /v1/transcriptions/{transcriptionId} → jobId. Use transcriptionId plus start for media seek — not the job id in search payloads.

Chunk vectors store only per-hit metadata (display name, source URL, segment window, etc.). Transcription-level fields such as duration, engine, or full segment lists are not duplicated on every vector — fetch the transcript API when you need them.

results[] and groups[].hits[] share the same hit fields:

Field	Type	Description
`text`	string	Matched chunk text excerpt.
`score`	number	Relevance score from RRF fusion (or reranker when rerank: true).
`transcriptionId`	string \| null	Source transcription identifier.
`projectId`	string \| null	Project the chunk belongs to.
`workspaceId`	string \| null	Owning workspace.
`displayName`	string \| null	Transcript display name at index time.
`chunkType`	string \| null	Chunk type (currently transcription).
`chunkIndex`	integer \| null	Zero-based chunk position within the transcription.
`startSegmentId`	string \| null	First transcription segment id in this chunk.
`endSegmentId`	string \| null	Last transcription segment id in this chunk.
`start`	number \| null	Chunk start time in seconds.
`end`	number \| null	Chunk end time in seconds.
`startTimestamp`	string \| null	Human-readable start time (M:SS or H:MM:SS).
`endTimestamp`	string \| null	Human-readable end time.
`sourceUrl`	string \| null	Media URL stamped at index time (when available).
`language`	string \| null	Language stamped at index time (when available).
`customerJobRef`	string \| null	Indexer job reference from userMetadata.customerJobRef.

Each group also includes transcriptionId, displayName, and topScore. groups[].hits[] includes the core seek fields above (text, score, segment window, times, chunkIndex, customerJobRef). Flat results[] includes every column in the table (for example chunkType, startTimestamp, sourceUrl, projectId).

With reranking and chunk type filter:

{
  "query": "discussion about architecture decisions",
  "limit": 5,
  "rerank": true,
  "chunkType": "transcription"
}

The reranked field in the response is true only when rerank: true was sent and a reranker is actually configured on the server. It is safe to always send rerank: true — the server degrades gracefully to RRF ordering when no reranker is available.

Parameters

querystring: Free-text search query. 1–2000 characters.
limitinteger, optional: Max results to return. 1–50, default 10.
rerankboolean, optional: Apply a second-stage reranker for higher-precision ordering. Only has an effect when the catalog service is configured with RERANKER=bge or RERANKER=flashrank or RERANKER=cohere. Default false.
chunkTypestring, optional: Optional filter on chunk type. Currently only transcription is produced by the indexer. Omit to search all types.
projectIdstring, optional: Project scope override. Defaults to the project bound to your API key via X-Project-Id header. Ignored when the key already scopes to a project.

Returns

Returns query, collection, total, reranked, flat results[], plus groupCount and groups[] (hits grouped per transcript). All fields are camelCase in the public API.

curl -X POST "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/catalog/search" \
  -H "Authorization: Bearer sk_prj_..." \
  -H "Content-Type: application/json" \
-d '{
  "query": "what did the speaker say about performance metrics",
  "limit": 10,
  "rerank": false
}'

{
  "data": {
  "query": "what did the speaker say about performance metrics",
  "collection": "perchat_proj_prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "total": 3,
  "groupCount": 2,
  "reranked": false,
  "groups": [
    {
      "transcriptionId": "txt_02HX2K9V3JEK4WYZN6F0XQ2W8N",
      "displayName": "Product roadmap review",
      "topScore": 0.041,
      "hits": [
        {
          "text": "Our p99 latency improved 40% after the cache rollout…",
          "score": 0.041,
          "transcriptionId": "txt_02HX2K9V3JEK4WYZN6F0XQ2W8N",
          "displayName": "Product roadmap review",
          "start": 312.4,
          "end": 341.8,
          "startSegmentId": "seg_42",
          "endSegmentId": "seg_51",
          "customerJobRef": "indexer-01HX2K9V3JEK4WYZ",
          "chunkIndex": 3
        }
      ]
    },
    {
      "transcriptionId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
      "displayName": "Q3 earnings call",
      "topScore": 0.032,
      "hits": [
        {
          "text": "We track requests per second normalised by CPU usage.",
          "score": 0.032,
          "textSourceId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
          "displayName": "Q3 earnings call",
          "start": 120.0,
          "end": 145.2,
          "startSegmentId": "seg_18",
          "endSegmentId": "seg_22",
          "customerJobRef": null,
          "chunkIndex": 1
        },
        {
          "text": "Earlier we discussed margin expansion in EMEA.",
          "score": 0.021,
          "textSourceId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
          "displayName": "Q3 earnings call",
          "start": 88.0,
          "end": 102.5,
          "startSegmentId": "seg_12",
          "endSegmentId": "seg_15",
          "customerJobRef": null,
          "chunkIndex": 0
        }
      ]
    }
  ],
  "results": [
    {
      "text": "Our p99 latency improved 40% after the cache rollout…",
      "score": 0.041,
      "transcriptionId": "txt_02HX2K9V3JEK4WYZN6F0XQ2W8N",
      "displayName": "Product roadmap review",
      "chunkType": "transcription",
      "chunkIndex": 3,
      "startSegmentId": "seg_42",
      "endSegmentId": "seg_51",
      "start": 312.4,
      "end": 341.8,
      "startTimestamp": "5:12",
      "endTimestamp": "5:41",
      "customerJobRef": "indexer-01HX2K9V3JEK4WYZ",
      "sourceUrl": "https://cdn.example.com/roadmap.mp4",
      "language": "en"
    },
    {
      "text": "We track requests per second normalised by CPU usage.",
      "score": 0.032,
      "transcriptionId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
      "displayName": "Q3 earnings call",
      "chunkType": "transcription",
      "chunkIndex": 1,
      "startSegmentId": "seg_18",
      "endSegmentId": "seg_22",
      "start": 120.0,
      "end": 145.2,
      "startTimestamp": "2:00",
      "endTimestamp": "2:25",
      "customerJobRef": null,
      "sourceUrl": "https://cdn.example.com/earnings-q3.mp4",
      "language": "en"
    },
    {
      "text": "Earlier we discussed margin expansion in EMEA.",
      "score": 0.021,
      "transcriptionId": "txt_01HX2K9V3JEK4WYZN6F0XQ2W8M",
      "displayName": "Q3 earnings call",
      "chunkType": "transcription",
      "chunkIndex": 0,
      "startSegmentId": "seg_12",
      "endSegmentId": "seg_15",
      "start": 88.0,
      "end": 102.5,
      "startTimestamp": "1:28",
      "endTimestamp": "1:42",
      "customerJobRef": null,
      "sourceUrl": "https://cdn.example.com/earnings-q3.mp4",
      "language": "en"
    }
  ]
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}