openapi: 3.1.0
info:
  title: Factagora API
  description: >
    Fact-checking infrastructure for AI. 6 purpose-built endpoints to verify
    facts, retrieve evidence, and extract causal reasoning from documents. One
    API key, structured JSON responses, Bearer auth.
  version: 1.0.0
  contact:
    url: https://enterprise.factagora.com/en/api
  license:
    name: Commercial
    url: https://enterprise.factagora.com
servers:
  - url: https://api.factagora.com/api/v1
    description: Production
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        API keys follow the format `fag_...`. Get your free API key at
        https://factagora.ai/settings/api-keys
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        statusCode:
          type: integer
      example:
        error: Unauthorized
        message: Missing Bearer token
        statusCode: 401
paths:
  /fact-search:
    get:
      summary: Fact Search
      description: >
        Search recent news articles from global news sources including GNews and
        Naver News. Returns article titles, URLs, publication dates, and source
        domains.
      operationId: factSearch
      tags:
        - Intelligence
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: >-
            Search query for news articles. Use focused keywords for best
            results.
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 50
          description: Maximum number of results to return.
        - name: language
          in: query
          schema:
            type: string
          description: 'Filter by source language. Examples: english, korean'
        - name: country
          in: query
          schema:
            type: string
          description: 'Filter by source country code. Examples: US, KR'
        - name: sortBy
          in: query
          schema:
            type: string
            default: relevance
            enum:
              - relevance
              - date
          description: Sort order.
        - name: timespan
          in: query
          schema:
            type: string
          description: 'Time range filter. Examples: 7d, 30d, 3months'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  articles:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        url:
                          type: string
                        domain:
                          type: string
                        publishedAt:
                          type: string
                          format: date-time
                        language:
                          type: string
                        sourceCountry:
                          type: string
                        snippet:
                          type: string
                        imageUrl:
                          type: string
                        source:
                          type: string
                          enum:
                            - gnews
                            - naver
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      executionTimeMs:
                        type: integer
                      source:
                        type: string
                        enum:
                          - gnews
                          - naver
                          - mixed
                      cached:
                        type: boolean
              example:
                query: bitcoin
                articles:
                  - title: Bitcoin surges past $100,000 amid institutional demand
                    url: https://reuters.com/...
                    domain: reuters.com
                    publishedAt: '2026-03-29T10:00:00Z'
                    language: english
                    sourceCountry: US
                    snippet: >-
                      Bitcoin hit a new all-time high as institutional
                      investors...
                    source: gnews
                meta:
                  total: 1
                  executionTimeMs: 312
                  source: gnews
                  cached: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /fact-checker:
    post:
      summary: Fact Checker
      description: >
        Verify whether a given claim is TRUE, FALSE, or UNCERTAIN. Returns a
        confidence score and up to 5 cited sources from the Factagora knowledge
        base.
      operationId: factChecker
      tags:
        - Intelligence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - claim
              properties:
                claim:
                  type: string
                  maxLength: 1000
                  description: The claim or statement to verify.
            example:
              claim: OpenAI released GPT-5 in 2025
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  claim:
                    type: string
                  verdict:
                    type: string
                    enum:
                      - true
                      - false
                      - UNCERTAIN
                  confidence:
                    type: number
                    minimum: 0
                    maximum: 1
                  summary:
                    type: string
                  sources:
                    type: array
                    maxItems: 5
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        url:
                          type: string
                        credibility:
                          type: number
                          minimum: 0
                          maximum: 1
                  meta:
                    type: object
                    properties:
                      executionTimeMs:
                        type: integer
              example:
                claim: OpenAI released GPT-5 in 2025
                verdict: false
                confidence: 0.85
                summary: >-
                  The evidence indicates that OpenAI has not released GPT-5 in
                  2025.
                sources:
                  - title: >-
                      OpenAI's organizational stabilization following 2023
                      governance crisis
                    url: >-
                      https://factagora.com/claims/c5558d16-3625-4136-b62b-44b7df600239
                    credibility: 0.7
                meta:
                  executionTimeMs: 4672
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /evidence-finder:
    post:
      summary: Evidence Finder
      description: >
        Search for evidence related to a claim from multiple angles. Returns
        AI-analyzed, credibility-scored sources categorized by type, each with a
        stance indicating whether the source supports, contradicts, or is
        neutral toward the claim.
      operationId: evidenceFinder
      tags:
        - Intelligence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - claim
              properties:
                claim:
                  type: string
                  maxLength: 500
                  description: The claim or topic to find evidence for.
                limit:
                  type: integer
                  default: 5
                  minimum: 1
                  maximum: 20
            example:
              claim: Bitcoin price will exceed 200000 dollars in 2025
              limit: 5
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  claim:
                    type: string
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        summary:
                          type: string
                        source:
                          type: string
                        type:
                          type: string
                          enum:
                            - DATA
                            - EXPERT
                            - NEWS
                            - FACT_CHECK
                        credibility:
                          type: number
                          minimum: 0
                          maximum: 1
                        stance:
                          type: string
                          enum:
                            - SUPPORTS
                            - CONTRADICTS
                            - NEUTRAL
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      executionTimeMs:
                        type: integer
              example:
                claim: Bitcoin price will exceed 200000 dollars in 2025
                results:
                  - summary: >-
                      Multiple expert agents predict Bitcoin will reach $200,000
                      by 2025.
                    source: >-
                      https://factagora.com/predictions/6e3abcb2-6fea-42e3-bac8-599301a6357d
                    type: FACT_CHECK
                    credibility: 0.9
                    stance: SUPPORTS
                meta:
                  total: 1
                  executionTimeMs: 12716
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /deep-research:
    post:
      summary: Deep Research
      description: >
        Perform in-depth research on any topic. Aggregates verified claims,
        predictions, live news, and time-series event data, then generates a
        structured report with sections and cited sources.
      operationId: deepResearch
      tags:
        - Intelligence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  maxLength: 1000
                  description: The topic or question to research.
            example:
              query: Bitcoin price history in 2024
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  summary:
                    type: string
                  sections:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        content:
                          type: string
                  timeseries:
                    nullable: true
                    type: object
                    properties:
                      title:
                        type: string
                      dataPoints:
                        type: array
                        items:
                          type: object
                          properties:
                            timestamp:
                              type: string
                            label:
                              type: string
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        url:
                          type: string
                  meta:
                    type: object
                    properties:
                      executionTimeMs:
                        type: integer
              example:
                query: Bitcoin price history in 2024
                summary: Bitcoin experienced significant price movements in 2024.
                sections:
                  - title: Background
                    content: >-
                      Bitcoin has been subject to cyclical price patterns tied
                      to halving events.
                  - title: Current State
                    content: In January 2024, the SEC approved spot Bitcoin ETFs.
                timeseries:
                  title: Bitcoin key events in 2024
                  dataPoints:
                    - timestamp: 2024-01
                      label: SEC approves spot Bitcoin ETFs
                    - timestamp: 2024-03
                      label: Bitcoin reaches all-time high above $73,000
                sources:
                  - title: Will Bitcoin exceed $100,000 by end of 2024?
                    url: >-
                      https://factagora.com/predictions/6e3abcb2-6fea-42e3-bac8-599301a6357d
                meta:
                  executionTimeMs: 8340
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /timeseries:
    post:
      summary: Timeseries (URL)
      description: >
        Extract time-series data from a URL. Returns timestamped events or facts
        organized chronologically.
      operationId: timeseries
      tags:
        - Intelligence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  description: >-
                    URL of the page or document to extract time-series data
                    from.
            example:
              url: https://data.worldbank.org/indicator/NY.GDP.MKTP.CD?locations=US
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  dataPoints:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                          description: 'Format: YYYY, YYYY-MM, or YYYY-MM-DD'
                        label:
                          type: string
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      executionTimeMs:
                        type: integer
              example:
                title: AI Regulation Timeline
                dataPoints:
                  - timestamp: 2023-03
                    label: Italy temporarily bans ChatGPT over privacy concerns
                  - timestamp: 2024-03
                    label: EU AI Act formally adopted
                meta:
                  total: 2
                  executionTimeMs: 520
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /timeseries/file:
    post:
      summary: Timeseries (File Upload)
      description: |
        Extract time-series data from an uploaded PDF or Markdown file.
      operationId: timeseriesFile
      tags:
        - Intelligence
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: PDF or Markdown file to extract time-series data from.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  dataPoints:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                        label:
                          type: string
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      executionTimeMs:
                        type: integer
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /causality-graph:
    post:
      summary: Causality Graph (URL)
      description: >
        Analyze cause-and-effect relationships from a URL. Returns nodes
        (concepts/events) and directed edges (causal relationships).
      operationId: causalityGraph
      tags:
        - Intelligence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  description: >-
                    URL of the page or document to extract causal relationships
                    from.
            example:
              url: https://example.com/economic-analysis
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        label:
                          type: string
                  edges:
                    type: array
                    items:
                      type: object
                      properties:
                        from:
                          type: string
                        to:
                          type: string
                        label:
                          type: string
                  meta:
                    type: object
                    properties:
                      total_nodes:
                        type: integer
                      total_edges:
                        type: integer
                      executionTimeMs:
                        type: integer
              example:
                nodes:
                  - id: n1
                    label: Rising interest rates
                  - id: n2
                    label: Lower consumer spending
                  - id: n3
                    label: Reduced GDP growth
                edges:
                  - from: n1
                    to: n2
                    label: causes
                  - from: n2
                    to: n3
                    label: leads to
                meta:
                  total_nodes: 3
                  total_edges: 2
                  executionTimeMs: 640
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /causality-graph/file:
    post:
      summary: Causality Graph (File Upload)
      description: >
        Analyze cause-and-effect relationships from an uploaded PDF or Markdown
        file.
      operationId: causalityGraphFile
      tags:
        - Intelligence
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: PDF or Markdown file to extract causal relationships from.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        label:
                          type: string
                  edges:
                    type: array
                    items:
                      type: object
                      properties:
                        from:
                          type: string
                        to:
                          type: string
                        label:
                          type: string
                  meta:
                    type: object
                    properties:
                      total_nodes:
                        type: integer
                      total_edges:
                        type: integer
                      executionTimeMs:
                        type: integer
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'