> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factagora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Catalog

> Walkthroughs for each of the 6 Factagora Search APIs

This page walks through each of the 6 Search APIs end-to-end, request, response, and how to read the result. For full parameter specs, head to the [API Reference](/api-reference/introduction).

<Info>
  All endpoints use the same auth: `Authorization: Bearer fag_your_api_key`. Replace `fag_your_api_key` with your key from the [Factagora dashboard](https://factagora.com).
</Info>

## 1. Fact Search

**`GET /api/v1/fact-search`** · 1 credit · Real-time semantic news search.

Search news by meaning rather than keywords. Returns articles with publication date, source domain, and relevance score.

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.factagora.com/api/v1/fact-search" \
    -H "Authorization: Bearer fag_your_api_key" \
    --data-urlencode "q=ECB interest rate decision" \
    --data-urlencode "limit=5" \
    --data-urlencode "timespan=7d"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.factagora.com/api/v1/fact-search",
      headers={"Authorization": "Bearer fag_your_api_key"},
      params={"q": "ECB interest rate decision", "limit": 5, "timespan": "7d"},
  )
  data = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    q: "ECB interest rate decision",
    limit: "5",
    timespan: "7d",
  });
  const resp = await fetch(
    `https://api.factagora.com/api/v1/fact-search?${params}`,
    { headers: { Authorization: "Bearer fag_your_api_key" } },
  );
  const data = await resp.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "query": "ECB interest rate decision",
  "results": [
    {
      "title": "ECB raises rates by 25bp, signals pause",
      "url": "https://example.com/ecb-rate-hike",
      "publishedAt": "2024-06-15T08:00:00Z",
      "source": "reuters.com",
      "language": "english"
    }
  ],
  "meta": { "executionTimeMs": 412 }
}
```

<Info>
  **Use `timespan` to keep results fresh.** Combine with `sortBy=date` when you want the absolute latest articles rather than the most relevant ones.
</Info>

## 2. Fact Checker

**`POST /api/v1/fact-checker`** · 2 credits · Claim verification.

Sends a claim, returns a **TRUE / FALSE / UNCERTAIN** verdict with a confidence score and supporting sources from the Factagora knowledge base.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/fact-checker" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"claim": "The ECB raised interest rates in June 2024."}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/fact-checker",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"claim": "The ECB raised interest rates in June 2024."},
  )
  result = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/fact-checker", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      claim: "The ECB raised interest rates in June 2024.",
    }),
  });
  const result = await resp.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "claim": "The ECB raised interest rates in June 2024.",
  "verdict": "TRUE",
  "confidence": 0.92,
  "summary": "Multiple verified sources confirm the ECB raised its deposit rate by 25bp on June 6, 2024.",
  "sources": [
    {
      "title": "ECB June 2024 monetary policy decision",
      "url": "https://factagora.com/claims/abc-123"
    }
  ]
}
```

<Warning>
  **Treat `confidence < 0.5` as `UNCERTAIN`** even when the verdict is `TRUE` or `FALSE`. The verdict reflects the AI's best guess; confidence reflects how strongly the evidence supports it.
</Warning>

## 3. Evidence Hunter

**`POST /api/v1/evidence-finder`** · 2 credits · Evidence expansion and source discovery.

Given a claim, surfaces multi-angle evidence, each result is typed (`DATA`, `EXPERT`, `NEWS`, `FACT_CHECK`), credibility-scored, and tagged with a stance (supports / contradicts / neutral).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/evidence-finder" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"claim": "Carbon pricing reduces industrial emissions.", "limit": 5}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/evidence-finder",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"claim": "Carbon pricing reduces industrial emissions.", "limit": 5},
  )
  data = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/evidence-finder", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      claim: "Carbon pricing reduces industrial emissions.",
      limit: 5,
    }),
  });
  const data = await resp.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "claim": "Carbon pricing reduces industrial emissions.",
  "results": [
    {
      "summary": "OECD study finds a 5–15% reduction in covered-sector emissions following carbon-pricing introduction.",
      "source": "https://oecd.org/...",
      "type": "DATA",
      "credibility": 0.91,
      "stance": "supports"
    },
    {
      "summary": "Industry economist argues short-term emissions decline is offset by carbon leakage.",
      "source": "https://example.com/...",
      "type": "EXPERT",
      "credibility": 0.74,
      "stance": "contradicts"
    }
  ]
}
```

<Info>
  **Use `stance` to balance perspectives.** A claim that returns only `supports`-stance evidence may be under-explored, pull more results or refine the claim to surface counter-evidence.
</Info>

## 4. Deep Research

**`POST /api/v1/deep-research`** · 2 credits · Cross-source research synthesis.

Aggregates verified claims, news, and time-series events on a topic, then generates a structured report with sections and citations.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/deep-research" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"query": "Impact of US tariffs on global semiconductor supply chains"}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/deep-research",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"query": "Impact of US tariffs on global semiconductor supply chains"},
  )
  report = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/deep-research", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "Impact of US tariffs on global semiconductor supply chains",
    }),
  });
  const report = await resp.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "query": "Impact of US tariffs on global semiconductor supply chains",
  "summary": "US tariffs on advanced chips have accelerated supply-chain regionalization, with notable shifts in Taiwan, Korea, and ASEAN fab investments.",
  "sections": [
    { "title": "Background", "content": "..." },
    { "title": "Current State", "content": "..." },
    { "title": "Key Debates", "content": "..." },
    { "title": "Conclusion", "content": "..." }
  ],
  "timeseries": {
    "title": "Major tariff and policy events",
    "dataPoints": [
      { "date": "2022-10-07", "event": "US export controls on advanced chips to China" }
    ]
  },
  "sources": [
    { "title": "...", "url": "..." }
  ]
}
```

<Info>
  **Treat the summary as a draft, not a final answer.** Deep Research synthesizes from multiple sources but does not replace human judgment for high-stakes decisions, always review the cited sources.
</Info>

## 5. Timeseries

**`POST /api/v1/timeseries`** · 3 credits · Time-based information flow.

Extracts a chronological sequence of events from a URL or uploaded document (PDF/Markdown).

<CodeGroup>
  ```bash cURL (URL) theme={null}
  curl -X POST "https://api.factagora.com/api/v1/timeseries" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com/ai-act-history"}'
  ```

  ```bash cURL (file upload) theme={null}
  curl -X POST "https://api.factagora.com/api/v1/timeseries/file" \
    -H "Authorization: Bearer fag_your_api_key" \
    -F "file=@report.pdf"
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/timeseries",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"url": "https://example.com/ai-act-history"},
  )
  data = resp.json()
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "title": "EU AI Act timeline",
  "dataPoints": [
    { "date": "2021-04-21", "event": "European Commission proposes AI Act" },
    { "date": "2023-12-08", "event": "Provisional political agreement reached" },
    { "date": "2024-03-13", "event": "European Parliament adopts the AI Act" }
  ]
}
```

<Info>
  **Use `/timeseries/file` for PDFs and Markdown** that aren't reachable by URL, for example, internal reports or whitepapers stored on your servers.
</Info>

## 6. Causality Graph

**`POST /api/v1/causality-graph`** · 3 credits · Cause-and-effect analysis.

Extracts a directed graph of causes and effects from a URL or document. Nodes are concepts/events; edges are causal relationships.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/causality-graph" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com/economic-analysis"}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/causality-graph",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"url": "https://example.com/economic-analysis"},
  )
  graph = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/causality-graph", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url: "https://example.com/economic-analysis" }),
  });
  const graph = await resp.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "nodes": [
    { "id": "n1", "label": "Rate hike" },
    { "id": "n2", "label": "Mortgage demand drop" },
    { "id": "n3", "label": "Housing price decline" }
  ],
  "edges": [
    { "from": "n1", "to": "n2", "relation": "causes" },
    { "from": "n2", "to": "n3", "relation": "causes" }
  ]
}
```

<Info>
  **Pair with Timeseries for full picture.** Timeseries tells you *when*; Causality Graph tells you *why*, together they reconstruct an event chain end-to-end.
</Info>

## Summary

| API             | Endpoint                | What it does                             | Credits |
| --------------- | ----------------------- | ---------------------------------------- | ------- |
| Fact Search     | `GET /fact-search`      | Real-time semantic news search           | 1       |
| Fact Checker    | `POST /fact-checker`    | Verify a claim with verdict + confidence | 2       |
| Evidence Hunter | `POST /evidence-finder` | Multi-angle credibility-scored evidence  | 2       |
| Deep Research   | `POST /deep-research`   | Cross-source synthesis with sections     | 2       |
| Timeseries      | `POST /timeseries`      | Chronological event extraction           | 3       |
| Causality Graph | `POST /causality-graph` | Cause-and-effect graph                   | 3       |