{
  "openapi": "3.1.0",
  "info": {
    "title": "GXceed Paper Search API",
    "version": "1.0.0",
    "description": "Public keyword search API for GX, ESG, and climate disclosure papers indexed by GXceed. No authentication required. Fair-use guideline ~60 req/min/IP (hard enforcement may be added if abused). Full docs: https://gxceed.com/en/api-reference",
    "contact": {
      "name": "GXceed",
      "url": "https://gxceed.com/en/api-reference",
      "email": "hello@gxceed.com"
    },
    "license": {
      "name": "AI-generated summaries and GXceed-authored metadata: CC BY 4.0 unless otherwise stated. Third-party paper metadata, abstracts, DOIs, and source links remain subject to their original publishers' terms.",
      "url": "https://gxceed.com/legal/terms"
    }
  },
  "servers": [
    {
      "url": "https://gxceed.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/papers/search": {
      "get": {
        "operationId": "searchPapers",
        "summary": "Search GXceed papers",
        "description": "Search published GXceed papers by keyword. Returns citation-friendly metadata including title, authors, venue, year, citation_url, and updated_at.",
        "tags": ["Papers"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query, 2–500 characters. Up to 5 whitespace-separated terms, AND-combined.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 500,
              "example": "carbon disclosure EDINET"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "description": "Filter by topic slug.",
            "schema": {
              "type": "string",
              "enum": [
                "esg",
                "energy_transition",
                "carbon_pricing",
                "climate_finance",
                "ccus",
                "hydrogen",
                "renewable",
                "policy",
                "carbon_accounting",
                "climate_science",
                "disclosure_infrastructure",
                "transition_finance",
                "energy_efficiency",
                "scope3",
                "scope1_2",
                "tcfd",
                "sbt",
                "cdp",
                "ev",
                "greenwashing",
                "climate_risk",
                "biodiversity",
                "supply_chain",
                "ai_esg",
                "other"
              ],
              "example": "carbon_pricing"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Filter by paper language.",
            "schema": {
              "type": "string",
              "enum": ["ja", "en", "all"],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of results to skip (for pagination).",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "api_version": "v1",
                  "query": "carbon disclosure EDINET",
                  "topic": null,
                  "lang": "all",
                  "total": 42,
                  "count": 10,
                  "limit": 10,
                  "offset": 0,
                  "results": [
                    {
                      "id": "abc123",
                      "title": "Structured GHG Disclosure Accessibility for Listed Japanese Firms",
                      "title_ja": "上場企業の GHG 開示アクセシビリティ構造化",
                      "title_en": "Structured GHG Disclosure Accessibility for Listed Japanese Firms",
                      "authors": ["Hiroyuki Kokubu"],
                      "year": 2026,
                      "abstract": "An engineering pilot using EDINET and LLM-assisted report extraction to improve GHG disclosure accessibility.",
                      "url": "https://gxceed.com/papers/abc123",
                      "citation_url": "https://doi.org/10.2139/ssrn.xxxx",
                      "doi": "10.2139/ssrn.xxxx",
                      "source_url": "https://ssrn.com/abstract=xxxx",
                      "venue": "SSRN",
                      "venue_type": "preprint",
                      "topic": "disclosure_infrastructure",
                      "tags": ["GHG", "EDINET", "disclosure", "LLM"],
                      "lang": "en",
                      "updated_at": "2026-05-16T00:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — rate limit exceeded. Retry after a short delay, or contact hello@gxceed.com for higher-volume access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResponse": {
        "type": "object",
        "required": ["api_version", "query", "total", "count", "limit", "offset", "results"],
        "properties": {
          "api_version": {
            "type": "string",
            "description": "API version identifier. Currently 'v1'. Use this to guard against future breaking changes.",
            "example": "v1"
          },
          "query": {
            "type": "string",
            "description": "The search query as submitted."
          },
          "topic": {
            "type": ["string", "null"],
            "description": "Active topic filter, or null if not set."
          },
          "lang": {
            "type": "string",
            "description": "Active language filter."
          },
          "total": {
            "type": "integer",
            "description": "Total number of matching papers (before limit/offset)."
          },
          "count": {
            "type": "integer",
            "description": "Number of results returned in this response."
          },
          "limit": {
            "type": "integer",
            "description": "Applied limit."
          },
          "offset": {
            "type": "integer",
            "description": "Applied offset."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Paper"
            }
          }
        }
      },
      "Paper": {
        "type": "object",
        "required": ["id", "url"],
        "properties": {
          "id": {
            "type": "string",
            "description": "GXceed internal paper ID."
          },
          "title": {
            "type": ["string", "null"],
            "description": "Paper title in original language."
          },
          "title_ja": {
            "type": ["string", "null"],
            "description": "Japanese title (AI-translated if not originally Japanese)."
          },
          "title_en": {
            "type": ["string", "null"],
            "description": "English title (AI-translated if not originally English)."
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Author display names."
          },
          "year": {
            "type": ["integer", "null"],
            "description": "Publication year."
          },
          "abstract": {
            "type": ["string", "null"],
            "description": "AI-generated English summary if available, otherwise Japanese summary or original abstract. Capped at 600 characters."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "GXceed paper detail page URL."
          },
          "citation_url": {
            "type": "string",
            "format": "uri",
            "description": "Best stable link for citing this work, with provenance: DOI link (https://doi.org/...) when a DOI exists, otherwise the original source URL, otherwise the GXceed page. Use this when citing papers in AI-generated answers."
          },
          "doi": {
            "type": ["string", "null"],
            "description": "Digital Object Identifier."
          },
          "source_url": {
            "type": ["string", "null"],
            "format": "uri",
            "description": "Original source URL (preprint server, journal, etc.)."
          },
          "venue": {
            "type": ["string", "null"],
            "description": "Publication venue name."
          },
          "venue_type": {
            "type": ["string", "null"],
            "enum": ["preprint", "journal", "conference", "dataset", "report", null],
            "description": "Venue type classification."
          },
          "topic": {
            "type": ["string", "null"],
            "description": "Primary GX topic classification."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "AI-assigned keyword tags."
          },
          "lang": {
            "type": ["string", "null"],
            "enum": ["ja", "en", "mul", null],
            "description": "Paper language: ja (Japanese), en (English), mul (multilingual)."
          },
          "updated_at": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "ISO 8601 UTC timestamp of when this paper record was last updated in GXceed. Useful for freshness checks. Falls back to the publication date if no update timestamp exists."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Papers",
      "description": "GX and sustainability paper search"
    }
  ],
  "externalDocs": {
    "description": "GXceed API Reference",
    "url": "https://gxceed.com/en/api-reference"
  }
}