{
  "openapi": "3.1.0",
  "servers": [
    {
      "description": "Production",
      "url": "https://api.codat.io"
    }
  ],
  "info": {
    "title": "Files API",
    "description": "> ### New to Codat?\n>\n> Our Files API reference is relevant only to our existing clients.\n> Please reach out to your Codat contact so that we can find the right product for you.\n\nAn API for uploading and downloading files from 'File Upload' Integrations.\n\nThe Accounting file upload, Banking file upload, and Business documents file upload integrations provide simple file upload functionality.\n\n<!-- Start Codat Tags Table -->\n## Endpoints\n\n| Endpoints | Description |\n| :- |:- |\n| Files | Endpoints to manage uploaded files. |\n<!-- End Codat Tags Table -->\n[Read more...](https://docs.codat.io/other/file-upload)\n\n[See our OpenAPI spec](https://github.com/codatio/oas) ",
    "version": "3.0.0",
    "contact": {
      "name": "Codat",
      "email": "support@codat.io"
    },
    "termsOfService": "https://www.codat.io/legals/"
  },
  "security": [
    {
      "auth_header": []
    }
  ],
  "x-speakeasy-retries": {
    "strategy": "backoff",
    "backoff": {
      "initialInterval": 500,
      "maxInterval": 60000,
      "maxElapsedTime": 3600000,
      "exponent": 1.5
    },
    "statusCodes": [
      408,
      429,
      "5XX"
    ],
    "retryConnectionErrors": true
  },
  "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/Payment-Required"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/Not-Found"
          },
          "429": {
            "$ref": "#/components/responses/Too-Many-Requests"
          },
          "500": {
            "$ref": "#/components/responses/Internal-Server-Error"
          },
          "503": {
            "$ref": "#/components/responses/Service-Unavailable"
          }
        },
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FileUpload"
              }
            }
          }
        },
        "description": "The *Upload files* endpoint uploads multiple files provided by the SMB to Codat. This may include personal identity documents, pitch decks, contracts, or files with accounting and banking data.\n\nUploaded files must meet the following requirements:\n\n- Up to 20 files can be uploaded at a time.\n- PDF, XLS, XLSX, XLSB, CSV, DOC, DOCX, PPT, PPTX, JPEG, JPG, and PNG files can be uploaded.\n- Each file can be up to 10MB in size.",
        "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"
                },
                "examples": {}
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/Payment-Required"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/Not-Found"
          },
          "429": {
            "$ref": "#/components/responses/Too-Many-Requests"
          },
          "500": {
            "$ref": "#/components/responses/Internal-Server-Error"
          },
          "503": {
            "$ref": "#/components/responses/Service-Unavailable"
          }
        },
        "description": "The *List files* endpoint returns a list of all files uploaded to Codat by the SMB. ",
        "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": {
                "x-speakeasy-usage-example": true,
                "schema": {
                  "title": "Data",
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/Payment-Required"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/Not-Found"
          },
          "429": {
            "$ref": "#/components/responses/Too-Many-Requests"
          },
          "500": {
            "$ref": "#/components/responses/Internal-Server-Error"
          },
          "503": {
            "$ref": "#/components/responses/Service-Unavailable"
          }
        },
        "description": "The *Download files* endpoint downloads all files that have  been uploaded by to SMB to Codat. A `date` may be specified to download any files uploaded on the date provided.",
        "operationId": "download-files"
      }
    }
  },
  "components": {
    "schemas": {
      "DateTime": {
        "title": "Date time",
        "type": "string",
        "examples": [
          "2022-10-23T00:00:00.000Z",
          "2022-10-23T00:00:00.000Z"
        ],
        "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:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones.  \n> 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,
            "description": "The file's name."
          },
          "displayName": {
            "type": "string",
            "nullable": true,
            "description": "An optional display name for the file."
          },
          "sourceType": {
            "type": "string",
            "nullable": true,
            "description": "The source of the file uploaded."
          },
          "uploaded": {
            "$ref": "#/components/schemas/DateTime"
          }
        },
        "additionalProperties": false
      },
      "Files": {
        "title": "Files",
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/File"
        }
      },
      "FileUpload": {
        "title": "Attachment upload",
        "type": "object",
        "x-internal": true,
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "$ref": "#/components/schemas/FileUpload/definitions/codatFile"
          }
        },
        "definitions": {
          "codatFile": {
            "type": "string",
            "description": "The file to be uploaded as an attachment.",
            "format": "binary"
          }
        }
      }
    },
    "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."
        },
        "description": "Unique identifier for a company."
      },
      "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."
        },
        "description": "Unique identifier for a connection."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request made is not valid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/Forbidden/content/application~1json/schema"
            },
            "examples": {
              "Malformed query": {
                "value": {
                  "statusCode": 400,
                  "service": "PublicApi",
                  "error": "Error processing request - not valid.",
                  "correlationId": "bc997528a9d7abb9161ef45f05d38599",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Your API request was not properly authorized.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/Forbidden/content/application~1json/schema"
            },
            "examples": {
              "Unauthorized": {
                "value": {
                  "statusCode": 401,
                  "service": "PublicApi",
                  "error": "Unauthorized",
                  "correlationId": "7eb40d6b415d7bcd99ce658268284056",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      },
      "Payment-Required": {
        "description": "An account limit has been exceeded. The type of limit is described in the error property:\n\n- You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request.\n- The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan.\n- Your Free account is older than 365 days and has expired. Contact support@codat.io.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/Forbidden/content/application~1json/schema"
            },
            "examples": {
              "Conflict": {
                "value": {
                  "statusCode": 429,
                  "service": "PublicApi",
                  "error": "You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request.",
                  "correlationId": "bc997528a9d7abb9161ef45f05d38599",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "You are using an outdated API key or a key not associated with that resource.",
        "content": {
          "application/json": {
            "schema": {
              "title": "Error message",
              "type": "object",
              "x-internal": true,
              "properties": {
                "statusCode": {
                  "type": "integer",
                  "description": "The HTTP status code returned by the error."
                },
                "service": {
                  "type": "string",
                  "description": "Codat's service the returned the error."
                },
                "error": {
                  "type": "string",
                  "description": "A brief description of the error."
                },
                "correlationId": {
                  "type": "string",
                  "description": "Unique identifier used to propagate to all downstream services and determine the source of the error."
                },
                "validation": {
                  "$ref": "#/components/responses/Forbidden/content/application~1json/schema/definitions/errorValidation"
                },
                "canBeRetried": {
                  "type": "string",
                  "description": "`True` if the error occurred transiently and can be retried."
                },
                "detailedErrorCode": {
                  "type": "integer",
                  "description": "Machine readable error code used to automate processes based on the code returned."
                }
              },
              "definitions": {
                "errorValidation": {
                  "title": "Validation error",
                  "type": "object",
                  "nullable": true,
                  "description": "A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "nullable": true,
                      "items": {
                        "$ref": "#/components/responses/Forbidden/content/application~1json/schema/definitions/errorValidationItem"
                      }
                    },
                    "warnings": {
                      "type": "array",
                      "nullable": true,
                      "items": {
                        "$ref": "#/components/responses/Forbidden/content/application~1json/schema/definitions/errorValidationItem"
                      }
                    }
                  }
                },
                "errorValidationItem": {
                  "title": "Validation error item",
                  "type": "object",
                  "properties": {
                    "itemId": {
                      "type": "string",
                      "nullable": true,
                      "description": "Unique identifier for a validation item."
                    },
                    "message": {
                      "type": "string",
                      "nullable": true,
                      "description": "A message outlining validation item's issue."
                    },
                    "validatorName": {
                      "type": "string",
                      "nullable": true,
                      "description": "Name of validator."
                    }
                  }
                }
              }
            },
            "examples": {
              "Conflict": {
                "value": {
                  "statusCode": 403,
                  "service": "PublicApi",
                  "error": "You are using an outdated API key or a key not associated with that resource.",
                  "correlationId": "bc997528a9d7abb9161ef45f05d38599",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      },
      "Not-Found": {
        "description": "One or more of the resources you referenced could not be found.\nThis might be because your company or data connection id is wrong, or was already deleted.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/Forbidden/content/application~1json/schema"
            },
            "examples": {
              "Data connection not found": {
                "value": {
                  "statusCode": 404,
                  "service": "PublicApi",
                  "error": "Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found",
                  "correlationId": "8fa2b5f4794970a4ee73758f612e8df0",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              },
              "Company not found": {
                "value": {
                  "statusCode": 404,
                  "service": "ClientsApi",
                  "error": "No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e",
                  "correlationId": "0a40c2f31fc8f992fb88b0853e4166f3",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              },
              "No data available": {
                "value": {
                  "statusCode": 404,
                  "service": "PublicApi",
                  "error": "No data available for accounts for ID e5889b459f544926ac5b8e6756df2s",
                  "correlationId": "0a40c2f31fc8f992fb88b0853e4166f3",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      },
      "Too-Many-Requests": {
        "description": "Too many requests were made in a given amount of time. Wait a short period and then try again.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/Forbidden/content/application~1json/schema"
            },
            "examples": {
              "Conflict": {
                "value": {
                  "statusCode": 429,
                  "service": "PublicApi",
                  "error": "You have made too many requests in a given amount of time; please retry later.",
                  "correlationId": "bc997528a9d7abb9161ef45f05d38599",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      },
      "Internal-Server-Error": {
        "description": "There is a problem with our server. Please try again later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/Forbidden/content/application~1json/schema"
            },
            "examples": {
              "Conflict": {
                "value": {
                  "statusCode": 500,
                  "service": "PublicApi",
                  "error": "There is a problem with our server. Please try again later.",
                  "correlationId": "bc997528a9d7abb9161ef45f05d38599",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      },
      "Service-Unavailable": {
        "description": "The Codat API is temporarily offline for maintenance. Please try again later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/Forbidden/content/application~1json/schema"
            },
            "examples": {
              "Conflict": {
                "value": {
                  "statusCode": 500,
                  "service": "PublicApi",
                  "error": "The Codat API is temporarily offline for maintenance. Please try again later.",
                  "correlationId": "bc997528a9d7abb9161ef45f05d38599",
                  "canBeRetried": "Unknown",
                  "detailedErrorCode": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "auth_header": {
        "name": "Authorization",
        "description": "The word \"Basic\" followed by a space and your API key. [API keys](https://docs.codat.io/accounting-api#/schemas/apiKeys) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/codat-api#/api-keys/api-keys-list), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.",
        "type": "apiKey",
        "in": "header",
        "x-speakeasy-example": "Basic BASE_64_ENCODED(API_KEY)"
      }
    }
  }
}