File¶

Endpoints

POST      /files
GET       /files
GET       /files/:id
PUT       /files/:id
DELETE    /files/:id

A file is a collection of data stored in one unit, identified by a filename. It can be a document, picture, data library, application, or other collection of data.

The file object¶

What a file object looks like?

{
  "content_type": "text/csv",
  "url": "/file/40218fbb3b2c49d7b78c5bfc40f66b56",
  "tags": ["first", "file", "20210622"],
  "created": 1628774405,
  "updated": 1628774405,
  "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
  "workspace": "main",
  "link_uid": null,
  "data": "aGVsbG8gd29ybGQ=",
  "name": "MyFirstFile.csv",
  "description": "This is my first file"
}

Property	Description
`id` string	Unique identifier (UID) for the file.
`content_type` string	A string to identify the file's format.
`created` timestamp	Time at which the object was created. Measured in seconds since the Unix epoch.
`updated` timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.
`name` string	The file's name.
`description` string	An arbitrary string attached to the report. Often useful for finding detailed information about the file or for filtering a search based on the present hashtags.
`tags` array	Sequence of hashtags used to find the related file. The more hashtags that are used, the more elements that are filtered out from the search. Labels, dates and any other hashtag can be used.
`version` string	Indicates the file's current version.
`date` string	File date in the format: `YYYYMMDD`.
`data` string	The content that will be stored inside the file. It must be in Base64 format.
`workspace` string	The workspace where the file was generated.
`link_uid` string	An identifier you choose to link the file to related entities, such as the other files of the same feed. Several entities can share it.

Create a file¶

To create a new file, run the following:

Curl

curl https://api.everysk.com/v2/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "name": "MyFirstFile.csv",
        "tags": [
          "first",
          "file",
          "20210622"
        ],
        "description": "This is my first stored file",
        "data": "aGVsbG8gd29ybGQ=",
        "content_type": "text/csv",
        "workspace": "main"
      }' \
  -X POST

The above call returns the following JSON object:

{
  "file": {
    "content_type": "text/csv",
    "url": "/file/40218fbb3b2c49d7b78c5bfc40f66b56",
    "tags": ["first", "file", "20210622"],
    "created": 1628774405,
    "updated": 1628774405,
    "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
    "workspace": "main",
    "data": "aGVsbG8gd29ybGQ=",
    "name": "MyFirstFile.csv",
    "description": "This is my first stored file"
  }
}

Creates and then returns the new file.

HTTP Request

POST /files

HTTP Parameters

Parameter	Description
`name` string	REQUIRED A string to identify a file besides the file's id. Feel free to use a meaningful name for your file.
`description` string	REQUIRED Provides detailed information about your file. You may add hashtags to create tags allowing you to search for them later.
`tags` string	optional, default is `null` Filters the list of files through the tags added in the description. Do not use hashtags when passing a value to this parameter.
`data` string	REQUIRED The content that will be stored inside the file. It must be in Base64 format.
`with_data` boolean	optional, default is `True` When True, the the data inside the generated file will be returned in the api response.
`content_type` string	REQUIRED A string to identify the file's format. It accepts `image/svg+xml`, `image/bmp`, `image/jpeg`, `image/png`, `image/gif`, `application/xml`, `text/xml`, `application/javascript`, `application/json`, `text/plain`, `text/csv`, `application/csv`, `text/x-comma-separated-values`, `text/comma-separated-values`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/vnd.ms-excel`, `application/pdf`, `application/zip`, `'application/x-zip-compressed'`, `application/octet-stream`.
`workspace` string	optional, default is `main` Determines on which workspace the request will be made.
`link_uid` string	optional, default is `null` An identifier you choose to link the file to related entities, such as the other files of the same feed. Several entities can share it.

Upload a file in parts¶

A file of up to 300 MB can be sent in sequential parts instead of one Base64 body. Each part is a multipart/form-data request to POST /files that carries raw bytes, not Base64, in the chunk field. The file is created when the last part arrives.

To split a file into parts of 32 MB each:

split -b 32m positions.csv positions.part.

To send the first of three parts, run the following:

Curl

curl https://api.everysk.com/v2/files \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -F "upload_id=positions-20260925" \
  -F "part_number=1" \
  -F "total_parts=3" \
  -F "name=positions.csv" \
  -F "content_type=text/csv" \
  -F "workspace=main" \
  -F "link_uid=positions-feed" \
  -F "chunk=@positions.part.aa" \
  -X POST

The above call returns the following JSON object:

{
  "status": "staged",
  "parts_received": 1,
  "total_parts": 3,
  "upload_id": "positions-20260925"
}

Send the next parts the same way, with the same upload_id and total_parts and the next part_number. The file's metadata is read from part 1 only, so the later parts need no name. The last part creates the file and returns it, without its content:

{
  "file": {
    "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
    "name": "positions.csv",
    "content_type": "text/csv",
    "workspace": "main",
    "data": null,
    ...
  }
}

To replace the content of an existing file, send the parts to PUT /files/:id instead. There, part 1 needs no name either, and an id that does not exist fails on part 1 with 404, before anything is uploaded.

Rules

Parts go in order, from 1 to total_parts. A part that skips ahead returns 400 with the part number expected.
Every part except the last carries at least 1 MB (1048576 bytes).
The file is at most 300 MB, so total_parts is at most 300. An upload that grows past 300 MB is aborted and has to start over with a new upload_id.
Each part is its own request, so it must fit the maximum payload size.
Resending a part that already arrived does nothing, so a part that timed out can be retried safely. Resending the last part after the file was created returns {"status": "done", "file": {"id": ...}} with the same id, and no second file.
An upload that receives no part for 2 hours expires. Start over with a new upload_id.

HTTP Request

POST /files

PUT /files/:id

HTTP Parameters

Send the parameters as multipart/form-data fields.

Parameter	Description
`upload_id` string	REQUIRED An id you choose for the upload, the same on every part. Letters, digits, `_` and `-`, up to 128 characters.
`part_number` integer	REQUIRED The number of this part, from `1` to `total_parts`.
`total_parts` integer	REQUIRED How many parts the file has. The same on every part.
`chunk` file	REQUIRED The raw bytes of this part, as a file field.
`name` string	REQUIRED on part `1` of a `POST` The file's name.
`description` string	optional, default is `""` Detailed information about the file. Read from part `1`.
`tags` string	optional, default is `null` The file's tags. Repeat the field to send more than one, for example `-F "tags=positions" -F "tags=daily"`. Read from part `1`.
`content_type` string	optional, default is `application/octet-stream` The file's format, from the list under Create a file. Read from part `1`.
`date` string	optional, default is `null` File date in the format `YYYYMMDD`. Read from part `1`.
`workspace` string	optional, default is `main` Determines on which workspace the file will be created. Read from part `1`.
`link_uid` string	optional, default is `null` An identifier you choose to link the file to related entities, such as the other files of the same feed. Several entities can share it. Read from part `1`.
`with_data` boolean	optional, default is `False` When `True`, the last part returns the file with its content in `data`.

List all files¶

To list all files, run the following:

Curl

curl https://api.everysk.com/v2/files?query=#20210622&workspace=main \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

The above call returns the following JSON object:

{
  "files": [
    {
      "content_type": "text/csv",
      "name": "MyFirstFile.csv",
      "url": "/file/cd83dc4a00ca489fb4c5b37bee26c86e",
      "workspace": "main",
      "data": "aGVsbG8gd29ybGQ=",
      "description": "My first stored file",
      "created": 1628791473,
      "id": "file_TIi0Fsjab3bbJoyg4cezSGEiY",
      "updated": 1628791473,
      "tags": [
        "first",
        "file",
        "20210622"
      ]
    },
    ...
  ],
  "next_page_token": null
}

Returns a list of files you’ve previously created. The files are returned in sorted order, with the most recent file appearing first.

HTTP Request

GET /files

HTTP Parameters

Parameter	Description
`query` string	optional, default is `null` Request a list of files filtering it by `name` or `tag`. When using a `tag` to perform a query, each term must include a hashtag prefix. (e.g: `query`="#april #sample") See Filter with query.
`workspace` string	optional, default is `main` Determines on which workspace the request will be made.
`page_size` integer	optional, default is `10` Set the number of objects that will be listed per page.
`page_token` integer	optional, default is `null` The token defines which page will be returned to the user. For further information, please check out our pagination guide.

Retrieve a file¶

To retrieve a file, run the following:

Curl

curl https://api.everysk.com/v2/files/file_F6jkfLDarpyTQAJBjGwx9r2cl?workspace=main \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

The above call returns the following JSON object:

{
  "file": {
    "content_type": "text/csv",
    "url": "/file/40218fbb3b2c49d7b78c5bfc40f66b56",
    "created": 1628774405,
    "tags": ["first", "file", "20210622"],
    "updated": 1628774405,
    "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
    "workspace": "main",
    "data": "aGVsbG8gd29ybGQ=",
    "name": "MyFirstFile.csv",
    "description": "This is my first stored file"
  }
}

Retrieves the details of an existing file by supplying the file's id.

HTTP Request

GET /files/:id

HTTP Parameters

Parameter	Description
`id` string	REQUIRED A unique identifier (UID) for a file. A file's `id` will always look like this: `file_F6jkfLDarpyTQAJBjGwx9r2cl`.
`workspace` string	optional, default is `main` Determines on which workspace the request will be made.

Download a file in parts¶

A large file can be read one slice at a time instead of in a single response. Pass part_number, and optionally part_size, to GET /files/:id, and repeat the request from 1 to the total_parts the first response returns.

To download the first part of a file, run the following:

Curl

curl "https://api.everysk.com/v2/files/file_F6jkfLDarpyTQAJBjGwx9r2cl?workspace=main&part_number=1&part_size=33554432" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

The above call returns the following JSON object:

{
  "status": "partial",
  "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
  "part_number": 1,
  "total_parts": 4,
  "part_size": 33554432,
  "size": 110100480,
  "chunk": "aWQsc3ltYm9sLHF1YW50aXR5..."
}

chunk is the slice in Base64. Decode each one and join them in part_number order to rebuild the file. size is the size of the whole file in bytes.

HTTP Request

GET /files/:id

HTTP Parameters

Parameter	Description
`id` string	REQUIRED A unique identifier (UID) for a file.
`part_number` integer	REQUIRED The part to return, from `1` to `total_parts`. A number outside that range returns `400`.
`part_size` integer	optional, default is `33554432` (32 MB) The size of each part, in bytes. Must be between `1048576` (1 MB) and `67108864` (64 MB).
`workspace` string	optional, default is `main` Determines on which workspace the request will be made.

Update a file¶

To update a file, run the following:

Curl

curl https://api.everysk.com/v2/files/file_F6jkfLDarpyTQAJBjGwx9r2cl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "name": "UpdatedFile.csv",
        "description": "My first file was updated",
        "data": "aGVsbG8geW91IGFsbA==",
        "content_type": "text/csv"
      }' \
  -X PUT

The above call returns the following JSON object:

{
  "file": {
    "data": "aGVsbG8geW91IGFsbA==",
    "content_type": "text/csv",
    "name": "UpdatedFile.csv",
    "url": "/file/8c5bdaf066bc4208a06e9808426afdda",
    "workspace": "main",
    "description": "My first file was updated",
    "created": 1628774405,
    "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
    "updated": 1628792475,
    "tags": ["first", "file", "20210622"]
  }
}

Updates a file and then returns the updated file.

HTTP Request

PUT /files/:id

HTTP Parameters

Parameter	Description
`name` string	REQUIRED A string to identify a file besides the file's id. Feel free to use a meaningful name for your file.
`description` string	REQUIRED Provides detailed information about your file. You may add hashtags to create tags allowing you to search for them later.
`tags` string	optional, default is `null` Filters the list of files through the tags added in the description. Do not use hashtags when passing a value to this parameter.
`data` string	REQUIRED The content that will be stored inside the file. It must be in Base64 format.
`content_type` string	REQUIRED A string to identify the file's format. It accepts `image/svg+xml`, `image/bmp`, `image/jpeg`, `image/png`, `image/gif`, `application/xml`, `application/javascript`, `application/json`, `application/csv`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/vnd.ms-excel`, `application/pdf`, `application/octet-stream`, `application/zip`, `text/xml`, `text/plain`, `text/csv`, `text/comma-separated-values`, `text/x-comma-separated-values`.
`workspace` string	optional, default is `main` Determines on which workspace the request will be made.
`link_uid` string	optional, default is `null` An identifier you choose to link the file to related entities, such as the other files of the same feed. Several entities can share it.

Delete a file¶

To delete a file, run the following:

Curl

curl https://api.everysk.com/v2/files/file_F6jkfLDarpyTQAJBjGwx9r2cl?workspace=main \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

The above call returns the following JSON object:

{
  "file": {
    "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
    "name": "MyFirstFile.csv",
    "deleted": true
  }
}

Permanently deletes a file. It cannot be undone. Returns an object with the file's id and an attribute specifying whether the file was successfully deleted or not.

HTTP Request

DELETE /files/:id

HTTP Parameters

Parameter	Description
`id` string	REQUIRED The file's unique indetifier.
`workspace` string	optional, default is `main` Determines on which workspace the request will be made.