---
title: "Semantic letter search"
method: GET
path: "/v1/fund-letters/semantic"
tags: ["Fund Letters"]
---

# Semantic letter search

`GET /v1/fund-letters/semantic`

## Request

- Base URL: `https://api.turos.app`
- URL: `https://api.turos.app/v1/fund-letters/semantic`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Metered as fund_letter_semantic; paid plans only. Results are a relevance-ranked top-N (hasMore is always false). third_party-distribution letters return snippet-capped chunks (their /document is not distributable). On vector-engine failure the response degrades to lexical hits (score 0), reported via degradedState.

## Query parameters

- `q` string, required
- `top_k` integer
- `manager_id` string
- `fund_id` string
- `ticker` string
- `issuer_cik` string
- `issuer_ticker` string
- `letter_type` 'hedge_fund_letter' | 'registered_fund_letter' | 'corporate_shareholder_letter' | 'quarterly_shareholder_letter'
- `source` 'fund_website' | 'edgar' | 'aggregator'
- `distribution` 'public_record' | 'fund_published' | 'third_party'
- `period` string
- `year` integer
- `quarter` integer
- `published_from` string
- `published_to` string

## Response `200`

Successful response

- FundLetterSemanticHitList
  - `object` 'list', required
  - `data` object[], required
    - `object` 'fund_letter_semantic_hit', required
    - `score` number, required
    - `letter` object, required
      - `id` string, required
      - `managerId` string, nullable, required
      - `managerName` string, nullable, required
      - `fundId` string, nullable, required
      - `letterType` 'hedge_fund_letter' | 'registered_fund_letter' | 'corporate_shareholder_letter' | 'quarterly_shareholder_letter', required
      - `source` 'fund_website' | 'edgar' | 'aggregator', required
      - `distribution` 'public_record' | 'fund_published' | 'third_party', required
      - `title` string, nullable, required
      - `period` string, nullable, required
      - `publishedAt` string, nullable, required
    - `page` integer, required
    - `chunkText` string, required
    - `anchor` object, nullable, required
      - `page` integer, required
      - `charStart` integer, required
      - `charEnd` integer, required
      - `quote` string, required
      - `sourceSha256` string, required
      - `paginationVersion` string, required
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required
  - `responseMode` 'compact' | 'standard' | 'verbose', nullable
  - `include` string[], nullable
  - `requestId` string, required

## Other responses

- `default`: Contract-aware error response

---

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