Arcadia Downloads API

openapi: 3.2.0
info:
  description: Plug API
  title: Plug Downloads API
  version: 2.0.0
servers:
- url: https://api.arcadia.com
security:
- OAuth2: []
tags:
- name: Downloads
paths:
  /plug/downloads/csv:
    post:
      description: 'This endpoint will generate a CSV report based on the provided parameters.


        The `globalSearch` and `search` parameters reuse the search functionality

        for the list endpoints of the `entityType` specified:

        - Account and Statement Gap

        - Credential

        - File

        - Meter

        - Site

        - Statement


        The columns in the report will vary based on `entityType`.

        By default (if the `columns` parameter is not provided), all available fields will be included.

        The names of these columns can then be passed in the `columns` parameter for future

        reports to only include those fields.


        If `downloadMethod` is set to `IN_BROWSER`, use information in the response to make a request to the

        Get the DownloadRequest endpoint to retrieve the file.


        This endpoint supports Sandbox Mode.'
      operationId: create-a-csv-download-request
      parameters:
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicDownloadCSVRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDownloadRequestResource'
            text/csv:
              schema:
                $ref: '#/components/schemas/PublicDownloadRequestResource'
          description: Accepted
      summary: Create a CSV Download Request
      tags:
      - Downloads
      servers:
      - url: https://api.arcadia.com
      - url: https://sandbox.api.arcadia.com
  /plug/downloads/{downloadRequestWebhookId}:
    get:
      description: If you have the specific download request ID, this endpoint allows you to retrieve detailed information about the download request.
      operationId: get-the-downloadrequest
      parameters:
      - description: Create the input for this field by appending the token from the response of the first step to the end of the downloadId without any space
        in: path
        name: downloadRequestWebhookId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDownloadRequestResource'
            text/csv:
              schema:
                $ref: '#/components/schemas/PublicDownloadRequestResource'
          description: OK
      summary: Get the DownloadRequest
      tags:
      - Downloads
  /plug/downloads/{downloadRequestWebhookId}/source:
    get:
      description: 'Downloading a CSV file through the API is a 2 step process. The first step prepares the download and provides a URL in the response body that can be used for downloading the CSV file. The next step (this one) is to download the file using a GET request with the response body URL. With this endpoint, you can download the accounts, meters, statements or associated metadata when it is ready. The first step can be performed using any of the endpoints below.

        * Download Account Statements

        * Download Meter Usage

        * Download Sites'' Usage'
      operationId: stream-download
      parameters:
      - description: Create the input for this field by appending the token from the response of the first step to the end of the downloadId without any space
        in: path
        name: downloadRequestWebhookId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
            text/csv:
              schema:
                type: object
          description: OK
        '202':
          content:
            application/json:
              schema:
                type: object
            text/csv:
              schema:
                type: object
          description: Accepted
        '204':
          content:
            application/json:
              schema:
                type: object
            text/csv:
              schema:
                type: object
          description: No Content
      summary: Stream Download
      tags:
      - Downloads
components:
  schemas:
    PublicDownloadRequestResource:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: A timestamp indicating when the entity was created.
        downloadMethod:
          type: string
          description: Method used for downloading data.
          enum:
          - EMAIL
          - IN_BROWSER
        id:
          type: string
          description: A unique identifier for the entity.
        status:
          type: string
          description: Status of the resource.
          enum:
          - SUCCESS
          - PREPARING
          - FAILURE
          - NO_CONTENT
        token:
          type: string
          description: We require this token to be provided when you want to access the requested download file. If you made the request via an API call, this token can be found in our response to you. If you made the request via the Dashboard, this token already be included in the email we would send you.
      required:
      - createdAt
      - downloadMethod
      - id
      - status
      - token
    PublicDownloadCSVRequest:
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
        downloadMethod:
          type: string
          enum:
          - EMAIL
          - IN_BROWSER
        entityType:
          type: string
          enum:
          - CREDENTIAL
          - METER
          - STATEMENT
          - SITE
          - ACCOUNT
          - FILE
          - STATEMENT_GAP
          - DISCOVERED_STATEMENT
        globalSearch:
          type: string
        search:
          type: string
      required:
      - entityType
  parameters:
    arcVersionInHeaderParam:
      name: Arcadia-Version
      in: header
      example: '2024-02-21'
      description: The Arcadia-Version for the request
      required: true
      schema:
        type: string
        default: '2024-02-21'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: This API uses OAuth2 with the client credentials flow using the ['Create an Access Token'](ref:create-access-token) endpoint. API keys can be retrieved from the [Dashboard](https://dashboard.arcadia.com/).
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /oauth2/token
x-provenance:
  method: harvested
  publisher: Arcadia
  source: https://docs.arcadia.com/openapi/openapi.yaml
  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)