openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Miscelleneous API
  version: v1
  description: "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n"
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: Miscelleneous
  description: Miscelleneous operations
paths:
  /misc/rate-sources:
    get:
      tags:
      - Miscelleneous
      summary: Get available rate sources
      description: View available rate providers that you can use in stores
      operationId: GetRateSources
      responses:
        '200':
          description: rate providers array
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    id:
                      type: string
                      description: The id of the rate provider
                    name:
                      type: string
                      description: The name of the rate provider
        '403':
          description: If you are authenticated but forbidden to get the data
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security: []
  /misc/permissions:
    get:
      tags:
      - Miscelleneous
      summary: Permissions metadata
      description: The metadata of available permissions
      operationId: permissionsMetadata
      responses:
        '200':
          description: The metadata of available permissions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The permission id
                      nullable: false
                    included:
                      type: array
                      description: Permissions included in this array are also granted by this permission
                      nullable: false
                      items:
                        type: string
        '403':
          description: If you are authenticated but forbidden to get the data
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security: []
  /misc/lang:
    get:
      tags:
      - Miscelleneous
      summary: Language codes
      description: The supported language codes
      operationId: langCodes
      responses:
        '200':
          description: The supported language codes
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: The language code
                      nullable: false
                    currentLanguage:
                      type: string
                      description: The language name
                      nullable: false
        '403':
          description: If you are authenticated but forbidden to get the data
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security: []
  /i/{invoiceId}:
    parameters:
    - $ref: '#/components/parameters/InvoiceId'
    - name: lang
      in: query
      required: false
      description: The preferred language of the checkout page. You can use "auto" to use the language of the customer's browser or see the list of language codes with [this operation](#operation/langCodes).
      schema:
        type: string
    get:
      tags:
      - Miscelleneous
      operationId: Invoice_Checkout
      summary: Invoice checkout
      description: View the checkout page of an invoice
      responses:
        '200':
          description: The checkout page
          content:
            text/html:
              example: The HTML checkout page of the invoice
        '404':
          description: The invoice could not be found
      security: []
components:
  parameters:
    InvoiceId:
      name: invoiceId
      in: path
      required: true
      description: The invoice ID
      schema:
        $ref: '#/components/schemas/InvoiceId'
  schemas:
    InvoiceId:
      type: string
      description: The invoice ID
      example: HMprBnL9BTXWuPvpoKBS6e
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          nullable: false
          description: An error code describing the error
        message:
          type: string
          nullable: false
          description: User friendly error message about the error
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/