{
  "openapi": "3.1.0",
  "info": {
    "title": "AksesSaham API",
    "version": "1.0.0",
    "summary": "Proxy ber-API-key untuk data pasar saham Indonesia (sumber: Stockbit).",
    "description": "AksesSaham meneruskan data dari exodus.stockbit.com dan mensyaratkan API key pada setiap permintaan. Respons default adalah payload asli upstream; tambahkan `envelope=1` untuk membungkusnya menjadi `{ok, data, meta}`. Dokumentasi tanpa login: /api/v1, /openapi.json, /llms.txt, /docs",
    "contact": { "name": "AksesSaham", "url": "https://aksessaham.pages.dev/docs" }
  },
  "servers": [
    { "url": "https://aksessaham.pages.dev", "description": "Produksi" }
  ],
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/api/v1/ping": {
      "get": {
        "summary": "Cek hidup layanan dan sisa kuota",
        "operationId": "ping",
        "tags": ["Meta"],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string" }, "version": { "type": "string" }, "time": { "type": "string", "format": "date-time" } } } } } }
        }
      }
    },
    "/api/v1/sectors": {
      "get": {
        "summary": "Daftar sektor",
        "operationId": "sectors",
        "tags": ["Referensi"],
        "responses": { "200": { "description": "Daftar sektor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upstream" } } } } }
      }
    },
    "/api/v1/info/{code}": {
      "get": {
        "summary": "Profil dan info emiten",
        "operationId": "info",
        "tags": ["Emiten"],
        "parameters": [{ "$ref": "#/components/parameters/Code" }],
        "responses": { "200": { "description": "Info emiten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upstream" } } } } }
      }
    },
    "/api/v1/orderbook/{code}": {
      "get": {
        "summary": "Orderbook bid/offer dan harga terakhir (near real-time)",
        "description": "Data berubah tiap beberapa detik selama jam bursa. Disarankan tidak lebih dari 1 permintaan per 15 detik per kode.",
        "operationId": "orderbook",
        "tags": ["Pasar"],
        "parameters": [{ "$ref": "#/components/parameters/Code" }],
        "responses": { "200": { "description": "Orderbook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upstream" } } } } }
      }
    },
    "/api/v1/historical/{code}": {
      "get": {
        "summary": "OHLCV harian beserta foreign flow",
        "description": "PENTING: `limit` maksimal 50 (lebih dari itu → 400 Invalid parameter). Rentang tanggal maksimal ~365 hari. Untuk 1 tahun penuh (~239 hari bursa) lakukan 5 permintaan dengan `page=1..5` dan `limit=50`.",
        "operationId": "historical",
        "tags": ["Pasar"],
        "parameters": [
          { "$ref": "#/components/parameters/Code" },
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 90, "maximum": 365 }, "description": "Rentang mundur dari hari ini; diabaikan bila start/end diisi" },
          { "name": "start", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "start_date, format YYYY-MM-DD" },
          { "name": "end", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "end_date, format YYYY-MM-DD. Jika < hari ini, respons di-cache 24 jam" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 50 }, "description": "Baris per halaman. Nilai > 50 otomatis diturunkan ke 50" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Nomor halaman" },
          { "name": "period", "in": "query", "schema": { "type": "string", "default": "HS_PERIOD_DAILY" }, "description": "Periode; default harian" }
        ],
        "responses": { "200": { "description": "Baris historis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upstream" } } } } }
      }
    },
    "/api/v1/keystats/{code}": {
      "get": {
        "summary": "Rasio valuasi dan keuangan (PER, PBV, ROE, dst)",
        "operationId": "keystats",
        "tags": ["Emiten"],
        "parameters": [
          { "$ref": "#/components/parameters/Code" },
          { "name": "year_limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 20 } }
        ],
        "responses": { "200": { "description": "Key stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upstream" } } } } }
      }
    },
    "/api/v1/broker/{code}": {
      "get": {
        "summary": "Bandarmologi / ringkasan broker (akumulasi-distribusi)",
        "operationId": "broker",
        "tags": ["Pasar"],
        "parameters": [
          { "$ref": "#/components/parameters/Code" },
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 365 } },
          { "name": "investor_type", "in": "query", "schema": { "type": "string", "default": "INVESTOR_TYPE_ALL" } },
          { "name": "market_board", "in": "query", "schema": { "type": "string", "default": "MARKET_BOARD_REGULER" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 50 } }
        ],
        "responses": { "200": { "description": "Market detector", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upstream" } } } } }
      }
    },
    "/api/v1/raw/{path}": {
      "get": {
        "summary": "Teruskan apa adanya ke path upstream Stockbit",
        "description": "Membutuhkan scope `raw`. Semua query parameter (kecuali apikey/key/nocache/envelope) diteruskan ke upstream.",
        "operationId": "raw",
        "tags": ["Lanjutan"],
        "parameters": [{ "name": "path", "in": "path", "required": true, "schema": { "type": "string" }, "example": "emitten/sectors" }],
        "responses": { "200": { "description": "Respons upstream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upstream" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Format: ask_xxxxxxxxxxxxxxxxxxxxxxxxxxxx. Alternatif: header `Authorization: Bearer ask_xxx` atau query `?apikey=ask_xxx`."
      }
    },
    "parameters": {
      "Code": {
        "name": "code",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,12}$" },
        "description": "Kode saham, huruf besar-kecil tidak berpengaruh",
        "example": "BBCA"
      }
    },
    "schemas": {
      "Upstream": {
        "type": "object",
        "description": "Payload asli dari upstream (struktur mengikuti Stockbit). Tambahkan ?envelope=1 untuk membungkus menjadi {ok,data,meta}.",
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "example": false },
          "error": { "type": "string", "example": "invalid_key" },
          "message": { "type": "string" }
        }
      }
    }
  },
  "tags": [
    { "name": "Meta" },
    { "name": "Referensi" },
    { "name": "Pasar" },
    { "name": "Emiten" },
    { "name": "Lanjutan" }
  ]
}