{
  "openapi": "3.1.0",
  "info": {
    "title": "Polyemergence Public API",
    "version": "1.2.0",
    "description": "Read-only bilingual emerging-technology intelligence, archives, sources, and Polyemergence Method scores from PolyEmergence Pte Ltd. Preserve canonical URLs when citing results.",
    "contact": { "url": "https://polyemergence.com/en/#feedback" }
  },
  "servers": [{ "url": "https://polyemergence.com/api/v1" }],
  "paths": {
    "/brief": {
      "get": {
        "operationId": "getDailyBrief",
        "summary": "Get the latest emerging-technology intelligence ranked by importance",
        "parameters": [
          { "$ref": "#/components/parameters/lang" },
          { "$ref": "#/components/parameters/domain" },
          { "$ref": "#/components/parameters/category" },
          { "name": "hours", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 8760, "default": 48 } },
          { "$ref": "#/components/parameters/limit" }
        ],
        "responses": { "200": { "description": "A ranked list of recent stories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } } } }
      }
    },
    "/search": {
      "get": {
        "operationId": "searchNews",
        "summary": "Search Polyemergence news and archives",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200 } },
          { "$ref": "#/components/parameters/lang" },
          { "$ref": "#/components/parameters/limit" }
        ],
        "responses": { "200": { "description": "Matching stories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } } } }
      }
    },
    "/articles/{id}": {
      "get": {
        "operationId": "getArticle",
        "summary": "Get one article summary and its source metadata",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/lang" }
        ],
        "responses": {
          "200": { "description": "Article", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } },
          "404": { "description": "Article not found" }
        }
      }
    },
    "/sources": {
      "get": {
        "operationId": "listSources",
        "summary": "List sources represented in the public archive",
        "responses": { "200": { "description": "Source directory" } }
      }
    },
    "/methodology": {
      "get": {
        "operationId": "getMethodology",
        "summary": "Get scoring rules and editorial disclosures",
        "responses": { "200": { "description": "Polyemergence Method" } }
      }
    }
  },
  "components": {
    "parameters": {
      "lang": { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["en", "zh"], "default": "en" } },
      "domain": { "name": "domain", "in": "query", "description": "Field slug from /data/editorial-domains.json", "schema": { "type": "string", "enum": ["ai", "programmable_life", "energy_storage", "robotics_autonomy", "quantum_technology", "space_economy", "advanced_materials", "neurotechnology", "climate_water_environment", "agrifood_technology", "advanced_manufacturing"] } },
      "category": { "name": "category", "in": "query", "description": "Story-angle slug from /data/editorial-domains.json", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,31}$", "examples": ["research", "business", "policy"] } },
      "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
    },
    "schemas": {
      "Scores": {
        "type": "object",
        "properties": {
          "signal": { "type": "integer" }, "structure": { "type": "integer" }, "consequence": { "type": "integer" },
          "confidence": { "type": "integer" }, "momentum": { "type": "integer" }
        }
      },
      "Article": {
        "type": "object",
        "required": ["id", "title", "summary", "source", "source_url", "canonical_url", "category", "importance", "published_at"],
        "properties": {
          "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "full_summary": { "type": "string" },
          "source": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "canonical_url": { "type": "string", "format": "uri" },
          "language": { "type": "string" }, "category": { "type": "string" }, "domain": { "type": "string", "enum": ["ai", "programmable_life", "energy_storage", "robotics_autonomy", "quantum_technology", "space_economy", "advanced_materials", "neurotechnology", "climate_water_environment", "agrifood_technology", "advanced_manufacturing"] }, "importance": { "type": "integer" }, "scores": { "$ref": "#/components/schemas/Scores" },
          "related_domains": { "type": "array", "maxItems": 2, "items": { "type": "string" }, "description": "Related fields, without replacing the primary field." },
          "evidence": { "type": "object", "description": "Source provenance and explicitly supported maturity; not independent verification.", "properties": { "type": { "type": "string", "enum": ["official_release", "preprint", "research_paper", "media_report", "interview", "open_source", "unknown"] }, "stage": { "type": "string", "enum": ["laboratory", "demonstration", "pilot", "deployment", "unspecified"] } } },
          "reading_context": { "type": "string", "description": "Article-specific observation bound to the article and source, when available. Generic field guidance is excluded. This is not independent fact-checking." },
          "published_at": { "type": "string", "format": "date-time" }, "source_published_at": { "type": ["string", "null"], "format": "date-time", "description": "Original publication time, or null for undated discovery-only records." },
          "date_basis": { "type": "string", "description": "source_published or first_seen; discovery dates are not release dates." }, "first_seen_at": { "type": ["string", "null"], "format": "date-time" },
          "tags": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ArticleList": {
        "type": "object",
        "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } } }
      }
    }
  }
}