{"openapi":"3.0.3","info":{"title":"Apibir API","version":"0.1.0","description":"JSON API for FX rates and macro series.\n\n## Authentication\n\nProtected routes require an API key via either header:\n\n- `X-API-Key: apibir_\u2026`\n- `Authorization: Bearer apibir_\u2026`\n\nCreate keys in the developer panel. FX and macro quotas are counted separately.\n\n## Response envelope\n\nSuccessful data responses wrap the payload as:\n\n```json\n{\n  \"success\": true,\n  \"source\": \"fx\",\n  \"asOf\": \"2026-08-07T15:30:00+03:00\",\n  \"license\": \"\u2026\",\n  \"cached\": false,\n  \"data\": {}\n}\n```"},"servers":[{"url":"https:\/\/apibir.com","description":"Current environment"}],"tags":[{"name":"Health","description":"Service status"},{"name":"FX","description":"Foreign exchange rates"},{"name":"Macro","description":"Macro economic series"}],"paths":{"\/health":{"get":{"tags":["Health"],"operationId":"getHealth","summary":"Health check","description":"Returns application, database, and cache status. No authentication required.","security":[],"responses":{"200":{"description":"Service is healthy","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/HealthResponse"},"example":{"success":true,"status":"ok","db":true,"cache":true,"time":"2026-08-07T15:30:00+00:00"}}}}}}},"\/v1\/fx\/rates":{"get":{"tags":["FX"],"operationId":"getFxRates","summary":"Current FX rates","description":"Current reference rates (buying \/ selling). Consumes FX quota.","security":[{"ApiKey":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Success envelope","content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/FxRatesData"}}}]},"example":{"success":true,"source":"fx","asOf":"2026-08-07T15:30:00+03:00","license":"","cached":false,"data":[{"pair":"USDTRY","buying":34.05,"selling":34.19},{"pair":"EURTRY","buying":36.98,"selling":37.12}]}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"examples":{"missing":{"summary":"Missing key","value":{"success":false,"error":"missing_api_key","message":"Provide X-API-Key or Authorization: Bearer apibir_\u2026"}},"invalid":{"summary":"Invalid key","value":{"success":false,"error":"invalid_api_key","message":"API key is invalid or revoked"}}}}}},"429":{"description":"Quota exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"success":false,"error":"quota_exceeded","message":"FX monthly quota exceeded"}}}}}}},"\/v1\/fx\/rates\/{pair}\/history":{"get":{"tags":["FX"],"operationId":"getFxHistory","summary":"FX history","description":"Pair history by date range. Default range: last 7 days. Consumes FX quota.","security":[{"ApiKey":[]},{"BearerAuth":[]}],"parameters":[{"name":"pair","in":"path","required":true,"description":"Currency pair, e.g. USDTRY","schema":{"type":"string","example":"USDTRY"}},{"name":"start","in":"query","required":false,"description":"Start date (YYYY-MM-DD). Defaults to 7 days ago.","schema":{"type":"string","format":"date","example":"2026-08-01"}},{"name":"end","in":"query","required":false,"description":"End date (YYYY-MM-DD). Defaults to today.","schema":{"type":"string","format":"date","example":"2026-08-07"}}],"responses":{"200":{"description":"Success envelope","content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/FxHistoryData"}}}]},"example":{"success":true,"source":"macro","asOf":"2026-08-07T15:30:00+03:00","license":"","cached":false,"data":[{"date":"2026-08-06","value":34.12},{"date":"2026-08-07","value":34.18}]}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"examples":{"missing":{"summary":"Missing key","value":{"success":false,"error":"missing_api_key","message":"Provide X-API-Key or Authorization: Bearer apibir_\u2026"}},"invalid":{"summary":"Invalid key","value":{"success":false,"error":"invalid_api_key","message":"API key is invalid or revoked"}}}}}},"429":{"description":"Quota exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"success":false,"error":"quota_exceeded","message":"FX monthly quota exceeded"}}}}}}},"\/v1\/macro\/catalog":{"get":{"tags":["Macro"],"operationId":"getMacroCatalog","summary":"Macro series catalog","description":"Search the macro series catalog. Consumes macro quota.","security":[{"ApiKey":[]},{"BearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Search text","schema":{"type":"string","example":"enflasyon"}}],"responses":{"200":{"description":"Success envelope","content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/MacroCatalogData"}}}]},"example":{"success":true,"source":"macro","asOf":"2026-08-07T15:30:00+03:00","license":"","cached":false,"data":[{"code":"TP.FG.J0","name":"T\u00dcFE (2003=100)"}]}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"examples":{"missing":{"summary":"Missing key","value":{"success":false,"error":"missing_api_key","message":"Provide X-API-Key or Authorization: Bearer apibir_\u2026"}},"invalid":{"summary":"Invalid key","value":{"success":false,"error":"invalid_api_key","message":"API key is invalid or revoked"}}}}}},"429":{"description":"Quota exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"success":false,"error":"quota_exceeded","message":"FX monthly quota exceeded"}}}}}}},"\/v1\/macro\/series\/{code}":{"get":{"tags":["Macro"],"operationId":"getMacroSeries","summary":"Macro series observations","description":"Observations for a series code. Default range: last 30 days. Consumes macro quota.","security":[{"ApiKey":[]},{"BearerAuth":[]}],"parameters":[{"name":"code","in":"path","required":true,"description":"Series code","schema":{"type":"string","example":"TP.FG.J0"}},{"name":"start","in":"query","required":false,"description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date","example":"2026-01-01"}},{"name":"end","in":"query","required":false,"description":"End date (YYYY-MM-DD)","schema":{"type":"string","format":"date","example":"2026-08-01"}}],"responses":{"200":{"description":"Success envelope","content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/MacroSeriesData"}}}]},"example":{"success":true,"source":"macro","asOf":"2026-08-07T15:30:00+03:00","license":"","cached":false,"data":[{"date":"2026-07-01","value":1124.35}]}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"examples":{"missing":{"summary":"Missing key","value":{"success":false,"error":"missing_api_key","message":"Provide X-API-Key or Authorization: Bearer apibir_\u2026"}},"invalid":{"summary":"Invalid key","value":{"success":false,"error":"invalid_api_key","message":"API key is invalid or revoked"}}}}}},"429":{"description":"Quota exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"success":false,"error":"quota_exceeded","message":"FX monthly quota exceeded"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key header, e.g. `apibir_\u2026`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Same key as `Authorization: Bearer apibir_\u2026`"}},"schemas":{"HealthResponse":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"db":{"type":"boolean"},"cache":{"type":"boolean"},"time":{"type":"string","format":"date-time"}}},"Envelope":{"type":"object","required":["success","source","asOf","data"],"properties":{"success":{"type":"boolean"},"source":{"type":"string"},"asOf":{"type":"string","format":"date-time"},"license":{"type":"string"},"cached":{"type":"boolean"},"data":{"description":"Endpoint-specific payload"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"missing_api_key"},"message":{"type":"string"}}},"FxRate":{"type":"object","properties":{"pair":{"type":"string","example":"USDTRY"},"buying":{"type":"number"},"selling":{"type":"number"}}},"FxRatesData":{"type":"array","items":{"$ref":"#\/components\/schemas\/FxRate"}},"HistoryPoint":{"type":"object","properties":{"date":{"type":"string","format":"date"},"value":{"type":"number"}}},"FxHistoryData":{"type":"array","items":{"$ref":"#\/components\/schemas\/HistoryPoint"}},"MacroSeriesItem":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"MacroCatalogData":{"type":"array","items":{"$ref":"#\/components\/schemas\/MacroSeriesItem"}},"MacroSeriesData":{"type":"array","items":{"$ref":"#\/components\/schemas\/HistoryPoint"}}}}}