Search - Gildea API

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

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()

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();

curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/search?similar_to=0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9&limit=5"

{
  "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"
}

GET

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

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()

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();

curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/search?similar_to=0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9&limit=5"

{
  "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"
}

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 (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.

role

string

Filter by unit role: thesis / synopsis (the central statement of an analysis / event), argument (a supporting analysis sentence), or claim (an atomic fact).

entity

string

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) for guaranteed precision; a name resolves to its family-level canonical entity. An unknown entity returns 404 (not an empty list).

theme

string

Theme label (one of 12; see Themes). Returns units from articles tagged with that theme. An unknown label returns 404, not an empty list.

content_type

string

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.

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.

limit

integer

default:"10"

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

results

array

Ranked search results.

Show Search result

unit

object

The matched verified unit, the same object shape returned by signal detail.

Show Unit fields

string

Unit identifier (stable; the same unit returns the same id from signal detail).

role

string

thesis · synopsis · argument · claim. Use GET /v1/signals/{citation.signal_id} for the unit in its full context.

text

string

The verified text content.

entities

array

Public IDs of entities named in this unit.

verification

object

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.

evidence

object

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.

citation

object

Source signal attribution.

Show Citation fields

signal_id

string

Parent signal identifier.

title

string

Signal headline.

url

string

Original source URL.

domain

string

Source domain.

published_at

string

Publication timestamp (ISO 8601).

relevance_score

number

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.

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"

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()

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();

curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/search?similar_to=0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9&limit=5"

{
  "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"
}

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

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.

Required string length: 1 - 2000

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.

role

enum<string> | null

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).

Available options:

thesis,

synopsis,

argument,

claim

entity

string | null

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).

theme

string | null

Filter results to a specific theme label (see GET /v1/themes). An unknown label returns 404, not an empty list.

content_type

enum<string> | null

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.

Available options:

analysis,

event

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.

window

string | null

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.

recency_boost

number

default:0

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

Required range: 0 <= x <= 1

limit

integer

default:10

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.)

Required range: 1 <= x <= 100

diversity_cap

integer

default:2

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.

Required range: 1 <= x <= 100

Response

Successful Response

results

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).

Rate Limits