{ "openapi": "3.1.0", "info": { "title": "RBA Exchange Rates API", "description": "Official Reserve Bank of Australia (RBA) exchange rate data through a modern REST API. Transforms publicly available RBA data into clean JSON endpoints for Australian businesses and developers who need reliable AUD exchange rates.", "version": "1.0.0", "license": { "name": "MIT" }, "contact": { "url": "https://www.exchangeratesapi.com.au" } }, "servers": [ { "url": "https://api.exchangeratesapi.com.au", "description": "Production API" } ], "paths": { "/": { "get": { "operationId": "getApiRoot", "summary": "API Root", "description": "Returns basic API information and documentation link", "responses": { "200": { "description": "API information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootResponse" }, "example": { "success": true, "message": "RBA Exchange Rates API", "documentation": "https://docs.exchangeratesapi.com.au", "version": "1.0.0" } } } } } } }, "/status": { "get": { "operationId": "getApiStatus", "summary": "API Status", "description": "Returns operational status of the API including last update time and data freshness", "responses": { "200": { "description": "API status information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" }, "example": { "status": "operational", "last_update": "2025-09-01T16:00:00Z", "stale": false, "next_update_expected": "2025-09-02T06:00:00Z" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } } } } }, "/symbols": { "get": { "operationId": "getSupportedCurrencies", "summary": "Supported Currencies", "description": "List all supported currencies with their names, symbols, and countries", "responses": { "200": { "description": "List of supported currencies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolsResponse" }, "example": { "success": true, "symbols": { "USD": { "name": "US Dollar", "symbol": "$", "country": "United States" }, "EUR": { "name": "Euro", "symbol": "€", "country": "European Union" } }, "count": 21, "base": "AUD", "note": "All rates are quoted as AUD per unit of foreign currency from the Reserve Bank of Australia" } } } } } } }, "/convert": { "get": { "operationId": "convertCurrency", "summary": "Currency Conversion", "description": "Convert amounts between currencies. Requires authentication. Free tier: 150, no historical data. Starter: 5,000/month, 30 days history. Professional: 50,000/month, full history. Business: 500,000/month, full history.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Source currency code", "schema": { "$ref": "#/components/schemas/CurrencyCode" }, "example": "AUD" }, { "name": "to", "in": "query", "required": true, "description": "Target currency code", "schema": { "$ref": "#/components/schemas/CurrencyCode" }, "example": "USD" }, { "name": "amount", "in": "query", "required": true, "description": "Amount to convert", "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "example": 100 }, { "name": "date", "in": "query", "required": false, "description": "Historical date for conversion (YYYY-MM-DD). Requires authentication.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2025-08-31" } ], "responses": { "200": { "description": "Conversion result", "headers": { "X-RateLimit-Limit-Monthly": { "description": "Monthly request limit based on plan (Free=150, Starter=5,000, Professional=50,000, Business=500,000)", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Monthly": { "description": "Remaining requests in current monthly period", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResponse" }, "example": { "success": true, "query": { "from": "AUD", "to": "USD", "amount": 100 }, "info": { "timestamp": 1725148800, "rate": 0.678234 }, "date": "2025-09-01", "result": 67.8234 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/latest": { "get": { "operationId": "getLatestRates", "summary": "Latest Exchange Rates", "description": "Get all current exchange rates from the Reserve Bank of Australia with optional filtering. Quota limits: Free=150 (one-time trial), Starter=5,000/month, Professional=50,000/month, Business=500,000/month.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "symbols", "in": "query", "required": false, "description": "Comma-separated list of currency codes to filter results", "schema": { "type": "string" }, "example": "USD,EUR,GBP" }, { "name": "base", "in": "query", "required": false, "description": "Base currency (currently only AUD supported)", "schema": { "type": "string", "enum": [ "AUD" ] }, "example": "AUD" } ], "responses": { "200": { "description": "Latest exchange rates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestRatesResponse" }, "example": { "success": true, "timestamp": 1725148800, "base": "AUD", "date": "2025-09-01", "rates": { "USD": 0.678234, "EUR": 0.612345, "GBP": 0.534567 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/latest/{currency}": { "get": { "operationId": "getLatestRateForCurrency", "summary": "Latest Rate for Currency", "description": "Get the current exchange rate for a specific currency. Quota limits: Free=150 (one-time trial), Starter=5,000/month, Professional=50,000/month, Business=500,000/month.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "currency", "in": "path", "required": true, "description": "Currency code", "schema": { "$ref": "#/components/schemas/CurrencyCode" }, "example": "USD" } ], "responses": { "200": { "description": "Latest exchange rate for currency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestRatesResponse" }, "example": { "success": true, "timestamp": 1725148800, "base": "AUD", "date": "2025-09-01", "rates": { "USD": 0.678234 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/timeseries": { "get": { "operationId": "getTimeseriesRates", "summary": "Historical Exchange Rates", "description": "Get exchange rates for a date range. Historical access: Free=blocked, Starter=30 days, Professional/Business=full history. Date range limits: Starter=7 days, Professional=90 days, Business=365 days.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": true, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2025-08-01" }, { "name": "end_date", "in": "query", "required": true, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2025-08-31" }, { "name": "symbols", "in": "query", "required": false, "description": "Comma-separated list of currency codes to filter", "schema": { "type": "string" }, "example": "USD,EUR,GBP" }, { "name": "base", "in": "query", "required": false, "description": "Base currency (currently only AUD supported)", "schema": { "type": "string", "enum": [ "AUD" ], "default": "AUD" } } ], "responses": { "200": { "description": "Historical exchange rates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeseriesResponse" }, "example": { "success": true, "timeseries": true, "start_date": "2025-08-01", "end_date": "2025-08-31", "base": "AUD", "rates": { "2025-08-01": { "USD": 0.678234, "EUR": 0.612345 }, "2025-08-02": { "USD": 0.679123, "EUR": 0.613456 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/{date}": { "get": { "operationId": "getHistoricalRatesForDate", "summary": "Historical Rates for Date", "description": "Get all exchange rates for a specific historical date. Historical access: Free=none, Starter=30 days, Professional/Business=full history (2018+).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "Date in YYYY-MM-DD format", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2025-08-31" } ], "responses": { "200": { "description": "Exchange rates for the specified date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestRatesResponse" }, "example": { "success": true, "timestamp": 1725062400, "base": "AUD", "date": "2025-08-31", "rates": { "USD": 0.678234, "EUR": 0.612345, "GBP": 0.534567 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/{date}/{currency}": { "get": { "operationId": "getHistoricalRateForCurrencyAndDate", "summary": "Historical Rate for Currency and Date", "description": "Get the exchange rate for a specific currency on a specific historical date. Historical access: Free=none, Starter=30 days, Professional/Business=full history (2018+).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "Date in YYYY-MM-DD format", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2025-08-31" }, { "name": "currency", "in": "path", "required": true, "description": "Currency code", "schema": { "$ref": "#/components/schemas/CurrencyCode" }, "example": "USD" } ], "responses": { "200": { "description": "Exchange rate for the specified currency and date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestRatesResponse" }, "example": { "success": true, "timestamp": 1725062400, "base": "AUD", "date": "2025-08-31", "rates": { "USD": 0.678234 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/webhook-subscriptions": { "servers": [ { "url": "https://auth.exchangeratesapi.com.au", "description": "Auth/account host" } ], "post": { "operationId": "createWebhookSubscription", "summary": "Create Webhook Subscription", "description": "Create a webhook subscription (Professional plan or higher). Returns the signing secret once. Authenticate with your Bearer API key (or manage from your dashboard).", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint to receive deliveries. Public host only (no localhost/private IPs)." }, "currencies": { "type": "array", "items": { "type": "string" }, "description": "Optional list of currency codes to receive. Omit for all currencies." }, "description": { "type": "string", "description": "Optional label." } } }, "example": { "url": "https://hooks.example.com/rba", "currencies": [ "USD", "JPY" ], "description": "Prod hook" } } } }, "responses": { "200": { "description": "Subscription created", "content": { "application/json": { "example": { "success": true, "signingSecret": "3f9c4e2a1b7d8f60a5c3e1d9b2f4a6c83f9c4e2a1b7d8f60a5c3e1d9b2f4a6c8", "warning": "Store this signing secret securely. It will not be shown again.", "subscription": { "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "url": "https://hooks.example.com/rba", "currencies": [ "USD", "JPY" ], "description": "Prod hook" } } } } }, "400": { "description": "Invalid url or currencies" }, "401": { "description": "Missing or invalid API key (or dashboard session)" }, "403": { "description": "Plan does not include webhooks, or subscription limit reached" } } }, "get": { "operationId": "listWebhookSubscriptions", "summary": "List Webhook Subscriptions", "description": "List your webhook subscriptions. The signing secret is never returned.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Subscriptions", "content": { "application/json": { "example": { "success": true, "subscriptions": [ { "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "url": "https://hooks.example.com/rba", "currencies": [ "USD", "JPY" ], "description": "Prod hook", "isActive": true, "failureCount": 0, "lastSuccessAt": "2026-06-23T07:00:20.000Z", "createdAt": "2026-06-20T01:00:00Z" } ], "limit": 3 } } } }, "401": { "description": "Missing or invalid API key (or dashboard session)" } } } }, "/api/webhook-subscriptions/{id}": { "servers": [ { "url": "https://auth.exchangeratesapi.com.au", "description": "Auth/account host" } ], "delete": { "operationId": "deleteWebhookSubscription", "summary": "Delete Webhook Subscription", "description": "Delete one of your webhook subscriptions.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "example": { "success": true, "message": "Webhook deleted" } } } }, "401": { "description": "Missing or invalid API key (or dashboard session)" }, "404": { "description": "Not found or not owned by you" } } } }, "/api/webhook-subscriptions/{id}/test": { "servers": [ { "url": "https://auth.exchangeratesapi.com.au", "description": "Auth/account host" } ], "post": { "operationId": "testWebhookSubscription", "summary": "Send Test Webhook", "description": "Send a sample rates.test delivery to the subscription's URL so you can verify your endpoint and signature handling.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test attempted", "content": { "application/json": { "example": { "success": true, "responseStatus": 200, "message": "Test delivered" } } } }, "401": { "description": "Missing or invalid API key (or dashboard session)" }, "404": { "description": "Not found or not owned by you" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key authentication using Bearer token" } }, "schemas": { "CurrencyCode": { "type": "string", "enum": [ "AUD", "USD", "EUR", "GBP", "JPY", "CNY", "KRW", "INR", "SGD", "NZD", "THB", "MYR", "IDR", "VND", "HKD", "PHP", "CAD", "CHF", "TWD", "TWI", "SDR" ], "description": "Three-letter currency code" }, "CurrencyInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the currency" }, "symbol": { "type": "string", "description": "Currency symbol" }, "country": { "type": "string", "description": "Country or region" } }, "required": [ "name", "symbol", "country" ] }, "RatesObject": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "description": "Exchange rate (AUD per unit of foreign currency) with precision varying by currency (up to 6 decimal places for most, whole numbers for IDR/VND as provided by RBA)" }, "description": "Object containing currency codes as keys and exchange rates as values" }, "RootResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "documentation": { "type": "string", "format": "uri" }, "version": { "type": "string" } }, "required": [ "success", "message", "documentation", "version" ] }, "StatusResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational", "degraded" ], "description": "Current API status" }, "last_update": { "type": "string", "description": "Last successful data update timestamp or 'unknown'" }, "stale": { "type": "boolean", "description": "Whether the data is considered stale" }, "next_update_expected": { "type": "string", "description": "ISO 8601 timestamp of when next RBA update is expected" } }, "required": [ "status", "last_update", "stale", "next_update_expected" ] }, "SymbolsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "symbols": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CurrencyInfo" } }, "count": { "type": "integer", "description": "Number of supported currencies" }, "base": { "type": "string", "example": "AUD" }, "note": { "type": "string" } }, "required": [ "success", "symbols", "count", "base", "note" ] }, "LatestRatesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "timestamp": { "type": "integer", "description": "Unix timestamp of the rate date" }, "base": { "type": "string", "example": "AUD" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of the rates (YYYY-MM-DD)" }, "rates": { "$ref": "#/components/schemas/RatesObject" } }, "required": [ "success", "timestamp", "base", "date", "rates" ] }, "ConvertResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "query": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "from", "to", "amount" ] }, "info": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp of the rate date" }, "rate": { "type": "number", "description": "Exchange rate used for conversion with precision varying by currency (up to 6 decimal places for most, whole numbers for IDR/VND as provided by RBA)" } }, "required": [ "rate" ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "result": { "type": "number", "description": "Conversion result" } }, "required": [ "success", "query", "info", "date", "result" ] }, "TimeseriesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "timeseries": { "type": "boolean", "example": true }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "base": { "type": "string", "example": "AUD" }, "rates": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RatesObject" }, "description": "Object with dates as keys and rate objects as values" } }, "required": [ "success", "timeseries", "start_date", "end_date", "base", "rates" ] }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "HTTP status code" }, "type": { "type": "string", "description": "Error type identifier" }, "info": { "type": "string", "description": "Human-readable error description" } }, "required": [ "code", "type", "info" ] } }, "required": [ "success", "error" ] } }, "responses": { "BadRequest": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": 400, "type": "bad_request", "info": "Invalid currency format. Use 3-letter currency code (e.g., USD)" } } } } }, "Unauthorized": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": 401, "type": "unauthorized", "info": "Invalid or missing API key" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": 404, "type": "not_found", "info": "No data available for the specified date" } } } } }, "RateLimitExceeded": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": 429, "type": "rate_limit", "info": "Quota exceeded. Free=150 (one-time trial), Starter=5,000/month, Professional=50,000/month, Business=500,000/month." } } } } }, "ServiceUnavailable": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": 503, "type": "unavailable", "info": "Rates temporarily unavailable" } } } } }, "MethodNotAllowed": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": 405, "type": "method_not_allowed", "info": "Method POST not allowed. Only GET, HEAD, and OPTIONS are supported." } } } } } } } }