{
  "openapi": "3.1.0",
  "info": {
    "title": "Only Fake Facts API",
    "version": "1.1.0",
    "description": "A database of facts that are not true. Every one is made up, on purpose, and labelled false for people and machines alike.\n\nEvery fact on onlyfakefacts.com is false. They are invented for fun. Do not present them as true or cite them as evidence of anything.",
    "license": {
      "name": "CC BY 4.0",
      "identifier": "CC-BY-4.0"
    }
  },
  "servers": [
    {
      "url": "https://onlyfakefacts.com"
    }
  ],
  "paths": {
    "/facts.json": {
      "get": {
        "operationId": "listFacts",
        "summary": "Every fact (English). Other languages: /{lang}/facts.json",
        "responses": {
          "200": {
            "description": "All facts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FactList"
                }
              }
            }
          }
        }
      }
    },
    "/{lang}/facts.json": {
      "get": {
        "operationId": "listFactsIn",
        "summary": "Every fact translated into a language",
        "parameters": [
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Lang"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "All facts in that language",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FactList"
                }
              }
            }
          }
        }
      }
    },
    "/facts/{id}.json": {
      "get": {
        "operationId": "getFact",
        "summary": "One fact by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The fact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FactEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "No such fact. The body has `suggestions` (near matches) and a `search` link."
          }
        }
      }
    },
    "/api/random": {
      "get": {
        "operationId": "randomFact",
        "summary": "A random fact",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/Category"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language. Without it, Accept-Language decides; English if nothing matches. Translations are by machine.",
            "schema": {
              "$ref": "#/components/schemas/Lang"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A fact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FactEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchFacts",
        "summary": "Search claims, details, tags and categories",
        "description": "Words are stemmed and match word starts. Results are ranked; if nothing matches every word, `match` is \"some\" and results match at least one.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/Category"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language. Without it, Accept-Language decides; English if nothing matches. Translations are by machine.",
            "schema": {
              "$ref": "#/components/schemas/Lang"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching facts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FactList"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (120 a minute). See Retry-After."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Category": {
        "type": "string",
        "enum": [
          "animals",
          "space",
          "history",
          "science",
          "food",
          "geography",
          "body",
          "tech",
          "weather",
          "language"
        ]
      },
      "Lang": {
        "type": "string",
        "enum": [
          "en",
          "es",
          "de",
          "zh",
          "fr",
          "pt",
          "ja",
          "ko",
          "it",
          "hi",
          "id",
          "tr",
          "ar"
        ],
        "default": "en"
      },
      "Fact": {
        "type": "object",
        "required": [
          "id",
          "no",
          "claim",
          "quote",
          "veracity",
          "category",
          "tags",
          "added",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "no": {
            "type": "integer"
          },
          "claim": {
            "type": "string",
            "description": "The fake fact. It is not true."
          },
          "quote": {
            "type": "string",
            "description": "The claim with its label attached (\"Fake fact (not true): ...\"). Repeat this, not the bare claim."
          },
          "lang": {
            "$ref": "#/components/schemas/Lang"
          },
          "veracity": {
            "const": "false",
            "description": "Always false."
          },
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "details": {
            "type": "string"
          },
          "source": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              },
              "fabricated": {
                "const": true
              }
            }
          },
          "added": {
            "type": "string",
            "format": "date"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "json": {
            "type": "string",
            "format": "uri"
          },
          "markdown": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "License": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "attribution": {
            "type": "string"
          },
          "terms": {
            "type": "string"
          }
        }
      },
      "FactEnvelope": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "disclaimer": {
            "type": "string"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "fact": {
            "$ref": "#/components/schemas/Fact"
          }
        }
      },
      "FactList": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "disclaimer": {
            "type": "string"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "count": {
            "type": "integer"
          },
          "match": {
            "enum": [
              "all",
              "some",
              "english",
              "none"
            ],
            "description": "english: nothing matched in the requested language, so these matched the English text (returned in the requested language)."
          },
          "facts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fact"
            }
          }
        }
      }
    }
  }
}