openapi: 3.1.0
servers:
  - description: Production
    url: 'https://api.codat.io'
info:
  title: Files API
  description: |-
    An API for uploading and downloading files from 'File Upload' Integrations.

    The Accounting file upload, Banking file upload, and Business documents file upload integrations provide simple file upload functionality.

    [Read more...](https://docs.codat.io/other/file-upload)

    [See our OpenAPI spec](https://github.com/codatio/oas) 
  version: 2.1.0
  contact:
    name: Codat
    email: support@codat.io
  termsOfService: 'https://www.codat.io/legals/'
security:
  - auth_header: []
tags:
  - name: Files
    description: Endpoints to manage uploaded files.
paths:
  '/companies/{companyId}/connections/{connectionId}/files':
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    post:
      tags:
        - Files
      summary: Upload files for a company
      responses:
        '200':
          description: Success
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: string
              format: binary
      description: Upload files
      operationId: upload-files
  '/companies/{companyId}/files':
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      tags:
        - Files
      summary: List all files uploaded by a company
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Files'
      description: Returns an array of files that have been uploaded for a given company.
      operationId: list-files
  '/companies/{companyId}/files/download':
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      tags:
        - Files
      summary: Download all files for a company
      parameters:
        - name: date
          in: query
          schema:
            $ref: '#/components/schemas/DateTime'
          description: Only download files uploaded on this date
      responses:
        '200':
          description: Success
          content:
            application/octet-stream:
              schema:
                title: Data
                type: string
                format: binary
      description: You can specify a date to download specific files for.
      operationId: download-files
components:
  schemas:
    DateTime:
      title: Date time
      type: string
      example: '2022-10-23T00:00:00Z'
      description: |-
        In Codat's data model, dates and times are represented using the <a class="external" href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 standard</a>. Date and time fields are formatted as strings; for example:

        ```
        2020-10-08T22:40:50Z
        2021-01-01T00:00:00
        ```



        When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:

        - Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`
        - Unqualified local time: `2021-11-15T01:00:00`
        - UTC time offsets: `2021-11-15T01:00:00-05:00`

        > Time zones
        > 
        > Not all dates from Codat will contain information about time zones.  
        > Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced.
    File:
      title: File
      type: object
      properties:
        fileName:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
        sourceType:
          type: string
          nullable: true
        uploaded:
          $ref: '#/components/schemas/DateTime'
      additionalProperties: false
    Files:
      type: array
      items:
        $ref: '#/components/schemas/File'
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 8a210b68-6988-11ed-a1eb-0242ac120002
        description: Unique identifier for your SMB in Codat.
    connectionId:
      name: connectionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 2e9d2c44-f675-40ba-8049-353bfcb5e171
        description: Unique identifier for a company's data connection.
  securitySchemes:
    auth_header:
      name: Authorization
      description: 'The word "Basic" followed by a space and your API Key, base64 encoded, which can be found [here](https://app.codat.io/developers/api-keys)'
      type: apiKey
      in: header