openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Notifications (Current User) 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: Notifications (Current User)
  description: Notifications operations
paths:
  /api/v1/users/me/notifications:
    get:
      tags:
      - Notifications (Current User)
      summary: Get notifications
      parameters:
      - name: seen
        in: query
        required: false
        description: filter by seen notifications
        schema:
          type: string
          nullable: true
      - name: skip
        in: query
        required: false
        description: Number of records to skip
        schema:
          nullable: true
          type: number
      - name: take
        in: query
        required: false
        description: Number of records returned in response
        schema:
          nullable: true
          type: number
      - name: storeId
        in: query
        required: false
        description: Array of store ids to fetch the notifications for
        schema:
          type: array
          items:
            type: string
        example: '&storeId=ABCDE&storeId=FGHIJ'
      description: View current user's notifications
      operationId: Notifications_GetNotifications
      responses:
        '200':
          description: list of notifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationData'
        '403':
          description: If you are authenticated but forbidden to get the data
      security:
      - API_Key:
        - btcpay.user.canmanagenotificationsforuser
        - btcpay.user.canviewnotificationsforuser
        Basic: []
  /api/v1/users/me/notifications/{id}:
    get:
      tags:
      - Notifications (Current User)
      summary: Get notification
      parameters:
      - name: id
        in: path
        required: true
        description: The notification to fetch
        schema:
          type: string
      description: View information about the specified notification
      operationId: Notifications_GetNotification
      responses:
        '200':
          description: specified notification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationData'
        '403':
          description: If you are authenticated but forbidden to view the specified notification
        '404':
          description: The key is not found for this notification
      security:
      - API_Key:
        - btcpay.user.canmanagenotificationsforuser
        - btcpay.user.canviewnotificationsforuser
        Basic: []
    put:
      tags:
      - Notifications (Current User)
      summary: Update notification
      parameters:
      - name: id
        in: path
        required: true
        description: The notification to update
        schema:
          type: string
      description: Updates the notification
      operationId: Notifications_UpdateNotification
      responses:
        '200':
          description: updated notification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationData'
        '403':
          description: If you are authenticated but forbidden to update the specified notification
        '404':
          description: The key is not found for this notification
      security:
      - API_Key:
        - btcpay.user.canmanagenotificationsforuser
        Basic: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotification'
    delete:
      tags:
      - Notifications (Current User)
      summary: Remove Notification
      description: Removes the specified notification.
      operationId: Notifications_DeleteNotification
      parameters:
      - name: id
        in: path
        required: true
        description: The notification to remove
        schema:
          type: string
      responses:
        '200':
          description: The notification has been deleted
        '403':
          description: If you are authenticated but forbidden to remove the specified notification
        '404':
          description: The key is not found for this notification
      security:
      - API_Key:
        - btcpay.user.canmanagenotificationsforuser
        Basic: []
  /api/v1/users/me/notification-settings:
    get:
      tags:
      - Notifications (Current User)
      summary: Get notification settings
      description: View information about your notification settings
      operationId: Notifications_GetNotificationSettings
      responses:
        '200':
          description: The current user's notification settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSettingsData'
        '403':
          description: If you are authenticated but forbidden to view the notification settings
      security:
      - API_Key:
        - btcpay.user.canmanagenotificationsforuser
        Basic: []
    put:
      tags:
      - Notifications (Current User)
      summary: Update notification settings
      description: Updates the current user's notification settings
      operationId: Notifications_UpdateNotificationSettings
      responses:
        '200':
          description: The current user's notification settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSettingsData'
        '403':
          description: If you are authenticated but forbidden to update the notification settings
      security:
      - API_Key:
        - btcpay.user.canmanagenotificationsforuser
        Basic: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationSettingsRequest'
components:
  schemas:
    NotificationSettingsData:
      type: object
      additionalProperties: false
      properties:
        notifications:
          type: array
          description: The notification types
          items:
            $ref: '#/components/schemas/NotificationSettingsItemData'
      example:
      - identifier: newversion
        name: New version
        enabled: false
      - identifier: newuserrequiresapproval
        name: New user requires approval
        enabled: true
      - identifier: inviteaccepted
        name: User accepted invitation
        enabled: true
      - identifier: pluginupdate
        name: Plugin update
        enabled: false
      - identifier: invoicestate
        name: All invoice updates
        enabled: true
      - identifier: invoicestate_invoice_paidAfterExpiration
        name: Invoice was paid after expiration
        enabled: true
      - identifier: invoicestate_invoice_expiredPaidPartial
        name: Invoice expired with partial payments
        enabled: true
      - identifier: invoicestate_invoice_failedToConfirm
        name: Invoice has payments that failed to confirm on time
        enabled: true
      - identifier: invoicestate_invoice_confirmed
        name: Invoice is settled
        enabled: true
      - identifier: payout
        name: Payouts
        enabled: true
      - identifier: external-payout-transaction
        name: External payout approval
        enabled: true
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    UpdateNotification:
      type: object
      additionalProperties: false
      properties:
        seen:
          type: boolean
          nullable: true
          description: Sets the notification as seen/unseen. If left null, sets it to the opposite value
    NotificationData:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: The id of the notification
        identifier:
          type: string
          description: The identifier of the notification
        type:
          type: string
          description: The type of the notification
        body:
          type: string
          format: html
          description: The html body of the notifications
        storeId:
          allOf:
          - $ref: '#/components/schemas/StoreId'
          type: string
          nullable: true
          description: If related to a store, the store id of the notification
        link:
          type: string
          format: uri
          nullable: true
          description: The link of the notification
        createdTime:
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
          description: The creation time of the notification
        seen:
          type: boolean
          description: If the notification has been seen by the user
    UpdateNotificationSettingsRequest:
      type: object
      additionalProperties: false
      properties:
        disabled:
          type: array
          items:
            type: string
          description: List of the notification type identifiers, which should be disabled. Can also be a single item 'all'.
          example:
          - newversion
          - pluginupdate
          nullable: false
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    NotificationSettingsItemData:
      type: object
      additionalProperties: false
      properties:
        identifier:
          type: string
          description: The identifier of the notification type
          nullable: false
        name:
          type: string
          description: The description of the notification type
          nullable: false
        enabled:
          type: boolean
          description: If the notification type is enabled
          nullable: false
      example:
        identifier: newversion
        name: New version
        enabled: false
  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/