{
  "openapi": "3.1.0",
  "info": {
    "title": "eipan API",
    "version": "1.0.0",
    "description": "Read-only JSON API for the eipane.com archive of Greek sayings, proverbs, expressions and words. Editorial text is licensed under CC BY 4.0. Attribution to eipane.com and a link are expected where outputs cite or reproduce entries. Third-party quotations and the eipan brand are excluded.",
    "termsOfService": "https://eipane.com/oroi-chrisis/",
    "license": {
      "name": "CC BY 4.0",
      "identifier": "CC-BY-4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "url": "https://eipane.com/epikoinonia/"
    }
  },
  "servers": [
    {
      "url": "https://api.eipane.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "API index",
        "operationId": "getIndex",
        "responses": {
          "200": {
            "description": "Index and documentation links"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "OpenAPI document",
        "operationId": "getOpenApi",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document"
          }
        }
      }
    },
    "/v1/entries": {
      "get": {
        "summary": "List public entries",
        "operationId": "listEntries",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "gnomiko",
                "paroimia",
                "ekfrasi",
                "lexi"
              ]
            }
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Theme slug, e.g. sofia"
          },
          {
            "name": "collection",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Collection slug"
          },
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Personal-name tag slug, e.g. giannis"
          },
          {
            "name": "indexable",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "When true, only sitemap/indexable entries. When false, only noindex published entries."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated entry list"
          }
        }
      }
    },
    "/v1/entries/{slug}": {
      "get": {
        "summary": "Get one entry",
        "operationId": "getEntry",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entry"
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Search entries (accent-insensitive and Greeklish)",
        "operationId": "searchEntries",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "gnomiko",
                "paroimia",
                "ekfrasi",
                "lexi"
              ]
            }
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "collection",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Personal-name tag slug, e.g. giannis"
          },
          {
            "name": "indexable",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "When true, only sitemap/indexable entries. When false, only noindex published entries."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked matches"
          },
          "400": {
            "description": "Missing or short query"
          }
        }
      }
    },
    "/v1/random": {
      "get": {
        "summary": "Random public entry",
        "operationId": "randomEntry",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "gnomiko",
                "paroimia",
                "ekfrasi",
                "lexi"
              ]
            }
          },
          {
            "name": "indexable",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "When true, only sitemap/indexable entries. When false, only noindex published entries."
          }
        ],
        "responses": {
          "200": {
            "description": "One entry"
          }
        }
      }
    },
    "/v1/today": {
      "get": {
        "summary": "Phrase of the day (deterministic for the Europe/Athens date)",
        "operationId": "todayEntry",
        "parameters": [
          {
            "name": "indexable",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "When true, only sitemap/indexable entries. When false, only noindex published entries."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "gnomiko",
                "paroimia",
                "ekfrasi",
                "lexi"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Today’s entry"
          }
        }
      }
    },
    "/v1/themes": {
      "get": {
        "summary": "List themes",
        "operationId": "listThemes",
        "responses": {
          "200": {
            "description": "Themes"
          }
        }
      }
    },
    "/v1/collections": {
      "get": {
        "summary": "List collections",
        "operationId": "listCollections",
        "responses": {
          "200": {
            "description": "Collections"
          }
        }
      }
    },
    "/v1/names": {
      "get": {
        "summary": "List personal-name tags",
        "operationId": "listNames",
        "responses": {
          "200": {
            "description": "Names that appear in sayings"
          }
        }
      }
    },
    "/v1/names/{slug}": {
      "get": {
        "summary": "Get one personal-name tag and its entries",
        "operationId": "getName",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Name and entries"
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Attribution": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "example": "eipane.com"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string",
            "example": "CC BY 4.0"
          }
        },
        "required": [
          "source",
          "url",
          "license"
        ]
      }
    }
  },
  "security": []
}