Search - Gildea API

curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/search?q=AI%20chip%20supply%20chain&limit=5"

{
  "data": [
    {
      "unit": {
        "unit_id": "0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9",
        "unit_type": "analysis_claim",
        "text": "NVIDIA increased H200 shipments by 40% quarter-over-quarter as supply constraints eased.",
        "parent_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7"
      },
      "verification": {
        "final_verdict": "pass",
        "verification_path": "auto_pass",
        "was_human_reviewed": false,
        "scoring_mode": "nli",
        "primary_score": 0.8912
      },
      "citation": {
        "signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
        "signal_title": "NVIDIA Q4 2025 Supply Chain Analysis",
        "url": "https://example.com/nvidia-supply-chain",
        "author": "Jane Smith",
        "registrable_domain": "example.com",
        "published_at": "2026-03-15T00:00:00+00:00"
      },
      "relevance_score": 0.031746
    }
  ],
  "query": "AI chip supply chain"
}

GET

curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/search?q=AI%20chip%20supply%20chain&limit=5"

{
  "data": [
    {
      "unit": {
        "unit_id": "0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9",
        "unit_type": "analysis_claim",
        "text": "NVIDIA increased H200 shipments by 40% quarter-over-quarter as supply constraints eased.",
        "parent_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7"
      },
      "verification": {
        "final_verdict": "pass",
        "verification_path": "auto_pass",
        "was_human_reviewed": false,
        "scoring_mode": "nli",
        "primary_score": 0.8912
      },
      "citation": {
        "signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
        "signal_title": "NVIDIA Q4 2025 Supply Chain Analysis",
        "url": "https://example.com/nvidia-supply-chain",
        "author": "Jane Smith",
        "registrable_domain": "example.com",
        "published_at": "2026-03-15T00:00:00+00:00"
      },
      "relevance_score": 0.031746
    }
  ],
  "query": "AI chip supply chain"
}

For how retrieval works under the hood (dense + sparse + RRF + cross-encoder rerank), see How search works.

string

Free-text search query. Required unless similar_to is provided.

similar_to

string

A 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. Exactly one of q or similar_to must be provided.

unit_type

string

Filter by text unit type: thesis_sentence, argument_sentence, summary_sentence, analysis_claim, or event_claim.

entity

string

Entity public ID (e.g. gld:/a1b2c3d4e5f6). Returns only units whose text literally contains a known surface form of the entity — high-precision entity attribution. Find public IDs via GET /v1/entities.

theme

string

Theme label (one of 12; see Themes). Returns units from articles tagged with that theme.

published_after

string

ISO 8601 date. Only return results from articles published after this date.

published_before

string

ISO 8601 date. Only return results from articles published before this date.

recency_boost

number

default:"0.0"

Recency weight from 0 to 1. 0 ignores publication date; 1 maximally favors newer signals. Soft preference — does not exclude older results.

diversity_cap

integer

default:"2"

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.

verification_detail

string

Set to full for complete verification metadata on each result. Default returns a compact form.

limit

integer

default:"10"

Max results to return (1–100). Raise when doing strategic / deep retrieval; the retrieval pool scales accordingly.

data

array

Ranked search results.

Show Search result

unit

object

The matched text unit.

Show Unit fields

unit_id

string

Text unit identifier.

unit_type

string

thesis_sentence, argument_sentence, summary_sentence, analysis_claim, or event_claim.

text

string

The verified text content.

parent_id

string

Parent ID. Article ID for analysis claims (claims are served at the article level, not nested under arguments). Argument ID for argument sentences. Thesis ID for thesis sentences. Summary ID for summary sentences and event claims. Use with GET /v1/signals/{id} to retrieve the full source decomposition.

verification

object

Verification details (compact by default, full with verification_detail=full).

citation

object

Source signal attribution.

Show Citation fields

signal_id

string

Parent signal identifier.

signal_title

string

Signal headline.

url

string

Original source URL.

author

string

Author name if available.

registrable_domain

string

Source domain.

published_at

string

Publication timestamp (ISO 8601).

relevance_score

number

Combined relevance score (higher = more relevant).

evidence

object

Evidence snippet metadata, if available.

diagnostics

object

Retrieval stage ranks for observability. Optional — only present when diagnostic signals are available.

Show Diagnostic fields

rrf_rank

integer

Rank after dense + sparse RRF fusion, before cross-encoder rerank.

rerank_rank

integer

Final rank after cross-encoder rerank. Present when rerank ran successfully.

rerank_score

number

Cross-encoder relevance score (0–1, higher is more relevant). Present when rerank ran successfully.

entity_filter_dropped

integer

Number of candidates removed by the unit-level entity post-filter. Present only when entity filter was applied. A high number relative to limit suggests the requested entity is sparsely surface-formed in the corpus.

query

string

The search query (when using q).

similar_to

string

The source unit ID (when using similar_to).

curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/search?q=AI%20chip%20supply%20chain&limit=5"

{
  "data": [
    {
      "unit": {
        "unit_id": "0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9",
        "unit_type": "analysis_claim",
        "text": "NVIDIA increased H200 shipments by 40% quarter-over-quarter as supply constraints eased.",
        "parent_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7"
      },
      "verification": {
        "final_verdict": "pass",
        "verification_path": "auto_pass",
        "was_human_reviewed": false,
        "scoring_mode": "nli",
        "primary_score": 0.8912
      },
      "citation": {
        "signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
        "signal_title": "NVIDIA Q4 2025 Supply Chain Analysis",
        "url": "https://example.com/nvidia-supply-chain",
        "author": "Jane Smith",
        "registrable_domain": "example.com",
        "published_at": "2026-03-15T00:00:00+00:00"
      },
      "relevance_score": 0.031746
    }
  ],
  "query": "AI chip supply chain"
}

Authorizations

X-API-Key

string

header

required

API key for authentication. Include in every request as X-API-Key: gld_your_key_here.

Query Parameters

string | null

Search query text. Required unless similar_to is provided.

Minimum string length: 1

similar_to

string | null

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.

unit_type

string | null

Filter by text unit type: 'thesis_sentence', 'argument_sentence', 'summary_sentence', 'analysis_claim', 'event_claim'.

entity

string | null

Entity public ID (e.g. gld:/a1b2c3d4e5f6). Returns only units whose text literally contains a known surface form of the entity. Find public IDs via GET /v1/entities.

theme

string | null

Filter results to a specific theme.

published_after

string | null

ISO 8601 date — only results published after this date.

published_before

string | null

ISO 8601 date — only results published before this date.

recency_boost

number

default:0

Recency weight (0=none, 1=max). Boosts newer signals.

Required range: 0 <= x <= 1

verification_detail

string | null

Set to 'full' for complete verification metadata.

limit

integer

default:10

Max results to return (1–100). Defaults to 10; raise when doing strategic/deep retrieval.

Required range: 1 <= x <= 100

diversity_cap

integer

default:2

Max units per source article in the results. Default 2 (forces source diversity). Set higher (e.g. 100) when you want comprehensive coverage from a definitive article.

Required range: 1 <= x <= 100

Response

Successful Response

data

SearchHit · object[]

required

Ranked search results.

Show child attributes

query

string | null

The search query (when using q).

Example:

"AI chip supply chain"

similar_to

string | null

The source unit ID (when using similar_to).

Get Theme

Embed Text

Documentation Index

Authorizations

Query Parameters

Response