{
  "openapi": "3.0.3",
  "info": {
    "title": "MetaGazette public news API",
    "description": "Read-only JSON for published journalism. Not a commerce API: no price, stock, SKU or checkout. Partner ingest is out of scope.",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://api.metagazette.com", "description": "Production API" },
    { "url": "https://tr.metagazette.com", "description": "Same-origin /api on the Turkish host" }
  ],
  "paths": {
    "/api/languages": {
      "get": {
        "operationId": "listLanguages",
        "summary": "List published language editions",
        "responses": {
          "200": {
            "description": "Language list",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Language" } } } }
          }
        }
      }
    },
    "/api/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List news sections for a language",
        "parameters": [{ "$ref": "#/components/parameters/languageCode" }],
        "responses": {
          "200": {
            "description": "Categories",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } }
          }
        }
      }
    },
    "/api/tags": {
      "get": {
        "operationId": "listTags",
        "summary": "List tags for a language",
        "parameters": [{ "$ref": "#/components/parameters/languageCode" }],
        "responses": {
          "200": {
            "description": "Tags",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } }
          }
        }
      }
    },
    "/api/articles": {
      "get": {
        "operationId": "listArticles",
        "summary": "List published articles",
        "parameters": [
          { "$ref": "#/components/parameters/languageCode" },
          { "name": "take", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "categorySlug", "in": "query", "schema": { "type": "string" } },
          { "name": "tagSlug", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Article list or paged payload",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } }
          }
        }
      }
    },
    "/api/articles/{slug}": {
      "get": {
        "operationId": "getArticle",
        "summary": "Get one published article",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/languageCode" }
        ],
        "responses": {
          "200": {
            "description": "Article",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } }
          },
          "404": { "description": "Not found" }
        }
      }
    },
    "/api/homepage": {
      "get": {
        "operationId": "getHomepage",
        "summary": "Front-page payload for a language",
        "parameters": [{ "$ref": "#/components/parameters/languageCode" }],
        "responses": {
          "200": {
            "description": "Homepage",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Liveness",
        "responses": { "200": { "description": "OK" } }
      }
    }
  },
  "components": {
    "parameters": {
      "languageCode": {
        "name": "languageCode",
        "in": "query",
        "required": true,
        "schema": { "type": "string", "enum": ["en", "tr", "de", "es", "ar"] }
      }
    },
    "schemas": {
      "Language": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "code": { "type": "string" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "description": { "type": "string" }
        }
      },
      "Tag": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" }
        }
      },
      "Article": {
        "type": "object",
        "required": ["slug", "title"],
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "content": { "type": "string" },
          "coverImageUrl": { "type": "string", "nullable": true },
          "authorName": { "type": "string" },
          "publishedAtUtc": { "type": "string", "format": "date-time" },
          "updatedAtUtc": { "type": "string", "format": "date-time" },
          "createdAtUtc": { "type": "string", "format": "date-time" },
          "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } },
          "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }
        },
        "description": "Published journalism. There is no price, availability, sku or gtin field on articles. Publication-level access is price=0 TRY, availability=https://schema.org/InStock in JSON-LD Offer."
      },
      "PublicationAccess": {
        "type": "object",
        "description": "Function-calling shape for the news service itself (not a physical product). SKU/GTIN/MPN are not assigned.",
        "properties": {
          "name": { "type": "string", "example": "MetaGazette" },
          "description": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "image": { "type": "string", "format": "uri" },
          "brand": { "type": "string", "example": "MetaGazette" },
          "price": { "type": "string", "example": "0" },
          "priceCurrency": { "type": "string", "example": "TRY" },
          "availability": { "type": "string", "example": "https://schema.org/InStock" }
        }
      },
      "ArticleList": {
        "oneOf": [
          { "type": "array", "items": { "$ref": "#/components/schemas/Article" } },
          {
            "type": "object",
            "properties": {
              "items": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } },
              "totalCount": { "type": "integer" },
              "page": { "type": "integer" },
              "pageSize": { "type": "integer" }
            }
          }
        ]
      }
    }
  }
}