Arcadia Files API

Source documents (PDFs, etc.) for statements and other artifacts.

GitHub OpenAPI

Operations 8

GET /plug/files List Files #
POST /plug/files Add Files #
GET /plug/files/{fileId} Retrieve File #
PATCH /plug/files/{fileId} Update File #
GET /plug/files/{fileId}/counts Get the File's Count of Associated Account, Statement and Meter Resources #
GET /plug/files/{fileId}/events List File's Events #
DELETE /plug/files/{fileId}/resources Deletes File Along With its Accounts, Meters, and Statements Resources #
GET /plug/files/{fileId}/source Download File Source #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/arcadia-power:arcadia-power-files-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

arcadia-power-files-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  description: Plug API
  title: Plug Files API
  version: 2.0.0
servers:
- url: https://api.arcadia.com
security:
- OAuth2: []
tags:
- name: Files
paths:
  /plug/files:
    get:
      description: A file is a utility statement PDF uploaded for OCR processing on the Arcadia Platform. This endpoint allows you to get a list of all the files that are in the system. This endpoint is pageable.
      operationId: list-files
      parameters:
      - description: 'A search query string. See [this page](ref:searching) for more information.


          The searchable fields for this endpoint are:

          - `accountNumbers`

          - `businessUnitsIntersection.id`

          - `businessUnitsIntersection.name`

          - `businessUnitsUnion.id`

          - `businessUnitsUnion.name`

          - `correlationId`

          - `createdAt`

          - `discoveredStatementId`

          - `fileId`

          - `fileName`

          - `normalizedAccountNumbers`

          - `organizationId`

          - `provider.name`

          - `statementId`

          - `status`

          - `statusDetails`

          - `transferMethod`'
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: A global search query string. See [this page](ref:searching#global-search) for more information.
        in: query
        name: globalSearch
        required: false
        schema:
          type: string
      - description: Business Unit IDs to filter Files by.
        in: query
        name: businessUnitIds
        required: false
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicFileResource'
          description: OK
      summary: List Files
      tags:
      - Files
    post:
      description: This endpoint allows you to upload new files into the system. In order to add new files, they must be in PDF format. Multiple statements cannot be combined into a single file; each individual file must only contain one statement. The maximum number of files in an upload is 75, and the combined size of all files must be less than 1 GB.
      operationId: add-files
      parameters:
      - in: query
        name: providerId
        required: false
        schema:
          type: string
      - in: query
        name: correlationId
        required: false
        schema:
          type: string
      - in: query
        name: transferMethod
        required: false
        schema:
          type: string
          default: API
          enum:
          - CLIENT
          - API
          - EMAIL
          - SFTP
          - WEB_NAVIGATION_OCR
      - description: Business Unit IDs to assign to the file's Account, if newly created.
        in: query
        name: requestedBusinessUnitIds
        required: false
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
              required:
              - files
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionPublicFileResource'
          description: OK
      summary: Add Files
      tags:
      - Files
  /plug/files/{fileId}:
    get:
      description: This endpoint allows you to view the details of a particular file.
      operationId: retrieve-file
      parameters:
      - in: path
        name: fileId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicFileResource'
          description: OK
      summary: Retrieve File
      tags:
      - Files
    patch:
      description: To update a file, make a PATCH call to the files endpoint with a specific fileId. Currently only correlationId can be updated.
      operationId: update-file
      parameters:
      - in: path
        name: fileId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicUpdateFileRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicFileResource'
          description: OK
      summary: Update File
      tags:
      - Files
  /plug/files/{fileId}/counts:
    get:
      description: This endpoint returns the count of Accounts, Meters and Statements that was obtained by a specific file.
      operationId: get-the-files-count-of-associated-account-statement-and-meter-resources
      parameters:
      - in: path
        name: fileId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAssociatedEntitiesCountResource'
          description: OK
      summary: Get the File's Count of Associated Account, Statement and Meter Resources
      tags:
      - Files
  /plug/files/{fileId}/events:
    get:
      description: This endpoint allows you to view the event history for a file. For example, you can query this endpoint to find out when a file was created and who it was created by. This endpoint is pageable.
      operationId: list-files-events
      parameters:
      - in: path
        name: fileId
        required: true
        schema:
          type: string
      - description: 'A search query string. See [this page](ref:searching) for more information.


          The searchable fields for this endpoint are:

          - `createdAt`

          - `eventType`

          - `fieldName`'
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicFileEventResource'
          description: OK
      summary: List File's Events
      tags:
      - Files
  /plug/files/{fileId}/resources:
    delete:
      description: Once completed, this File and its associated Accounts, Meters, and Statements resources will be deleted and cannot be recovered. After completion, you can check the status of deletion by using the Deletion Log ID from the response body and call this endpoint.
      operationId: deletes-file-along-with-its-accounts-meters-and-statements-resources
      parameters:
      - in: path
        name: fileId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDeletionLogResource'
          description: OK
      summary: Deletes File Along With its Accounts, Meters, and Statements Resources
      tags:
      - Files
  /plug/files/{fileId}/source:
    get:
      description: This endpoint allows you to retrieve the source PDF for a specific file.
      operationId: download-file-source
      parameters:
      - in: path
        name: fileId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            '*/*':
              schema:
                type: string
                format: binary
          description: OK
        '204':
          description: No Content
      summary: Download File Source
      tags:
      - Files
components:
  schemas:
    PagedPublicFileEventResource:
      type: object
      properties:
        fileEvents:
          type: array
          description: Events associated with the file, such as when the value of a field changes etc.
          items:
            $ref: '#/components/schemas/PublicFileEventResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
      required:
      - fileEvents
      - page
    PublicProviderResource:
      type:
      - object
      - 'null'
      description: The entity providing service and issuing bills (informally known as a utility).
      properties:
        country:
          type:
          - string
          - 'null'
          description: The country associated with the billing address.
        id:
          type: string
          description: A unique identifier for the entity.
        intervalServiceTypes:
          type: array
          description: List of interval service types supported by this provider (e.g., ['electric', 'gas'])
          items:
            type: string
            description: List of interval service types supported by this provider (e.g., ['electric', 'gas'])
            enum:
            - ELECTRIC
            - GAS
          uniqueItems: true
        isIntervalDataSupported:
          type:
          - boolean
          - 'null'
          description: Indicates whether the provider supports interval data
        isIntervalFileUploadSupported:
          type:
          - boolean
          - 'null'
          description: Indicates whether the provider supports interval file upload
        isRealTimeCredentialValidationSupported:
          type: boolean
          description: Indicates whether the provider supports credential validation
        name:
          type:
          - string
          - 'null'
          description: The name of the utility service provider.
      required:
      - country
      - id
      - intervalServiceTypes
      - isIntervalDataSupported
      - isIntervalFileUploadSupported
      - isRealTimeCredentialValidationSupported
      - name
    PublicDeletionLogResource:
      type: object
      properties:
        accountCount:
          type: integer
          format: int32
          description: 'The number of accounts. Note: if this is 0, but the entity being deleted has associated accounts, those accounts will be unlinked from the deleted entity but remain in the system. This is because the accounts are associated with another file or credential that is not being deleted.'
        createdAt:
          type: string
          format: date-time
          description: A timestamp indicating when the entity was created.
        createdBy:
          type:
          - string
          - 'null'
          description: User or system responsible for creating the entity.
        deletionTargetId:
          type: string
          description: The ID of the primary resource being deleted. May belong to an Account, Credential, File or Site.
        fileCount:
          type: integer
          format: int32
          description: The total number of files that are requested to be deleted.
        id:
          type: string
          description: A unique identifier for the entity.
        meterCount:
          type: integer
          format: int32
          description: The total number of meters associated with the account.
        siteCount:
          type: integer
          format: int32
          description: The total number of Sites.
        statementCount:
          type: integer
          format: int32
          description: The total number of statements.
        status:
          type: string
          description: Status of the resource.
          enum:
          - REQUESTED
          - SCHEDULED
          - SUCCESS
          - FAILURE
      required:
      - accountCount
      - createdAt
      - createdBy
      - deletionTargetId
      - fileCount
      - id
      - meterCount
      - siteCount
      - statementCount
      - status
    CollectionPublicFileResource:
      type: object
      properties:
        files:
          type: array
          description: An array of file objects representing what you submitted to Arcadia.
          items:
            $ref: '#/components/schemas/PublicFileResource'
      required:
      - files
    PublicAssociatedEntitiesCountResource:
      type: object
      properties:
        accountCount:
          type: integer
          format: int32
          description: The number of accounts.
        meterCount:
          type: integer
          format: int32
          description: The total number of meters associated with the account.
        statementCount:
          type: integer
          format: int32
          description: The total number of statements.
      required:
      - accountCount
      - meterCount
      - statementCount
    PublicFileResource:
      type: object
      description: An array of file objects representing what you submitted to Arcadia.
      properties:
        accountNumbers:
          type: array
          description: An array of account identifiers provided by the commodity provider (often times the bill publisher).
          items:
            type: string
            description: An array of account identifiers provided by the commodity provider (often times the bill publisher).
        businessUnitsIntersection:
          type: array
          description: Intersection of Business Units across Accounts on the linked Statement, when present.
          items:
            $ref: '#/components/schemas/PublicBusinessUnitResource'
        businessUnitsUnion:
          type: array
          description: Union of Business Units from Accounts on the linked Statement, when present.
          items:
            $ref: '#/components/schemas/PublicBusinessUnitResource'
        correlationId:
          type:
          - string
          - 'null'
          description: A string value you can set to help you reconcile with your internal systems.
        createdAt:
          type: string
          format: date-time
          description: A timestamp indicating when the entity was created.
        createdBy:
          type: string
          description: User or system responsible for creating the entity.
        discoveredStatementId:
          type:
          - string
          - 'null'
          description: The unique identifier for the discovered statement in the Arcadia platform.
        fileName:
          type: string
          description: The name of the file when it was originally submitted.
        id:
          type: string
          description: A unique identifier for the entity.
        isCustomerActionRequired:
          type: boolean
          description: Indicates whether any action is required from you regarding this resource.
        lastModifiedAt:
          type: string
          format: date-time
          description: The timestamp indicating when this resource was last modified.
        provider:
          $ref: '#/components/schemas/PublicProviderResource'
        statementDate:
          type:
          - string
          - 'null'
          format: date
          description: The date of the statement.
        statementId:
          type:
          - string
          - 'null'
          description: The unique identifier of a statement.
        status:
          type: string
          description: Status of the resource.
          enum:
          - QUEUED
          - FAILURE
          - IN_PROGRESS
          - COVERAGE_REQUEST
          - SUCCESS
        statusDetails:
          type: array
          description: 'Reasons the resource has the current status. '
          items:
            type: string
            description: 'Reasons the resource has the current status. '
            enum:
            - READY_FOR_PROCESSING
            - PROVIDER_UNIDENTIFIABLE
            - SERVICE_TYPE_NOT_SUPPORTED
            - LANGUAGE_NOT_SUPPORTED
            - REQUIRED_DATA_FIELDS_MISSING
            - BILL_INSUFFICIENTLY_LEGIBLE
            - TIMED_OUT
            - IDENTIFYING_PROVIDER
            - BILL_ANOMALY_FLAGGED
            - DATA_EXTRACTION_FAILURE_INVESTIGATION_STARTED
            - DATA_AUDIT_FAILURE_INVESTIGATION_STARTED
            - REQUEST_CREATED
            - IN_PROGRESS
            - DATA_EXTRACTION_SUCCESSFUL
            - CONTAINS_MULTIPLE_STATEMENTS
        transferMethod:
          type: string
          description: Indicates the method you used to send data to us.
          enum:
          - CLIENT
          - API
          - EMAIL
          - SFTP
          - WEB_NAVIGATION_OCR
      required:
      - accountNumbers
      - businessUnitsIntersection
      - businessUnitsUnion
      - correlationId
      - createdAt
      - createdBy
      - discoveredStatementId
      - fileName
      - id
      - isCustomerActionRequired
      - lastModifiedAt
      - provider
      - statementDate
      - statementId
      - status
      - statusDetails
      - transferMethod
    PublicBusinessUnitResource:
      type: object
      description: A business unit assignment.
      properties:
        id:
          type: string
          description: Business unit identifier.
          readOnly: true
        name:
          type:
          - string
          - 'null'
          description: Display name when visible to the caller.
      required:
      - id
      - name
    PageMetadata:
      required:
      - number
      - size
      - totalElements
      - totalPages
      type: object
      properties:
        number:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int64
      description: Specifies which page of results to return; this is 0-indexed
    PublicFileEventResource:
      type: object
      description: Events associated with the file, such as when the value of a field changes etc.
      properties:
        createdAt:
          type: string
          format: date-time
          description: The date-time this event occurred.
        createdBy:
          type: string
          description: The user or system that initiated the event.
        eventType:
          type: string
          description: The type of event that occurred.
          enum:
          - FILE_CREATED
          - FILE_STATUS_UPDATED
          - FILE_STATUS_DETAIL_UPDATED
          - FILE_UPDATED
          - FILE_BUSINESS_UNIT_ASSIGNMENT_FAILURE
        fieldName:
          type:
          - string
          - 'null'
          description: Represents the field which was modified.
        id:
          type: string
          description: A unique identifier for the event.
        newValue:
          type:
          - string
          - 'null'
          description: Represents the newly assigned value of the field.
        oldValue:
          type:
          - string
          - 'null'
          description: Represents the previous value of the field.
      required:
      - createdAt
      - createdBy
      - eventType
      - fieldName
      - id
      - newValue
      - oldValue
    PublicUpdateFileRequest:
      type: object
      properties:
        correlationId:
          type: string
          description: A string value you can set to help you reconcile with your internal systems.
          maxLength: 255
          minLength: 0
    PagedPublicFileResource:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/PublicFileResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
      required:
      - files
      - page
  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)