{
  "openapi": "3.0.3",
  "info": {
    "title": "DeepInquiry Verified Facts API",
    "version": "1.0.0",
    "description": "DeepInquiry publishes short factual claims that have been checked for how many separate source groups support them. Before sources are counted, they are grouped by website, and by parent company for the websites we have mapped; Wikipedia, its mirrors and aggregators are set aside whenever a source of another kind exists. Every fact comes back with its sources, a verification tier (gold / silver / bronze), a score (0.0-1.0, field name independence_score, a historical name), any removed-source codes, and source notes.\n\nMethodology: https://www.deepinquiry.ai/methodology\nResponse fields: https://www.deepinquiry.ai/docs/response",
    "contact": {
      "name": "DeepInquiry API",
      "email": "api@deepinquiry.ai",
      "url": "https://www.deepinquiry.ai/docs"
    },
    "license": {
      "name": "DeepInquiry Terms of Service",
      "url": "https://www.deepinquiry.ai/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.deepinquiry.ai/api",
      "description": "DeepInquiry API"
    }
  ],
  "tags": [
    {
      "name": "Facts",
      "description": "Read-only access to the verified-facts corpus."
    },
    {
      "name": "Search",
      "description": "Semantic search across the corpus."
    }
  ],
  "paths": {
    "/v1/facts": {
      "get": {
        "tags": [
          "Facts"
        ],
        "summary": "List approved facts",
        "description": "Returns up to 50 approved facts, filtered by category and verification\ntier. Order is randomized on the server so repeated calls return\ndifferent samples.\n",
        "operationId": "listFacts",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Restrict to a single category (e.g. `science`, `history`).",
            "required": false,
            "schema": {
              "type": "string",
              "example": "science"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max facts to return. Clamped to 50.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          },
          {
            "name": "min_tier",
            "in": "query",
            "description": "Minimum verification tier. `gold` is strictest. The effective floor\nis the stricter of the request and the caller's plan.\n",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "gold",
                "silver",
                "bronze",
                "unverified"
              ]
            }
          },
          {
            "name": "include_unverified",
            "in": "query",
            "description": "Only honored for scale/enterprise callers. When `true`, unverified\nfacts may appear in the result set.\n",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Facts list",
            "headers": {
              "X-DeepInquiry-Min-Tier": {
                "$ref": "#/components/headers/MinTierHeader"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/QuotaRemainingHeader"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FactList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/facts/{id}": {
      "get": {
        "tags": [
          "Facts"
        ],
        "summary": "Get a fact by ID with source clusters",
        "description": "Returns a single approved fact plus the full audit trail: every\nsource cluster that voted on it, with cluster ID, origin type,\nand member URLs.\n",
        "operationId": "getFact",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fact detail",
            "headers": {
              "X-DeepInquiry-Verification-Tier": {
                "$ref": "#/components/headers/VerificationTierHeader"
              },
              "X-DeepInquiry-Independence-Score": {
                "$ref": "#/components/headers/IndependenceScoreHeader"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/QuotaRemainingHeader"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "fact"
                  ],
                  "properties": {
                    "fact": {
                      "$ref": "#/components/schemas/FactWithClusters"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/facts/random": {
      "get": {
        "tags": [
          "Facts"
        ],
        "summary": "Get one random approved fact",
        "description": "Returns a single approved fact chosen at random, respecting the\ncaller's plan tier floor.\n",
        "operationId": "randomFact",
        "responses": {
          "200": {
            "description": "Random fact",
            "headers": {
              "X-DeepInquiry-Verification-Tier": {
                "$ref": "#/components/headers/VerificationTierHeader"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/QuotaRemainingHeader"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "fact"
                  ],
                  "properties": {
                    "fact": {
                      "$ref": "#/components/schemas/Fact"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Semantic search across the corpus",
        "description": "Finds the facts whose meaning is closest to the query and\nreturns up to 25 of them, each with a `similarity` score (0.0-1.0,\nhigher = closer).\n",
        "operationId": "searchFacts",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query. Max 500 characters.",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 500
            },
            "example": "how many hearts does an octopus have"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_tier",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "gold",
                "silver",
                "bronze",
                "unverified"
              ]
            }
          },
          {
            "name": "include_unverified",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked semantic-search results",
            "headers": {
              "X-DeepInquiry-Min-Tier": {
                "$ref": "#/components/headers/MinTierHeader"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/QuotaRemainingHeader"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "description": "Search is temporarily unavailable — retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "headers": {
      "MinTierHeader": {
        "description": "Effective minimum verification tier applied to this response.",
        "schema": {
          "type": "string",
          "enum": [
            "gold",
            "silver",
            "bronze",
            "unverified"
          ]
        }
      },
      "VerificationTierHeader": {
        "description": "The verification tier of the returned fact.",
        "schema": {
          "type": "string",
          "enum": [
            "gold",
            "silver",
            "bronze",
            "unverified"
          ]
        }
      },
      "IndependenceScoreHeader": {
        "description": "0.0-1.0. 1.0 is the top of the scale; it does not mean the evidence is independent.",
        "schema": {
          "type": "number",
          "format": "float",
          "minimum": 0,
          "maximum": 1
        }
      },
      "QuotaRemainingHeader": {
        "description": "Remaining requests in the caller's current billing window.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "schemas": {
      "Fact": {
        "type": "object",
        "required": [
          "id",
          "fact_text",
          "category"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "example": 1234
          },
          "fact_text": {
            "type": "string",
            "example": "An adult octopus has three hearts."
          },
          "category": {
            "type": "string",
            "example": "science"
          },
          "era": {
            "type": "string",
            "nullable": true,
            "example": "present day"
          },
          "region": {
            "type": "string",
            "nullable": true,
            "example": "global"
          },
          "surprise_score": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "minimum": 0,
            "maximum": 1
          },
          "confidence_level": {
            "type": "string",
            "nullable": true,
            "example": "high"
          },
          "verification_tier": {
            "type": "string",
            "nullable": true,
            "enum": [
              "gold",
              "silver",
              "bronze",
              "unverified"
            ]
          },
          "independence_score": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "minimum": 0,
            "maximum": 1
          },
          "cluster_count": {
            "type": "integer",
            "nullable": true,
            "minimum": 0
          },
          "citogenesis_flags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Non-empty when the verification pipeline detected signs that the supporting sources copied one another."
          },
          "claim_tier": {
            "type": "string",
            "nullable": true,
            "description": "Type/strength of claim (e.g. \"definitional\", \"empirical\")."
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "similarity": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "minimum": 0,
            "maximum": 1,
            "description": "Present only on /v1/search responses."
          },
          "source_notes": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            },
            "description": "Information only: weaker copies (for example a Wikipedia page or an aggregator) that were set aside because sources of another kind exist."
          }
        }
      },
      "SourceCluster": {
        "type": "object",
        "required": [
          "cluster_id",
          "origin_type",
          "member_urls"
        ],
        "properties": {
          "cluster_id": {
            "type": "string"
          },
          "origin_type": {
            "type": "string",
            "description": "e.g. \"primary\", \"secondary\", \"tertiary\""
          },
          "member_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "FactWithClusters": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Fact"
          },
          {
            "type": "object",
            "properties": {
              "source_clusters": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SourceCluster"
                }
              }
            }
          }
        ]
      },
      "Meta": {
        "type": "object",
        "properties": {
          "min_tier": {
            "type": "string",
            "enum": [
              "gold",
              "silver",
              "bronze",
              "unverified"
            ]
          },
          "include_unverified": {
            "type": "boolean"
          },
          "returned": {
            "type": "integer"
          },
          "query": {
            "type": "string",
            "description": "Present only on /v1/search responses."
          },
          "model": {
            "type": "string",
            "description": "Present only on /v1/search responses."
          }
        }
      },
      "FactList": {
        "type": "object",
        "required": [
          "facts",
          "meta"
        ],
        "properties": {
          "facts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fact"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "SearchResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/FactList"
          }
        ]
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code (e.g. `bad_request`, `unauthorized`, `forbidden`, `not_found`, `rate_limited`, `internal_error`)",
                "example": "bad_request"
              },
              "message": {
                "type": "string",
                "description": "Human-readable error description",
                "example": "limit must be between 1 and 25"
              },
              "request_id": {
                "type": "string",
                "description": "Server-assigned request identifier for support triage",
                "example": "req_abc123def456"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Request validation failed (missing, malformed, or out-of-range parameters)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "bad_request",
                "message": "limit must be between 1 and 25",
                "request_id": "req_abc123def456"
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid credential",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "x-api-key header missing or invalid",
                "request_id": "req_abc123def456"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Caller not permitted to request that tier or option",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "your plan cannot request bronze facts; choose a plan that includes them",
                "request_id": "req_abc123def456"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested fact or resource does not exist or is not approved",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "fact id 999999 not found or not approved",
                "request_id": "req_abc123def456"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Caller's plan quota exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "monthly quota exhausted",
                "request_id": "req_abc123def456"
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "internal_error",
                "message": "an unexpected error occurred",
                "request_id": "req_abc123def456"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}