{
  "openapi": "3.0.3",
  "info": {
    "title": "Yes or No Oracle API",
    "version": "1.1.0",
    "description": "A free, key-less API that answers a yes-or-no question with a random yes, no or maybe, in one of 8 oracle voices. Every answer comes with a themed headline (`word`) and a reflective sentence (`phrase`). Answers are random draws from curated pools, so you don't send the question. No sign-up, no API key, CORS open to all origins.",
    "termsOfService": "https://yesnooracle.app/terms",
    "contact": {
      "name": "Yes or No Oracle",
      "url": "https://yesnooracle.app/contact",
      "email": "hello@yesnooracle.app"
    },
    "license": {
      "name": "Free for personal and commercial use",
      "url": "https://yesnooracle.app/api"
    },
    "x-logo": {
      "url": "https://yesnooracle.app/apple-touch-icon.png"
    }
  },
  "externalDocs": {
    "description": "Docs and live playground",
    "url": "https://yesnooracle.app/api"
  },
  "servers": [
    {
      "url": "https://yesnooracle.app"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "oracle",
      "description": "Random yes / no / maybe answers"
    }
  ],
  "paths": {
    "/api/oracle": {
      "get": {
        "tags": [
          "oracle"
        ],
        "operationId": "getOracleAnswer",
        "summary": "Get a random yes, no or maybe answer",
        "description": "Returns one random answer from the chosen oracle's pool, as JSON or as one line of plain text.",
        "parameters": [
          {
            "name": "tool",
            "in": "query",
            "required": false,
            "description": "Which oracle answers: `oracle` (Yes or No Oracle), `magic-8-ball` (Magic 8 Ball), `crystal-ball` (Crystal Ball), `i-ching` (I Ching), `pendulum` (Yes or No Pendulum), `tarot` (Yes or No Tarot), `runes` (Rune Reading), `wheel` (Yes or No Wheel). Defaults to `oracle`. The short aliases `magic8`, `crystal`, `iching` also work.",
            "schema": {
              "type": "string",
              "enum": [
                "oracle",
                "magic-8-ball",
                "crystal-ball",
                "i-ching",
                "pendulum",
                "tarot",
                "runes",
                "wheel",
                "magic8",
                "crystal",
                "iching"
              ],
              "default": "oracle"
            }
          },
          {
            "name": "force",
            "in": "query",
            "required": false,
            "description": "Force the verdict, for tests and demos. Any other value is ignored.",
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no",
                "maybe"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "`json` (default) or `text`. Text returns one plain line, e.g. \"It is certain. No doubt about it — the ball is sure.\", for Twitch chat bots such as Nightbot ($(urlfetch …)) and StreamElements ($(customapi …)).",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "text"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An answer: JSON by default, one line of plain text with format=text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OracleAnswer"
                },
                "example": {
                  "answer": "yes",
                  "verdict": "yes",
                  "word": "It is certain",
                  "phrase": "No doubt about it — the ball is sure.",
                  "tool": "magic-8-ball",
                  "forced": false,
                  "image": "https://yesnooracle.app/art-magic8.webp"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "It is certain. No doubt about it — the ball is sure."
              }
            }
          },
          "400": {
            "description": "Unknown tool or format. With format=text the error is plain text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from one IP: about 60 a minute for JSON, 600 a minute for text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OracleAnswer": {
        "type": "object",
        "required": [
          "answer",
          "verdict",
          "word",
          "phrase",
          "tool",
          "forced",
          "image"
        ],
        "properties": {
          "answer": {
            "type": "string",
            "enum": [
              "yes",
              "no",
              "maybe"
            ],
            "description": "The verdict, normalized to yes / no / maybe."
          },
          "verdict": {
            "type": "string",
            "enum": [
              "yes",
              "no",
              "again"
            ],
            "description": "The raw verdict. `again` is the oracle's \"ask again\" and maps to `maybe`."
          },
          "word": {
            "type": "string",
            "description": "Themed headline, e.g. \"It is certain\" or a tarot card name."
          },
          "phrase": {
            "type": "string",
            "description": "A reflective sentence in the oracle's voice."
          },
          "tool": {
            "type": "string",
            "description": "The tool value you passed, or `oracle`."
          },
          "forced": {
            "type": "boolean",
            "description": "True when `force` chose the verdict."
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "Artwork for the oracle that answered."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "validTools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "validFormats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}