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:
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:
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
1tototal_parts. A part that skips ahead returns400with the part number expected. - Every part except the last carries at least 1 MB (
1048576bytes). - The file is at most 300 MB, so
total_partsis at most300. An upload that grows past 300 MB is aborted and has to start over with a newupload_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:
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:
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:
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:
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:
The above call returns the following JSON object:
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:
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. |