Search

Search verified text units

curl --request GET \
  --url https://api.gildea.ai/v1/search \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.gildea.ai/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gildea.ai/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gildea.ai/v1/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gildea.ai/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "unit": {
        "id": "0005a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
        "role": "claim",
        "text": "H200 shipments increased significantly in Q4 as supply chain constraints eased.",
        "argument_id": "a1",
        "entities": [
          "gld:/a1b2c3d4e5f6"
        ],
        "verification": {
          "human_reviewed": true
        },
        "evidence_preview": {
          "snippets": [
            {
              "text": "Nvidia said H200 shipments rose sharply in…",
              "truncated": true
            }
          ]
        }
      },
      "citation": {
        "signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
        "title": "NVIDIA H200 Shipments Surge as Supply Eases",
        "url": "https://reuters.com/technology/nvidia-h200-shipments",
        "domain": "reuters.com",
        "published_at": "2026-01-15T10:00:00Z"
      },
      "relevance_score": 0.87
    }
  ],
  "query": "AI chip supply chain",
  "similar_to": "0005a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c"
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

GET

Search verified text units

curl --request GET \
  --url https://api.gildea.ai/v1/search \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.gildea.ai/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gildea.ai/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gildea.ai/v1/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gildea.ai/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "unit": {
        "id": "0005a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
        "role": "claim",
        "text": "H200 shipments increased significantly in Q4 as supply chain constraints eased.",
        "argument_id": "a1",
        "entities": [
          "gld:/a1b2c3d4e5f6"
        ],
        "verification": {
          "human_reviewed": true
        },
        "evidence_preview": {
          "snippets": [
            {
              "text": "Nvidia said H200 shipments rose sharply in…",
              "truncated": true
            }
          ]
        }
      },
      "citation": {
        "signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
        "title": "NVIDIA H200 Shipments Surge as Supply Eases",
        "url": "https://reuters.com/technology/nvidia-h200-shipments",
        "domain": "reuters.com",
        "published_at": "2026-01-15T10:00:00Z"
      },
      "relevance_score": 0.87
    }
  ],
  "query": "AI chip supply chain",
  "similar_to": "0005a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c"
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "field": "body.text",
    "request_id": "9b2e6c1a-4f3d-4e8a-9c7b-2a1d0e5f6a7b",
    "retry_after": 30,
    "reset": 1768500000
  }
}

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

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'. Similarity is topical, not agreement: results decay from genuine corroboration into adjacent topics and can include a contradicting unit. To corroborate, keep the high-scoring hits, check citation.domain for source independence, and read unit.text to confirm they say the same thing. 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).

Example:

"0005a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c"

Get started

Integrations

API

Recipes

Changelog

Authorizations

Query Parameters

Response