> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gildea.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> Search Gildea's verified text units. Two modes, text query (`q`) or similarity to a known unit (`similar_to`).
For how retrieval works under the hood (dense + sparse + RRF + cross-encoder rerank), see [How search works](/concepts/search).
Free-text search query. Required unless `similar_to` is provided.
A text unit ID (e.g. a `unit.id` from a `q` search; the two chain naturally). Returns the units most similar in meaning, useful for cross-source corroboration and "find more like this." Required unless `q` is provided (exactly one of `q` / `similar_to`).
Similarity is *topical*, not *agreement*: results are ranked by `relevance_score` and decay from genuine corroboration into adjacent topics, and can even include a contradicting unit. To use it for corroboration, keep the high-scoring hits, check `citation.domain` for source independence, and read `unit.text` to confirm they actually say the same thing. It's a similarity signal, not a consensus verdict.
Filter by unit role: `thesis` / `synopsis` (the central statement of an analysis / event), `argument` (a supporting analysis sentence), or `claim` (an atomic fact).
Entity public ID (e.g. `gld:/a1b2c3d4e5f6`) or exact display name. Returns only units whose text literally contains a known surface form of the entity, for high-precision entity attribution. Pass the public ID (from any `entity_id` field, or via [`GET /v1/entities`](/api-reference/entities/list)) for guaranteed precision; a name resolves to its family-level canonical entity. An unknown entity returns `404` (not an empty list).
Theme label (one of 12; see [Themes](/concepts/themes)). Returns units from articles tagged with that theme. An unknown label returns `404`, not an empty list.
Filter by `content_type` (source kind): `analysis` (expert interpretation, a source's argued position) or `event` (a factual report of what happened). This is the opinion-vs-fact axis, orthogonal to `role`: because `role=claim` returns claims from both kinds, pair `content_type=analysis` with `role=claim` for verified claims from expert analysis only.
ISO 8601 date. Only return results from articles published after this date.
ISO 8601 date. Only return results from articles published before this date.
Recency weight from 0 to 1. `0` ignores publication date; `1` maximally favors newer signals. Soft preference; does not exclude older results.
Maximum units per source article in the returned set (1-100). Default 2 enforces source diversity; raise (e.g. 20) when a single in-depth article should be allowed to contribute more units.
Max results to return (1-100). Raise when doing strategic / deep retrieval; the retrieval pool scales accordingly.
Ranked search results.
The matched verified unit, the same object shape returned by signal detail.
Unit identifier (stable; the same unit returns the same `id` from signal detail).
`thesis` · `synopsis` · `argument` · `claim`. Use `GET /v1/signals/{citation.signal_id}` for the unit in its full context.
The verified text content.
Public IDs of entities named in this unit.
Present only when human-reviewed: `{ "human_reviewed": true }`. Omitted otherwise; every returned unit already passed verification, and the baseline trust signal is the cited evidence, not this flag.
Verbatim evidence `snippets` (each with `text` + `truncated`). Each snippet is a short (\~100-character) locator into the source, not the full passage: proof the unit is grounded, and the span to find if you re-verify. Follow `citation.url` for the full source.
Source signal attribution.
Parent signal identifier.
Signal headline.
Original source URL.
Source domain.
Publication timestamp (ISO 8601).
Per-result relevance score (higher = more relevant). Results are ranked by it with no fixed floor, so let the score decide how many to use rather than assuming every result up to `limit` is equally relevant.
The search query (when using `q`).
The source unit ID (when using `similar_to`).
```bash cURL theme={null}
curl -H "X-API-Key: gld_your_key" \
"https://api.gildea.ai/v1/search?q=AI%20chip%20supply%20chain&limit=5"
```
```python Python theme={null}
import requests
resp = requests.get(
"https://api.gildea.ai/v1/search",
headers={"X-API-Key": "gld_your_key"},
params={"q": "AI chip supply chain", "limit": 5},
)
results = resp.json()
```
```javascript JavaScript theme={null}
const resp = await fetch(
"https://api.gildea.ai/v1/search?q=AI+chip+supply+chain&limit=5",
{ headers: { "X-API-Key": "gld_your_key" } }
);
const results = await resp.json();
```
```bash "Similar to" (cURL) theme={null}
curl -H "X-API-Key: gld_your_key" \
"https://api.gildea.ai/v1/search?similar_to=0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9&limit=5"
```
```json 200 theme={null}
{
"results": [
{
"unit": {
"id": "0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9",
"role": "claim",
"text": "NVIDIA increased H200 shipments by 40% quarter-over-quarter as supply constraints eased.",
"evidence": {
"snippets": [
{ "text": "NVIDIA shipped over 400,000 H200 units in Q4, a 40% increase from the prior quarter…", "truncated": true }
]
}
},
"citation": {
"signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"title": "NVIDIA Q4 2025 Supply Chain Analysis",
"url": "https://reuters.com/nvidia-supply-chain",
"domain": "reuters.com",
"published_at": "2026-03-15T00:00:00+00:00"
},
"relevance_score": 0.8235
}
],
"query": "AI chip supply chain"
}
```
## OpenAPI
````yaml GET /v1/search
openapi: 3.1.0
info:
title: Gildea API
description: >-
Market intelligence on the AI economy, built for agents. Gildea ingests
expert sources (podcasts, essays, VC memos, X posts, research papers, news)
and decomposes them into verified, source-cited atomic facts: thesis
sentences, argument sentences, summary sentences, and claims.
**Key capabilities:**
- Verified atomic facts with verbatim source citations
- Entity intelligence with trend analytics across 8 entity types
- Theme taxonomy (6 value-chain segments + 6 market forces)
- Search verified text units by free-text query or by similarity to a known
unit
Only `verdict=pass` data is served. Every claim cites the source evidence it
was extracted from.
version: 0.1.0
servers:
- url: https://api.gildea.ai
description: Production
- url: http://localhost:8000
description: Local development
security:
- ApiKeyAuth: []
tags:
- name: signals
description: >-
Market intelligence signals — articles decomposed into verified text
units.
- name: entities
description: >-
Entity intelligence — companies, people, and products with trend
analytics.
- name: themes
description: Taxonomy themes — value chain segments and market forces with trend stats.
- name: search
description: >-
Search Gildea's verified text units — text queries or similarity to a
known unit.
- name: health
description: Service health and status.
- name: admin
description: Administrative operations (requires admin secret).
paths:
/v1/search:
get:
tags:
- search
summary: Search verified text units
description: >-
Search Gildea's verified text units. Pass `q` for a free-text query, or
`similar_to` with a text unit ID to find units with similar stored
embeddings. Exactly one of `q` or `similar_to` is required. Use `entity`
(public ID like `gld:/a1b2c3d4e5f6`), `theme`, or date filters to scope.
Filter by `entity` for high-precision entity attribution — only units
literally mentioning the entity are returned.
operationId: search_v1_search_get
parameters:
- name: q
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 2000
- type: 'null'
description: >-
Natural-language query — retrieval is semantic, so phrase it as a
question or rich description, not bare keywords. For an
exact-string lookup of a rare term (e.g. a specific model
codename), use the keyword filter `q` on GET /v1/signals instead.
Required unless similar_to is provided.
title: Q
description: >-
Natural-language query — retrieval is semantic, so phrase it as a
question or rich description, not bare keywords. For an exact-string
lookup of a rare term (e.g. a specific model codename), use the
keyword filter `q` on GET /v1/signals instead. Required unless
similar_to is provided.
- name: similar_to
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Text unit ID. Returns units whose stored embeddings are most
similar — useful for cross-source corroboration and 'find more
like this'. Required unless q is provided.
title: Similar To
description: >-
Text unit ID. Returns units whose stored embeddings are most similar
— useful for cross-source corroboration and 'find more like this'.
Required unless q is provided.
- name: role
in: query
required: false
schema:
anyOf:
- enum:
- thesis
- synopsis
- argument
- claim
type: string
- type: 'null'
description: >-
Filter by unit role: 'thesis' / 'synopsis' (the central statement
of an analysis / event), 'argument' (a supporting analysis
sentence), or 'claim' (a hard, citable atomic fact).
title: Role
description: >-
Filter by unit role: 'thesis' / 'synopsis' (the central statement of
an analysis / event), 'argument' (a supporting analysis sentence),
or 'claim' (a hard, citable atomic fact).
- name: entity
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Entity public ID (`gld:/a1b2c3d4e5f6`) or exact display name
(case-insensitive) — family-level and alias-aware (e.g. Sonnet /
Claude 3.5 resolve to Claude). Returns only units whose text
literally contains a known surface form. Pass the public ID (from
any `entity_id` field) for guaranteed precision; a name resolves
to its family-level canonical entity. An unknown entity returns
404 (not an empty list).
title: Entity
description: >-
Entity public ID (`gld:/a1b2c3d4e5f6`) or exact display name
(case-insensitive) — family-level and alias-aware (e.g. Sonnet /
Claude 3.5 resolve to Claude). Returns only units whose text
literally contains a known surface form. Pass the public ID (from
any `entity_id` field) for guaranteed precision; a name resolves to
its family-level canonical entity. An unknown entity returns 404
(not an empty list).
- name: theme
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter results to a specific theme label (see GET /v1/themes). An
unknown label returns 404, not an empty list.
title: Theme
description: >-
Filter results to a specific theme label (see GET /v1/themes). An
unknown label returns 404, not an empty list.
- name: content_type
in: query
required: false
schema:
anyOf:
- type: string
enum:
- analysis
- event
- type: 'null'
description: >-
Filter by source kind: 'analysis' (expert interpretation: a
source's argued position or reasoning) or 'event' (a factual
report of what happened). This is the opinion-vs-fact axis, and it
is orthogonal to `role`: `role=claim` returns claims from both
kinds, so pair it with `content_type` to get, for example,
verified claims from expert analysis only.
title: Content Type
description: >-
Filter by source kind: 'analysis' (expert interpretation: a source's
argued position or reasoning) or 'event' (a factual report of what
happened). This is the opinion-vs-fact axis, and it is orthogonal to
`role`: `role=claim` returns claims from both kinds, so pair it with
`content_type` to get, for example, verified claims from expert
analysis only.
- name: published_after
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 date — only results published after this date.
title: Published After
description: ISO 8601 date — only results published after this date.
- name: published_before
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 date — only results published before this date.
title: Published Before
description: ISO 8601 date — only results published before this date.
- name: window
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Relative time shortcut, e.g. `7d`, `2w`, `14d`, `1m` (d=days,
w=weeks, m=30-day months). Sugar for `published_after = now -
window`. Cannot be combined with `published_after`.
title: Window
description: >-
Relative time shortcut, e.g. `7d`, `2w`, `14d`, `1m` (d=days,
w=weeks, m=30-day months). Sugar for `published_after = now -
window`. Cannot be combined with `published_after`.
- name: recency_boost
in: query
required: false
schema:
type: number
maximum: 1
minimum: 0
description: Recency weight (0=none, 1=max). Boosts newer signals.
default: 0
title: Recency Boost
description: Recency weight (0=none, 1=max). Boosts newer signals.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: >-
Total number of top-ranked results to return (1–100, default 10).
Search is relevance-ranked and not cursor-paginated: it returns
the single best `limit` hits, so raise this for deep/strategic
retrieval rather than paging. (Browse-style cursor pagination
lives on the list endpoints, e.g. GET /v1/signals.)
default: 10
title: Limit
description: >-
Total number of top-ranked results to return (1–100, default 10).
Search is relevance-ranked and not cursor-paginated: it returns the
single best `limit` hits, so raise this for deep/strategic retrieval
rather than paging. (Browse-style cursor pagination lives on the
list endpoints, e.g. GET /v1/signals.)
- name: diversity_cap
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: >-
Max units returned per source article (default 2). This caps how
many hits any single article can contribute, so a query best
answered by one definitive source returns at most this many of its
units — raise it (up to 100) when you want comprehensive coverage
of a single article rather than diversity across sources.
default: 2
title: Diversity Cap
description: >-
Max units returned per source article (default 2). This caps how
many hits any single article can contribute, so a query best
answered by one definitive source returns at most this many of its
units — raise it (up to 100) when you want comprehensive coverage of
a single article rather than diversity across sources.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
type: object
additionalProperties: true
title: Response Search V1 Search Get
'400':
description: Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
SearchResponse:
properties:
results:
items:
$ref: '#/components/schemas/SearchHit'
type: array
title: Results
description: Ranked search results.
query:
anyOf:
- type: string
- type: 'null'
title: Query
description: The search query (when using q).
examples:
- AI chip supply chain
similar_to:
anyOf:
- type: string
- type: 'null'
title: Similar To
description: The source unit ID (when using similar_to).
type: object
required:
- results
title: SearchResponse
ErrorResponse:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
SearchHit:
properties:
unit:
$ref: '#/components/schemas/Unit'
description: >-
The matched verified unit — the same shape returned by GET
/v1/signals/{id} (carries its own `verification` and `evidence`).
citation:
$ref: '#/components/schemas/SearchCitation'
description: Source signal attribution.
relevance_score:
type: number
title: Relevance Score
description: >-
Combined relevance score (RRF for hybrid search, cosine for
similar_to).
type: object
required:
- unit
- citation
- relevance_score
title: SearchHit
ErrorDetail:
properties:
code:
type: string
title: Code
description: Machine-readable error code.
examples:
- not_found
message:
type: string
title: Message
description: Human-readable error description.
examples:
- Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found
status:
type: integer
title: Status
description: HTTP status code.
examples:
- 404
field:
anyOf:
- type: string
- type: 'null'
title: Field
description: 'For validation errors: path to the offending parameter.'
examples:
- body.text
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: Correlation id (also on the X-Request-Id response header).
retry_after:
anyOf:
- type: integer
- type: 'null'
title: Retry After
description: >-
Seconds to wait before retrying (mirrors the Retry-After header).
Present on 429 (rate limited) and 503 (temporarily unavailable).
reset:
anyOf:
- type: integer
- type: 'null'
title: Reset
description: >-
Unix epoch seconds when the exceeded rate-limit window resets.
Present on 429.
type: object
required:
- code
- message
- status
title: ErrorDetail
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
Unit:
properties:
id:
type: string
title: Id
description: Unique text-unit identifier.
role:
type: string
enum:
- thesis
- synopsis
- argument
- claim
title: Role
description: thesis | synopsis (central statement) · argument · claim.
examples:
- claim
text:
type: string
title: Text
description: The verified text content.
argument_id:
anyOf:
- type: string
- type: 'null'
title: Argument Id
description: >-
Present only on role=argument. Group units sharing this label, in
list order, to reconstruct one argument as a paragraph.
examples:
- a1
entities:
items:
type: string
type: array
title: Entities
description: Public IDs of entities named in this unit.
verification:
anyOf:
- $ref: '#/components/schemas/Verification'
- type: 'null'
description: >-
Present only when there's a trust signal to report (currently: human
review). Omitted otherwise — baseline trust is the cited evidence.
evidence:
anyOf:
- $ref: '#/components/schemas/Evidence'
- type: 'null'
description: Verbatim evidence snippets supporting this unit.
type: object
required:
- id
- role
- text
title: Unit
description: >-
One verified atomic text unit — the same shape in signal detail and
search hits.
SearchCitation:
properties:
signal_id:
type: string
title: Signal Id
description: Parent signal identifier.
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Signal headline.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: Original source URL.
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
description: Source domain.
examples:
- reuters.com
published_at:
anyOf:
- type: string
- type: 'null'
title: Published At
description: Publication timestamp (ISO 8601).
type: object
required:
- signal_id
title: SearchCitation
Verification:
properties:
human_reviewed:
anyOf:
- type: boolean
- type: 'null'
title: Human Reviewed
description: >-
Present and `true` only when a human reviewer approved this unit;
omitted otherwise. Baseline trust is the cited evidence, not this
flag.
type: object
title: Verification
Evidence:
properties:
snippets:
items:
$ref: '#/components/schemas/EvidenceSnippet'
type: array
title: Snippets
type: object
title: Evidence
EvidenceSnippet:
properties:
text:
type: string
title: Text
description: Verbatim evidence passage from the source (may be truncated).
truncated:
type: boolean
title: Truncated
description: True if the snippet was shortened for preview.
type: object
required:
- text
- truncated
title: EvidenceSnippet
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key for authentication. Include in every request as `X-API-Key:
gld_your_key_here`.
````