BTCPay Server Files API

openapi: 3.2.0
info:
  title: BTCPay Greenfield Files API
  version: v1
  description: '# Introduction


    The 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.


    # Authentication


    You 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`.


    If you want to simplify the process of creating API keys for your users, you can use the Authorization endpoint 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 page.


    # Usage examples


    Use **Basic Auth** to read store information with cURL:

    ```bash

    BTCPAY_INSTANCE="https://mainnet.demo.btcpayserver.org"

    USER="MyTestUser@gmail.com"

    PASSWORD="notverysecurepassword"

    PERMISSION="btcpay.store.canmodifystoresettings"

    BODY="$(echo "{}" | jq --arg "a" "$PERMISSION" ''. + {permissions:[$a]}'')"


    API_KEY="$(curl -s \

    -H "Content-Type: application/json" \

    --user "$USER:$PASSWORD" \

    -X POST \

    -d "$BODY" \

    "$BTCPAY_INSTANCE/api/v1/api-keys" | jq -r .apiKey)"

    ```


    Use an **API key** to read store information with cURL:

    ```bash

    STORE_ID="yourStoreId"


    curl -s \

    -H "Content-Type: application/json" \

    -H "Authorization: token $API_KEY" \

    -X GET \

    "$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID"

    ```


    You can find more examples on our docs for different programming languages:

    - cURL

    - Javascript/Node.Js

    - PHP'
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: /
  description: BTCPay Server Greenfield API
security:
- API_Key: []
  Basic: []
tags:
- name: Files
  description: File operations
paths:
  /api/v1/files:
    get:
      operationId: Files_GetFiles
      tags:
      - Files
      summary: Get all files
      description: Load all files that exist.
      parameters: []
      responses:
        '200':
          description: Files found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileData'
        '401':
          description: Missing authorization for loading the files
      security:
      - API_Key:
        - btcpay.server.canmodifyserversettings
        Basic: []
    post:
      tags:
      - Files
      summary: Uploads a file
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              properties:
                file:
                  type: string
                  description: The profile picture
                  format: binary
      operationId: Files_UploadFile
      responses:
        '200':
          description: Uploads a file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileData'
        '415':
          description: The upload did not work
      security:
      - API_Key:
        - btcpay.server.canmodifyserversettings
        Basic: []
  /api/v1/files/{fileId}:
    get:
      operationId: Files_GetFile
      tags:
      - Files
      summary: Get file
      description: View information about the specified file
      parameters:
      - name: fileId
        in: path
        required: true
        description: The file information to fetch
        schema:
          type: string
      responses:
        '200':
          description: File found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileData'
        '401':
          description: Missing authorization for loading the file
      security:
      - API_Key:
        - btcpay.server.canmodifyserversettings
        Basic: []
    delete:
      tags:
      - Files
      summary: Delete file
      description: Deletes the file
      operationId: Files_DeleteFile
      parameters:
      - name: fileId
        in: path
        required: true
        description: The file to delete
        schema:
          type: string
      responses:
        '200':
          description: File deleted successfully
        '404':
          description: The file could not be found
      security:
      - API_Key:
        - btcpay.server.canmodifyserversettings
        Basic: []
components:
  schemas:
    FileData:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: The id of the file
        userId:
          type: string
          description: The id of the user that uploaded the file
        uri:
          type: string
          description: The internal URI of the file
        url:
          type:
          - string
          - 'null'
          description: The full URL of the file
        originalName:
          type:
          - string
          - 'null'
          description: The original name of the file
        storageName:
          type:
          - string
          - 'null'
          description: The storage name of the file
        created:
          type:
          - number
          - 'null'
          description: The creation date of the file as a unix timestamp
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
  securitySchemes:
    API_Key:
      type: apiKey
      description: "BTCPay Server supports authenticating and authorizing users through an API Key that is generated by them. Send the API Key as a header value to Authorization with the format: `token {token}`. For a smoother experience, you can generate a url that redirects users to an API key creation screen.\n\n The following permissions are available to the context of the user creating the API Key:\n\n* `btcpay.impersonation.canimpersonate`: Can impersonate users\n* `btcpay.user.candeleteuser`: Delete user\n* `btcpay.user.canmanagenotificationsforuser`: Manage your notifications\n* `btcpay.user.canmodifyprofile`: Manage your profile\n* `btcpay.user.canviewnotificationsforuser`: View your notifications\n* `btcpay.user.canviewprofile`: View your profile\n* `unrestricted`: Unrestricted access\n\nThe following permissions are available if the user is an administrator:\n\n* `btcpay.server.cancreatelightninginvoiceinternalnode`: Create invoices with internal lightning node\n* `btcpay.server.cancreateuser`: Create new users\n* `btcpay.server.canmanageusers`: Manage users\n* `btcpay.server.canmodifyserversettings`: Manage your server\n* `btcpay.server.canuseinternallightningnode`: Use the internal lightning node\n* `btcpay.server.canviewlightninginvoiceinternalnode`: View invoices from internal lightning node\n* `btcpay.server.canviewusers`: View users\n\nThe following permissions applies to all stores of the user, you can limit to a specific store with the following format: `btcpay.store.cancreateinvoice:6HSHAEU4iYWtjxtyRs9KyPjM9GAQp8kw2T9VWbGG1FnZ`:\n\n* `btcpay.store.canarchivepullpayments`: Archive your pull payments\n* `btcpay.store.canbroadcasttransactions`: Broadcast wallet transactions\n* `btcpay.store.cancanceltransactions`: Cancel wallet transactions\n* `btcpay.store.cancreateinvoice`: Create an invoice\n* `btcpay.store.cancreatelightninginvoice`: Create invoices from the lightning nodes associated with your stores\n* `btcpay.store.cancreatenonapprovedpullpayments`: Create non-approved pull payments\n* `btcpay.store.cancreatepullpayments`: Create pull payments\n* `btcpay.store.cancreatetransactions`: Create wallet transactions\n* `btcpay.store.cancreditsubscribers`: Credit your subscribers\n* `btcpay.store.canmanageinvoicestatus`: Manage invoice status\n* `btcpay.store.canmanagelegacyaccesstokens`: Manage legacy access tokens\n* `btcpay.store.canmanagepayouts`: Manage payouts\n* `btcpay.store.canmanagepullpayments`: Manage your pull payments\n* `btcpay.store.canmanagesubscribers`: Manage your subscribers\n* `btcpay.store.canmanagewallets`: Manage wallets\n* `btcpay.store.canmanagewalletsettings`: Manage wallet settings\n* `btcpay.store.canmanagewallettransactions`: Manage wallet transactions\n* `btcpay.store.canmodifyinvoices`: Modify invoices\n* `btcpay.store.canmodifyofferings`: Modify your offerings\n* `btcpay.store.canmodifypaymentrequests`: Modify your payment requests\n* `btcpay.store.canmodifystoresettings`: Modify your stores\n* `btcpay.store.cansendstoreemails`: Send store emails\n* `btcpay.store.cansigntransactions`: Sign wallet transactions\n* `btcpay.store.canuselightningnode`: Use the lightning nodes associated with your stores\n* `btcpay.store.canviewinvoices`: View invoices\n* `btcpay.store.canviewlightninginvoice`: View the lightning invoices associated with your stores\n* `btcpay.store.canviewofferings`: View your offerings\n* `btcpay.store.canviewpaymentrequests`: View your payment requests\n* `btcpay.store.canviewpayouts`: View payouts\n* `btcpay.store.canviewpullpayments`: View your pull payments\n* `btcpay.store.canviewreports`: View your reports\n* `btcpay.store.canviewstoresettings`: View your stores\n* `btcpay.store.canviewwallet`: View wallets\n* `btcpay.store.webhooks.canmodifywebhooks`: Modify stores webhooks\n\nNote that API Keys only limits permission of a user and can never expand it. If an API Key has the permission `btcpay.server.canmodifyserversettings` but that the user account creating this API Key is not administrator, the API Key will not be able to modify the server settings.\nSome permissions may include other permissions, see [this operation](#operation/permissionsMetadata).\n"
      name: Authorization
      in: header
    Basic:
      type: http
      description: BTCPay Server supports authenticating and authorizing users through the Basic HTTP authentication scheme during the first five minutes after account creation or when the user explicitly enables it. Send the user and password encoded in base64 with the format `Basic {base64(username:password)}`. Using this authentication method implicitly provides you with the `unrestricted` permission
      scheme: Basic
externalDocs:
  description: BTCPay Greenfield Plugins API
  url: https://docs.btcpayserver.org/API/Greenfield/Plugins/
x-provenance:
  method: harvested
  publisher: BTCPay Server
  source: https://docs.btcpayserver.org/API/Greenfield/v1/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)