{
  "openapi": "3.0.3",
  "info": {
    "title": "Mekong Analytics Data Feed API",
    "description": "Programmatic access to English translations of investor-meeting documents (AGM/EGM transcripts, earnings calls) from Vietnamese listed companies.",
    "version": "1.0.0"
  },
  "servers": [{ "url": "https://app-production-d622.up.railway.app" }],
  "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
  "paths": {
    "/api/v1/companies": {
      "get": {
        "summary": "List covered companies",
        "parameters": [
          { "name": "sector", "in": "query", "schema": { "type": "string" }, "description": "GICS sector code (2 digits)" },
          { "name": "exchange", "in": "query", "schema": { "type": "string", "enum": ["HOSE", "HNX", "UPCOM"] } }
        ],
        "responses": {
          "200": {
            "description": "Company list",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/documents": {
      "get": {
        "summary": "List published documents (paginated)",
        "parameters": [
          { "name": "company", "in": "query", "schema": { "type": "string" }, "description": "Ticker, e.g. VNM" },
          { "name": "sector", "in": "query", "schema": { "type": "string" }, "description": "GICS sector code" },
          { "name": "meeting_type", "in": "query", "schema": { "type": "string", "enum": ["agm", "egm", "quarterly_call", "investor_day"] } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Meeting date from" },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Meeting date to" },
          { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Incremental sync cursor" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated document list",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/documents/{id}": {
      "get": {
        "summary": "Full document with extracted text and signed PDF links",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "xml"], "default": "json" } }
        ],
        "responses": {
          "200": {
            "description": "Document detail",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } },
              "application/xml": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } }
            }
          },
          "404": { "description": "Not found or not published" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "responses": {
      "Unauthorized": { "description": "Missing, invalid or inactive API key" },
      "RateLimited": { "description": "Rate limit exceeded (60 requests/minute per key)" }
    },
    "schemas": {
      "Gics": {
        "type": "object",
        "properties": { "code": { "type": "string" }, "name": { "type": "string" } }
      },
      "Company": {
        "type": "object",
        "properties": {
          "ticker": { "type": "string" },
          "name_en": { "type": "string" },
          "name_vi": { "type": "string" },
          "exchange": { "type": "string", "enum": ["HOSE", "HNX", "UPCOM"] },
          "gics_sector": { "$ref": "#/components/schemas/Gics" },
          "gics_industry": { "$ref": "#/components/schemas/Gics" }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "ticker": { "type": "string" },
          "company_name": { "type": "string" },
          "exchange": { "type": "string" },
          "gics_sector": { "$ref": "#/components/schemas/Gics" },
          "title": { "type": "string" },
          "meeting_type": { "type": "string", "enum": ["agm", "egm", "quarterly_call", "investor_day"] },
          "fiscal_period": { "type": "string" },
          "meeting_date": { "type": "string", "format": "date" },
          "publish_date": { "type": "string", "format": "date", "nullable": true },
          "document_type": { "type": "string", "enum": ["transcript", "slides", "press_release"] },
          "access_tier": { "type": "string", "enum": ["public_preview", "gated"] },
          "page_count": { "type": "integer", "nullable": true },
          "word_count": { "type": "integer", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "DocumentDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/Document" },
          {
            "type": "object",
            "properties": {
              "extracted_text": { "type": "string", "nullable": true },
              "pdf_original_url": { "type": "string", "nullable": true, "description": "Signed URL for the original Vietnamese PDF" },
              "pdf_translated_url": { "type": "string", "nullable": true, "description": "Signed URL for the translated English PDF" },
              "pdf_url_expires_in_seconds": { "type": "integer" }
            }
          }
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "per_page": { "type": "integer" },
          "total": { "type": "integer" },
          "total_pages": { "type": "integer" }
        }
      }
    }
  }
}