File storages

These endpoints are specific to file storage connections.

Retrieve file

Returns schema and first rows of a file.

Request

  • :id

    int Required

    The ID of the connection from which to read the users. It must be a source file storage.

  • path

    string Required

    The file path relative to the root of the file storage. For details on the required format, refer to the file storage connector documentation.

    The path must not be empty and cannot exceed 1,024 characters in length.

    Note that the path must be URL-encoded. For example, if the path is docs/users/subscribers.csv, you need to pass it as docs%2Fusers%2Fsubscribers.csv.

  • format

    string Required

    The file format. Note that it corresponds to the code of the file connector used to read the file.

    Possible values: "csv", "excel", "parquet" or "json".

  • sheet

    string Conditionally Required

    The sheet name. It can only be used with the "excel" format, where it is required.

    When provided, it must have a length between 1 and 31 characters, not start or end with a single quote ', and cannot contain any of the following characters: *, /, :, ?, [, \, and ].

  • compression

    string

    The method used to compress the file, if applicable.

    Note: An Excel file is inherently compressed, so no compression method needs to be specified unless the file has been further compressed.

    Possible values: "", "Zip", "Gzip" or "Snappy".

  • formatSettings

    nullable json

    The settings for the file format. Refer to the documentation for the connector related to the file format to understand the available settings and their corresponding values.

    If the file format does not require any settings, the formatSettings parameter must be either omitted or set to null.

  • limit

    int

    The maximum number of rows to return along with the schema. The maximum is 100; the default is 0, meaning no rows are returned.

Response

  • schema

    nullable schema

    The file's schema. It will be null if there are no supported columns.

  • rows

    array of object with json values

    The file's rows.

  • issues

    nullable array of string

    The issues encountered while reading the file, such as unsupported columns, which did not prevent processing. If it is not null, it contains at least one issue.
GET /v1/connections/:id/files
curl -G https://example.com/v1/connections/1371036433/files \
-H "Authorization: Bearer api_xxxxxxx" \
-d "path=users.xlsx" \
-d "format=excel" \
-d "sheet=Sheet1" \
-d "formatSettings=%7b%22HasColumnNames%22%3atrue%7d" \
-d "limit=50"
Response
{
  "schema": {
    "kind": "object",
    "properties": [
      {
        "name": "FirstName",
        "type": {
          "kind": "string"
        }
      },
      {
        "name": "LastName",
        "type": {
          "kind": "string"
        }
      }
    ]
  },
  "rows": [
    {
      "FirstName": "John",
      "LastName": "Mitchell"
    },
    {
      "FirstName": "Emily",
      "LastName": "Carter"
    },
    {
      "FirstName": "Michael",
      "LastName": "Reynolds"
    }
  ],
  "issues": [
    "Column \"Score\" cannot be imported because its type \"INT128\" is not supported"
  ]
}
Errors
404
workspace does not exist
404
connection does not exist
404
path does not exist

Read sheets

Returns the list of sheets in a file, applicable to file formats that support sheets.

Request

  • :id

    int Required

    The ID of the connection from which to read the users. It must be a source file storage.

  • path

    string Required

    The file path relative to the root of the file storage. For details on the required format, refer to the file storage connector documentation.

    The path must not be empty and cannot exceed 1,024 characters in length.

    Note that the path must be URL-encoded. For example, if the path is docs/users/subscribers.csv, you need to pass it as docs%2Fusers%2Fsubscribers.csv.

  • format

    string Required

    The file format. Note that it corresponds to the code of the file connector used to read the file.

    Possible values: "csv", "excel", "parquet" or "json".

  • compression

    string

    The method used to compress the file, if applicable.

    Note: An Excel file is inherently compressed, so no compression method needs to be specified unless the file has been further compressed.

    Possible values: "", "Zip", "Gzip" or "Snappy".

  • formatSettings

    nullable json

    The settings for the file format. Refer to the documentation for the connector related to the file format to understand the available settings and their corresponding values.

    If the file format does not require any settings, the formatSettings parameter must be either omitted or set to null.

Response

  • sheets

    array of string

    The sheets of the file. They have a length between 1 and 31 characters, not start or end with a single quote ', and cannot contain any of the following characters: *, /, :, ?, [, \, and ].
GET /v1/connections/:id/files/sheets
curl -G https://example.com/v1/connections/1371036433/files/sheets \
-H "Authorization: Bearer api_xxxxxxx" \
-d "path=users.xlsx" \
-d "format=excel" \
-d "formatSettings=%7b%22HasColumnNames%22%3atrue%7d"
Response
{
  "sheets": [
    "Sheet1",
    "Sheet2"
  ]
}
Errors
404
workspace does not exist
404
connection does not exist
404
path does not exist
422
format does not exist
422
format settings are not valid

Get absolute path

Returns the file path relative to the root of the file storage.

While this absolute path isn't used directly by other API endpoints, it can help confirm that the relative path points to the correct file.

Request

  • :id

    int Required

    The ID of the file storage connection for which the path should be retrieved.

  • path

    string Required

    The file path relative to the root of the file storage. For details on the required format, refer to the file storage connector documentation.

    The path must not be empty and cannot exceed 1,024 characters in length.

    Note that the path must be URL-encoded. For example, if the path is docs/users/subscribers.csv, you need to pass it as docs%2Fusers%2Fsubscribers.csv.

Response

  • path

    string

    The absolute path of the file.
GET /v1/connections/:id/files/absolute
curl -G https://example.com/v1/connections/1371036433/files/absolute \
-H "Authorization: Bearer api_xxxxxxx" \
-d "path=users.xlsx"
Response
{
  "path": "/data/users.csv"
}
Errors
404
workspace does not exist
404
connection does not exist
422
path is not valid
422
placeholder is not valid