{
  "openapi": "3.1.0",
  "info": {
    "title": "TAG.GDP Public API",
    "description": "Read-oriented public API for Talal Abu-Ghazaleh Global Digital Polytechnic (TAG.GDP / TAGGDP / GDPT). Covers catalog, news, FAQs, CMS pages, certificate verification, and agent discovery. Authenticated learner/admin endpoints are out of scope.",
    "version": "1.0.0",
    "contact": {
      "name": "TAG.GDP",
      "url": "https://taggdp.global/support"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://taggdp.global/api/public",
      "description": "Public API base (same host as the marketing site when /api is proxied)"
    }
  ],
  "tags": [
    { "name": "Catalog", "description": "Categories and courses" },
    { "name": "News", "description": "News and articles" },
    { "name": "Content", "description": "CMS pages, FAQs, search" },
    { "name": "Certificates", "description": "Public certificate verification" },
    { "name": "Discovery", "description": "Agent and feed discovery" }
  ],
  "paths": {
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "tags": ["Catalog"],
        "summary": "List public certification categories",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string", "example": "en" }
          }
        ],
        "responses": {
          "200": {
            "description": "Category list",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }
              }
            }
          }
        }
      }
    },
    "/categories/{slug}": {
      "get": {
        "operationId": "getCategory",
        "tags": ["Catalog"],
        "summary": "Get a category by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Category detail" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/courses": {
      "get": {
        "operationId": "listCourses",
        "tags": ["Catalog"],
        "summary": "List public courses",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Paginated course list" }
        }
      }
    },
    "/courses/{slug}": {
      "get": {
        "operationId": "getCourse",
        "tags": ["Catalog"],
        "summary": "Get a course by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Course detail" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/news": {
      "get": {
        "operationId": "listNews",
        "tags": ["News"],
        "summary": "List active news articles",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 10 }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "News list",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NewsItem" } }
              }
            }
          }
        }
      }
    },
    "/news/{slug}": {
      "get": {
        "operationId": "getNews",
        "tags": ["News"],
        "summary": "Get a news article by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "News article" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/pages/{slug}": {
      "get": {
        "operationId": "getPage",
        "tags": ["Content"],
        "summary": "Get a published CMS page",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "CMS page with SEO metadata" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/faqs": {
      "get": {
        "operationId": "listFaqs",
        "tags": ["Content"],
        "summary": "List public FAQs grouped by category",
        "responses": {
          "200": { "description": "FAQ groups" }
        }
      }
    },
    "/search": {
      "get": {
        "operationId": "searchSite",
        "tags": ["Content"],
        "summary": "Search public site content",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Search results" }
        }
      }
    },
    "/certificates/{code}": {
      "get": {
        "operationId": "verifyCertificate",
        "tags": ["Certificates"],
        "summary": "Verify a digitally issued certificate by public code",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Certificate verification payload" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/agent": {
      "get": {
        "operationId": "getAgentDiscovery",
        "tags": ["Discovery"],
        "summary": "HTTP+JSON agent discovery document",
        "responses": {
          "200": { "description": "Agent skills and documentation links" }
        }
      }
    },
    "/x402": {
      "get": {
        "operationId": "getX402Discovery",
        "tags": ["Discovery"],
        "summary": "x402 micropayment protocol discovery",
        "responses": {
          "200": { "description": "x402 configuration and challenge URLs" }
        }
      }
    },
    "/x402/challenge": {
      "get": {
        "operationId": "getX402Challenge",
        "tags": ["Discovery"],
        "summary": "x402 HTTP 402 payment challenge probe",
        "description": "Always returns HTTP 402 with PAYMENT-REQUIRED headers for agent discovery.",
        "responses": {
          "402": {
            "description": "Payment Required — includes PAYMENT-REQUIRED header (Base64 JSON)",
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": { "type": "string" },
                "description": "Base64-encoded PaymentRequired object"
              },
              "WWW-Authenticate": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/x402/courses/{slug}": {
      "get": {
        "operationId": "getX402CoursePayment",
        "tags": ["Discovery", "Catalog"],
        "summary": "x402 payment challenge for a paid course",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Course is free — no payment required" },
          "402": { "description": "Payment required for paid course" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/rss": {
      "get": {
        "operationId": "getRssFeed",
        "tags": ["Discovery", "News"],
        "summary": "RSS 2.0 news feed",
        "responses": {
          "200": {
            "description": "RSS feed",
            "content": {
              "application/rss+xml": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/languages": {
      "get": {
        "operationId": "listLanguages",
        "tags": ["Content"],
        "summary": "List supported UI languages",
        "responses": {
          "200": { "description": "Language list" }
        }
      }
    },
    "/settings": {
      "get": {
        "operationId": "getPublicSettings",
        "tags": ["Content"],
        "summary": "Public site settings",
        "responses": {
          "200": { "description": "Settings map" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "slug": { "type": "string" },
          "name": {},
          "description": {},
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "NewsItem": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "slug": { "type": "string" },
          "title": {},
          "author": {},
          "published_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "image_url": { "type": "string" }
        }
      },
      "ErrorMessage": {
        "type": "object",
        "properties": {
          "message": { "type": "string" }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorMessage" }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limited",
        "headers": {
          "Retry-After": {
            "schema": { "type": "integer" },
            "description": "Seconds to wait before retrying"
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorMessage" }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "llms.txt — documentation for AI assistants",
    "url": "https://taggdp.global/llms.txt"
  }
}