Skip to content

File


Endpoints

POST      /files
POST      /files/filter
GET       /files
GET       /files/:id
PUT       /files/:id
DELETE    /files/:id
DELETE    /files?ids=:id1,:id2

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 float Time at which the object was created. Measured in seconds since the Unix epoch.
updated float Time at which the object was updated. Measured in seconds since the Unix epoch.
name string The file's name. Up to 200 characters.
description string An arbitrary string attached to the file. Up to 500 characters.
tags array A list of strings. Up to 32 tags. Use them to find the file in a list.
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.
url string The path of the file in the Everysk platform.
hash string A hash of the file content.
date_time string The file date with a time.

Create a file

To create a new file, run the following:

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. Up to 200 characters.
description string optional, default is "" Provides detailed information about your file. Up to 500 characters.
tags array optional, default is [] A list of strings. Up to 32 tags.
date string optional, default is null File date in the format: YYYYMMDD.
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 data inside the generated file will be returned in the api response.
content_type string optional, default is application/octet-stream A string to identify the file's format. It accepts application/csv, application/javascript, application/json, application/msword, application/octet-stream, application/pdf, application/vnd.apache.parquet, application/vnd.ms-excel, application/vnd.ms-excel.sheet.macroEnabled.12, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/wps-office.xls, application/wps-office.xlsm, application/wps-office.xlsx, application/x-python, application/x-python-code, application/x-python-script, application/x-zip-compressed, application/xml, application/zip, audio/mpeg, audio/wav, image/bmp, image/gif, image/jpeg, image/png, image/svg+xml, image/webp, text/comma-separated-values, text/csv, text/html, text/markdown, text/plain, text/x-comma-separated-values, text/x-python, text/x-python-code, text/x-python-script, text/xml.
workspace string optional, default is main The workspace where the API creates the file. Send it in the JSON body.
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 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.

Send the metadata again on a PUT

On PUT, part 1 must send description, tags, content_type and workspace again. If part 1 leaves them out, the API sets description to "", tags to [], content_type to application/octet-stream and moves the file to the main workspace. name, date and link_uid keep their current values when you leave them out.

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 [] 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 The workspace of the file. Read from part 1. On PUT, leaving it out moves the file to main.
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 -G https://api.everysk.com/v2/files \
  --data-urlencode "query=#20210622" \
  --data-urlencode "workspace=main" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

The above call returns the following JSON object:

{
  "files": [
    {
      "content_type": "text/csv",
      "name": "MyFirstFile.csv",
      "url": "/file/cd83dc4a00ca489fb4c5b37bee26c86e",
      "workspace": "main",
      "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 list shows the most recently updated file first. A name search returns the files whose name starts with the text, case-insensitive, sorted A to Z. The list leaves out data unless you send with_data=true.

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 The workspace to list.
page_size integer optional, default is 10 Set the number of objects that will be listed per page, between 1 and 10000.
page_token string optional, default is null The next_page_token from the previous response. See the pagination guide.
with_data boolean optional, default is False When True, each file in the list includes its data.
start, end, date_time, period_field string optional Filter the list by a period. See Filter by period.

Filter files

To filter files, run the following:

curl https://api.everysk.com/v2/files/filter \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "workspace": "main",
        "tags": ["20210622"],
        "start": "20210601",
        "end": "20210630",
        "limit": 100
      }' \
  -X POST

The above call returns the following JSON object:

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

Returns the files of one workspace that match every filter you send, up to limit. The response has no next_page_token.

HTTP Request

POST /files/filter

HTTP Parameters

Parameter Description
workspace string REQUIRED The workspace to search. Without it, the API returns 400.
tags array optional, default is [] A list of strings. Returns the files that have every one of these tags.
link_uid string optional, default is null Returns the files with this link_uid.
start string optional, default is null Returns the files from this day onward, in the format YYYYMMDD.
end string optional, default is null Returns the files up to this day, in the format YYYYMMDD.
date_time string optional, default is null Returns the files of one day, in the format YYYYMMDD. It replaces start and end.
period_field string optional, default is date The property that start, end and date_time filter: date or updated_on.
limit integer optional, default is 1 The maximum number of files to return, between 1 and 10000.
with_data boolean optional, default is False When True, each item includes its data.

Retrieve a file

To retrieve a file, run the following:

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 The workspace of the object. If you send it and the object is in another workspace, the API returns 403.

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 "https://api.everysk.com/v2/files/file_F6jkfLDarpyTQAJBjGwx9r2cl?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).

The partial download does not read workspace.

Update a file

To update a file, run the following:

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. Every field is optional. Only the fields you send change. The other fields keep their current values.

HTTP Request

PUT /files/:id

HTTP Parameters

Parameter Description
name string optional A string to identify a file besides the file's id. Up to 200 characters.
description string optional Provides detailed information about your file. Up to 500 characters.
tags array optional A list of strings. Up to 32 tags. Replaces the current tags.
date string optional File date in the format: YYYYMMDD.
data string optional The content that will be stored inside the file. It must be in Base64 format.
content_type string optional A string to identify the file's format, from the list under Create a file.
workspace string optional Moves the object to this workspace. Leave it out to keep the current workspace.
link_uid string optional 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.
with_data boolean optional, default is True When True, the response includes the data of the file.

Delete a file

To delete a file, run the following:

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 identifier.
workspace string optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403.

Delete several files

To delete several files, run the following:

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

The above call returns the following JSON object:

{
  "files": [
    {
      "id": "file_F6jkfLDarpyTQAJBjGwx9r2cl",
      "name": "BATCH_DELETE",
      "deleted": true
    },
    {
      "id": "file_TIi0Fsjab3bbJoyg4cezSGEiY",
      "name": "BATCH_DELETE",
      "deleted": true
    }
  ]
}

Permanently deletes several files in one request. It cannot be undone. The response has one item for each id in ids. deleted is false for an id that the API could not delete. An id that does not exist also returns deleted: true. A bulk delete does not check workspace.

HTTP Request

DELETE /files?ids=:id1,:id2

HTTP Parameters

Parameter Description
ids string REQUIRED The ids to delete, separated by commas.