{
  "openapi": "3.1.0",
  "info": {
    "title": "News by Levels public reading API",
    "version": "1.0.0",
    "description": "Read-only access to published, source-attributed English news adaptations. No authentication or personal learner data. Public access is not a republication licence. Reading levels are not certified CEFR levels."
  },
  "servers": [
    {
      "url": "https://newsbylevels.com"
    }
  ],
  "paths": {
    "/api/discover.php": {
      "get": {
        "summary": "Search titles and excerpts; newest matches first, at most 20.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ],
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published news only; see endpoint for resource fields."
          },
          "400": {
            "description": "Invalid parameter."
          },
          "429": {
            "description": "Rate limit where applied; retry after Retry-After."
          },
          "503": {
            "description": "Temporarily unavailable."
          }
        }
      }
    },
    "/api/articles.php": {
      "get": {
        "summary": "Existing published story metadata catalogue.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Published news only; see endpoint for resource fields."
          },
          "400": {
            "description": "Invalid parameter."
          },
          "429": {
            "description": "Rate limit where applied; retry after Retry-After."
          },
          "503": {
            "description": "Temporarily unavailable."
          }
        }
      }
    },
    "/api/article.php": {
      "get": {
        "summary": "Existing story with three reading versions.",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published news only; see endpoint for resource fields."
          },
          "400": {
            "description": "Invalid parameter."
          },
          "429": {
            "description": "Rate limit where applied; retry after Retry-After."
          },
          "503": {
            "description": "Temporarily unavailable."
          }
        }
      }
    },
    "/api/level.php": {
      "get": {
        "summary": "Existing single reading version.",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "level",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published news only; see endpoint for resource fields."
          },
          "400": {
            "description": "Invalid parameter."
          },
          "429": {
            "description": "Rate limit where applied; retry after Retry-After."
          },
          "503": {
            "description": "Temporarily unavailable."
          }
        }
      }
    }
  },
  "externalDocs": {
    "url": "https://newsbylevels.com/developers.php"
  }
}