openapi: 3.0.0
info:
  title: Exchange Rate API
  description: >-
    Complete collection for the Exchange Rate API - Access real-time currency
    exchange rates.


    ## Features

    - Real-time exchange rates

    - Complete currency matrix for all supported currencies

    - Multiple currency pair support

    - Batch queries for multiple pairs


    ## Authentication

    All requests require an API key in the `x-api-co-id` header.


    ## Base URL

    - Production: `https://use.api.co.id`
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Exchange Rates
    description: Endpoints for accessing exchange rate data.
paths:
  /api/exchange-rates:
    get:
      tags:
        - Exchange Rates
      summary: List All Exchange Rates
      description: Get complete currency matrix with all exchange rates. Returns all possible currency pairs, alphabetically sorted by base currency.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      responses:
        '200':
          description: Successful response - All exchange rates
          content:
            application/json:
              examples:
                success:
                  summary: Success - All Exchange Rates
                  value:
                    success: true
                    updated_at: 1763461822000
                    rates:
                      - base: IDR
                        rates:
                          AED: 0.00021941
                          AUD: 0.00009185
                          CAD: 0.00008381
                          CHF: 0.00004759
                          CNY: 0.00042474
                          EUR: 0.00005155
                          GBP: 0.00004544
                          INR: 0.00528973
                          JPY: 0.00927646
                          KRW: 0.08742593
                          MYR: 0.00024851
                          PHP: 0.00351643
                          SAR: 0.00022403
                          SGD: 0.00007779
                          THB: 0.00193489
                          USD: 0.00005974
                      - base: MYR
                        rates:
                          AED: 0.88290865
                          AUD: 0.36961538
                          CAD: 0.33723558
                          CHF: 0.19149038
                          CNY: 1.70915865
                          EUR: 0.20742788
                          GBP: 0.18286058
                          IDR: 4024.03846154
                          INR: 21.28605769
                          JPY: 37.32884615
                          KRW: 351.80528846
                          PHP: 14.15024038
                          SAR: 0.90149038
                          SGD: 0.31302885
                          THB: 7.78605769
                          USD: 0.24038462
                      - base: USD
                        rates:
                          AED: 3.6729
                          AUD: 1.5376
                          CAD: 1.4029
                          CHF: 0.7966
                          CNY: 7.1101
                          EUR: 0.8629
                          GBP: 0.7607
                          IDR: 16740
                          INR: 88.55
                          JPY: 155.288
                          KRW: 1463.51
                          MYR: 4.16
                          PHP: 58.865
                          SAR: 3.7502
                          SGD: 1.3022
                          THB: 32.39
                    last_data_updated_at: 1732178872000
  /currency/:currency:
    get:
      tags:
        - Exchange Rates
      summary: Get Rates by Currency
      description: Get all exchange rates for a specific base currency. Returns rates to all available currencies.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: currency
          in: path
          required: true
          schema:
            type: string
          description: Base currency code (3 characters, case insensitive, e.g., USD, EUR, IDR)
          example: USD
      responses:
        '200':
          description: Successful response - Rates for currency
          content:
            application/json:
              examples:
                usd_rates:
                  summary: Success - USD Rates
                  value:
                    is_success: true
                    message: Success
                    data:
                      currency: USD
                      updated_at: 1732178872000
                      rates:
                        AED: 3.6729
                        AUD: 1.5376
                        CAD: 1.4029
                        CHF: 0.7966
                        CNY: 7.1101
                        EUR: 0.8629
                        GBP: 0.7607
                        IDR: 16740
                        INR: 88.55
                        JPY: 155.288
                        KRW: 1463.51
                        MYR: 4.16
                        PHP: 58.865
                        SAR: 3.7502
                        SGD: 1.3022
                        THB: 32.39
                    last_data_updated_at: 1732178872000
                idr_rates:
                  summary: Success - IDR Rates
                  value:
                    is_success: true
                    message: Success
                    data:
                      currency: IDR
                      updated_at: 1732178872000
                      rates:
                        AED: 0.00021941
                        AUD: 0.00009185
                        CAD: 0.00008381
                        CHF: 0.00004759
                        CNY: 0.00042474
                        EUR: 0.00005155
                        GBP: 0.00004544
                        INR: 0.00528973
                        JPY: 0.00927646
                        KRW: 0.08742593
                        MYR: 0.00024851
                        PHP: 0.00351643
                        SAR: 0.00022403
                        SGD: 0.00007779
                        THB: 0.00193489
                        USD: 0.00005974
                    last_data_updated_at: 1732178872000
        '404':
          description: Not Found - Currency not found
          content:
            application/json:
              examples:
                currency_not_found:
                  summary: Error - Currency Not Found
                  value:
                    is_success: false
                    message: 'no rates found for currency: XYZ'
                    errors: ''
  /currency/exchange-rate:
    get:
      tags:
        - Exchange Rates
      summary: Get Rates by Multiple Pairs
      description: 'Get exchange rates for single or multiple currency pairs in a single request. Supports comma-separated pair symbols (e.g., USDIDR or USDIDR,EURIDR,MYRIDR). Maximum recommended: 10 pairs per request.'
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: pair
          in: query
          required: true
          schema:
            type: string
          description: Currency pair symbol(s). Single pair (e.g., USDIDR) or comma-separated multiple pairs (e.g., USDIDR,EURIDR,MYRIDR)
          example: USDIDR,EURIDR,MYRIDR
      responses:
        '200':
          description: Successful response - Exchange rates for pair(s)
          content:
            application/json:
              examples:
                single_pair:
                  summary: Success - Single Pair (USDIDR)
                  value:
                    is_success: true
                    message: Success
                    data:
                      pair: USDIDR
                      updated_at: 1732178872000
                      rate: 16740
                    last_data_updated_at: 1732178872000
                multiple_pairs:
                  summary: Success - Multiple Pairs
                  value:
                    is_success: true
                    message: Success
                    data:
                      exchange_rates:
                        - pair: USDIDR
                          updated_at: 1732178872000
                          rate: 16740
                        - pair: EURIDR
                          updated_at: 1732178872000
                          rate: 19399.69869046
                        - pair: MYRIDR
                          updated_at: 1732178872000
                          rate: 4024.03846154
                    last_data_updated_at: 1732178872000
        '400':
          description: Bad Request - Missing pair parameter
          content:
            application/json:
              examples:
                missing_pair:
                  summary: Error - Missing Pair Parameter
                  value:
                    is_success: false
                    message: 'Pair query parameter is required (e.g., ?pair=USDIDR or ?pair=USDIDR,EURIDR)'
                    errors: ''
        '404':
          description: Not Found - Pair not found
          content:
            application/json:
              examples:
                pair_not_found:
                  summary: Error - Pair Not Found
                  value:
                    is_success: false
                    message: 'exchange rate not found for pair: INVALID'
                    errors: ''
