📄Files

List

List Files

GET https://uc.alxgsv.com/api/v1/projects/:project_id/files.json

curl -X GET -H "Authorization: Bearer ${SECRET_KEY}" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files.json

Path Parameters

Name

Type

Description

project_id*

String

page

Integer

Page for pagination

items

Integer

Number of files per page for pagination

Headers

Name

Type

Description

Authorization*

String

Bearer SECRET_KEY

{
    "data": [
        {
            "type": "files",
            "id": "f-pzRscOLZpMNeUjUUlHIwhS",
            "attributes": {
                "uuid": "e3b7bca3-e657-43b8-b8be-b79edf106e47",
                "is_image": true,
                "status": "ready",
                "mime": {
                    "mime": "image/png",
                    "type": "image",
                    "subtype": "png"
                },
                "original_url": "https://ucarecdn.com/e3b7bca3-e657-43b8-b8be-b79edf106e47/SCR20231117qnol.png",
                "original_name": "SCR-20231117-qnol.png",
                "size": 14,
                "original_protected": true,
                "chunked_upload": {
                    "is_chunked_upload": false,
                    "chunk_size": null,
                    "is_complete": false
                },
                "metadata": {},
                "content": {
                    "image": {
                        "dpi": [
                            144,
                            144
                        ],
                        "width": 378,
                        "format": "PNG",
                        "height": 352,
                        "sequence": false,
                        "color_mode": "RGBA",
                        "orientation": null,
                        "geo_location": null,
                        "datetime_original": null
                    },
                    "video": null
                },
                "created_at": "2023-11-18T07:36:58.449Z",
                "uploaded_at": "2023-11-18T07:36:57.897038Z",
                "removed_at": null,
                "expires_at": null
            },
            "relationships": {
                "project": {
                    "data": {
                        "type": "projects",
                        "id": "8a540ce633522d881e97"
                    }
                }
            },
            "authentication": {
                "access_token": "fat-pfeERYqeB6CzXHwcNp6B0i"
            },
            "chunked_upload_urls": []
        },
        {
            "type": "files",
            "id": "f-IC3oc8MHjv1WV9iV7DulJI",
            "attributes": {
                "uuid": "49936ae3-a967-4975-92c4-01c6a535c903",
                "is_image": null,
                "status": "pending",
                "mime": null,
                "original_url": null,
                "original_name": "20mb.jpg",
                "size": 15,
                "original_protected": true,
                "chunked_upload": {
                    "is_chunked_upload": true,
                    "chunk_size": 10485760,
                    "is_complete": true
                },
                "metadata": {
                    "foo": "bar"
                },
                "content": {
                    "image": null,
                    "video": null
                },
                "created_at": "2023-11-18T07:50:39.587Z",
                "uploaded_at": "2023-11-18T07:50:39.460403Z",
                "removed_at": null,
                "expires_at": null
            },
            "relationships": {
                "project": {
                    "data": {
                        "type": "projects",
                        "id": "8a540ce633522d881e97"
                    }
                }
            },
            "authentication": {
                "access_token": "fat-iAWqPSlSybODKHMiybfxL5"
            },
            "chunked_upload_urls": []
        }
    ],
    "pagination": {
        "count": 2,
        "page": 1,
        "items": 20,
        "pages": 1
    }
}

Direct uploads

Direct File upload

POST https://uc.alxgsv.com/api/v1/projects/:project_id/files.json

Authentication specifics You can upload file to your project with or without authentication, depending on how you Project is set up. If you're making a non-authenticated upload, you will get the access token that allows modifications to this specific file. It could be useful if you're uploading this file on behalf of your user, so you can't share secret keys with them, but want them to access metadata of this file or edit it later, without giving such an access to public.

Authorized client:

curl -X POST -H "Authorization: Bearer ${SECRET_KEY}" -F "file[content]=@/path/to_file" -F "file[metadata][foo]=bar" -F "file[expires_at]=2023-11-18T08:38:39Z" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files.json

Anonymous client:

curl -X POST -F "file[content]=@/path/to_file" -F "file[metadata][foo]=bar" -F "file[expires_at]=2023-11-18T08:38:39Z" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files.json

Path Parameters

Name

Type

Description

project_id*

String

Headers

Name

Type

Description

Authorization

String

Bearer SECRET_KEY

Request Body

Name

Type

Description

file[content]*

File

Uploaded file (if source_url is not defined)

file[metadata]

Object

Key-value dictionary of new file's metadata

file[expires_at]

String

When to remove this file

file[original_protected]

Boolean

Protected originals are not served by CDN to prevent metadata leaks. Default: true.

{
    "data": {
        "type": "files",
        "id": "f-aSNfnv1GIC1GVwTSdBXIv1",
        "attributes": {
            "uuid": "1687bbf8-b3ca-4323-b4c8-5e5f803bad82",
            "is_image": true,
            "status": "ready",
            "mime": {
                "mime": "image/png",
                "type": "image",
                "subtype": "png"
            },
            "original_url": "https://ucarecdn.com/1687bbf8-b3ca-4323-b4c8-5e5f803bad82/SCR20231117qnol.png",
            "original_name": "SCR-20231117-qnol.png",
            "size": 14,
            "original_protected": true,
            "chunked_upload": {
                "is_chunked_upload": false,
                "chunk_size": null,
                "is_complete": false
            },
            "metadata": {
                "foo": "bar"
            },
            "content": {
                "image": {
                    "dpi": [
                        144,
                        144
                    ],
                    "width": 378,
                    "format": "PNG",
                    "height": 352,
                    "sequence": false,
                    "color_mode": "RGBA",
                    "orientation": null,
                    "geo_location": null,
                    "datetime_original": null
                },
                "video": null
            },
            "created_at": "2023-11-26T09:27:28.398Z",
            "uploaded_at": "2023-11-26T09:27:27.850838Z",
            "removed_at": null,
            "expires_at": "2023-11-18T08:38:39.000Z"
        },
        "relationships": {
            "project": {
                "data": {
                    "type": "projects",
                    "id": "8a540ce633522d881e97"
                }
            }
        },
        "authentication": {
            "access_token": "fat-cUcMtSV4xOcbPBNsWAS5Fs"
        },
        "chunked_upload_urls": []
    }
}

Internet uploads

Upload File from the internet

POST https://uc.alxgsv.com/api/v1/projects/:project_id/files.json

Authorized client:

curl -X POST -H "Authorization: Bearer ${SECRET_KEY}" -d "file[source_url]=https://example.com/robots.txt" -d "file[metadata][foo]=bar" -d "file[expires_at]=2023-11-18T08:38:39Z" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files.json

Anonymous client:

curl -X POST -d "file[source_url]=https://example.com/robots.txt" -d "file[metadata][foo]=bar" -d "file[expires_at]=2023-11-18T08:38:39Z" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files.json

Path Parameters

Name

Type

Description

project_id*

String

Headers

Name

Type

Description

Authorization

String

Bearer SECRET_KEY

Request Body

Name

Type

Description

file[source_url]*

String

URL of a file in the internet to download

file[expires_at]

String

When to remove this file

file[metadata]

Object

Key-value dictionary of new file's metadata

file[original_protected]

Boolean

Protected originals are not served by CDN to prevent metadata leaks. Default: true.

{
    "data": {
        "type": "files",
        "id": "f-lw1KJfuk8nS6P0Vwl1I4Hw",
        "attributes": {
            "uuid": null,
            "is_image": null,
            "status": "pending",
            "mime": null,
            "original_url": null,
            "original_name": null,
            "size": null,
            "original_protected": true,
            "chunked_upload": {
                "is_chunked_upload": false,
                "chunk_size": null,
                "is_complete": false
            },
            "metadata": {},
            "content": {
                "image": null,
                "video": null
            },
            "created_at": "2023-11-26T09:15:48.991Z",
            "uploaded_at": null,
            "removed_at": null,
            "expires_at": "2023-11-18T08:38:39.000Z"
        },
        "relationships": {
            "project": {
                "data": {
                    "type": "projects",
                    "id": "8a540ce633522d881e97"
                }
            }
        },
        "authentication": {
            "access_token": "fat-OzzCVX2piXV7cvoREgb278"
        },
        "chunked_upload_urls": []
    }
}

Chunked uploads

Start Chunked upload

POST https://uc.alxgsv.com/api/v1/projects/:project_id/files.json

Chunk uploading specifics This call will start chunked uploading process. It will return a several upload links, one for each chunk. You need to PUT each chunk to the corresponding URL.

Finalization After all chunks are uploaded, you need to finalize upload by updating is_chunked_upload_complete attribute of the File.

curl -X POST -d "file[is_chunked_upload]=true" -d "file[size]=18462554" -d "file[chunk_size]=10485760" -d "file[filename]=20mb.jpg" -d "file[content_type]=image/jpeg" -d "file[metadata][foo]=bar" -d "file[expires_at]=2023-11-18T08:38:39Z" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files.json

or in JSON:

curl -X POST -H "Content-Type: application/json" -d '{"file"{"is_chunked_upload": "true", "size": 18462554, "chunk_size": 10485760, "filename": "20mb.jpg", "content_type": "image/jpeg", "metadata": {"foo": "bar"}, "expires_at": "2023-11-18T08:38:39Z"}' https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files.json

Path Parameters

Name

Type

Description

project_id*

String

Headers

Name

Type

Description

Authorization

String

Bearer SECRET_KEY

Request Body

Name

Type

Description

file[filename]*

String

file[size]*

Integer

File size in bytes

file[chunk_size]*

Integer

Size of each chunk (except last one), in bytes

file[content_type]*

String

file[expires_at]

String

When to remove this file

file[original_protected]

Boolean

Protected originals are not served by CDN to prevent metadata leaks. Default: true.

{
    "data": {
        "type": "files",
        "id": "f-SVWbvWImaRq5uHEiY6g6T9",
        "attributes": {
            "uuid": "feb35e12-1a98-49b2-bfdf-413f001d0ab1",
            "is_image": null,
            "status": "pending",
            "mime": null,
            "original_url": null,
            "original_name": null,
            "size": 1,
            "original_protected": true,
            "chunked_upload": {
                "is_chunked_upload": true,
                "chunk_size": 10485760,
                "is_complete": false
            },
            "metadata": {},
            "content": {
                "image": null,
                "video": null
            },
            "created_at": "2023-11-18T07:46:11.399Z",
            "uploaded_at": null,
            "removed_at": null,
            "expires_at": null
        },
        "relationships": {
            "project": {
                "data": {
                    "type": "projects",
                    "id": "8a540ce633522d881e97"
                }
            }
        },
        "authentication": {
            "access_token": "fat-E8mD6VEXUjT2qVGNbap2je"
        },
        "chunked_upload_urls": [
            "https://uploadcare.s3-accelerate.amazonaws.com/feb35e12-1a98-49b2-bfdf-413f001d0ab1/20mb.jpg?uploadId=i9vSetdlOjc8LyhQkO2W216EUHXmyqqXrq0I5uP9dGZI_KJtJKY6_6UVResrK.xP5jgexMgYqwlAeVFtrRegN0t.QcILb_0AZ3TdKcAc95X.js.G908AeBOo9NdJLwNU&partNumber=1&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA5C7IQCBHKSST3AMC%2F20231118%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231118T074611Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=a2852c9da6b1ca7165846785c9355d2d82a794699913680d1c3fd688ccb47723",
            "https://uploadcare.s3-accelerate.amazonaws.com/feb35e12-1a98-49b2-bfdf-413f001d0ab1/20mb.jpg?uploadId=i9vSetdlOjc8LyhQkO2W216EUHXmyqqXrq0I5uP9dGZI_KJtJKY6_6UVResrK.xP5jgexMgYqwlAeVFtrRegN0t.QcILb_0AZ3TdKcAc95X.js.G908AeBOo9NdJLwNU&partNumber=2&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA5C7IQCBHKSST3AMC%2F20231118%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231118T074611Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=1ecbffe919fd96561334f42b014fa490223c6c73d3f11ce3e7e1d008b3894d10"
        ]
    }
}

Upload one File chunk

PUT https://url/from/chunked/urls/of/the/file

curl -X PUT -d @/path/to/chunk https://url/from/chunked/urls/of/the/file

Finalize Chunked upload

PUT https://uc.alxgsv.com/api/v1/projects/:project_id/files/:file_id.json

Authentication specifics Files can be accessed either by Project's secret key or by File's access token. curl -X PUT -H "Authorization: Bearer ${SECRET_KEY}" -d "file[is_chunked_upload_complete]=true" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files/${FILE_ID}.json

or in JSON:

curl -X PUT -H "Authorization: Bearer ${SECRET_KEY}" -H "Content-Type: application/json"-d '{"file":{"is_chunked_upload_complete": true}}' https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files/${FILE_ID}.json

Path Parameters

Name

Type

Description

project_id*

String

file_id*

String

Headers

Name

Type

Description

Authorization*

String

Bearer SECRET_KEY or Bearer FILE_ACCESS_TOKEN

Request Body

Name

Type

Description

is_chunked_upload_complete*

Boolean

true

{
    "data": {
        "type": "files",
        "id": "f-aSNfnv1GIC1GVwTSdBXIv1",
        "attributes": {
            "uuid": "1687bbf8-b3ca-4323-b4c8-5e5f803bad82",
            "is_image": true,
            "status": "ready",
            "mime": {
                "mime": "image/png",
                "type": "image",
                "subtype": "png"
            },
            "original_url": "https://ucarecdn.com/1687bbf8-b3ca-4323-b4c8-5e5f803bad82/SCR20231117qnol.png",
            "original_name": "SCR-20231117-qnol.png",
            "size": 14,
            "original_protected": true,
            "chunked_upload": {
                "is_chunked_upload": false,
                "chunk_size": null,
                "is_complete": false
            },
            "metadata": {
                "foo": "bar"
            },
            "content": {
                "image": {
                    "dpi": [
                        144,
                        144
                    ],
                    "width": 378,
                    "format": "PNG",
                    "height": 352,
                    "sequence": false,
                    "color_mode": "RGBA",
                    "orientation": null,
                    "geo_location": null,
                    "datetime_original": null
                },
                "video": null
            },
            "created_at": "2023-11-26T09:27:28.398Z",
            "uploaded_at": "2023-11-26T09:27:27.850838Z",
            "removed_at": null,
            "expires_at": "2023-11-18T08:38:39.000Z"
        },
        "relationships": {
            "project": {
                "data": {
                    "type": "projects",
                    "id": "8a540ce633522d881e97"
                }
            }
        },
        "authentication": {
            "access_token": "fat-cUcMtSV4xOcbPBNsWAS5Fs"
        },
        "chunked_upload_urls": []
    }
}

View

View File

GET https://uc.alxgsv.com/api/v1/projects/:project_id/files/:file_id.json

Authentication specifics Files can be accessed either by Project's secret key or by File's access token.

curl -X GET -H "Authorization: Bearer ${SECRET_KEY}" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files/${FILE_ID}.json

Path Parameters

Name

Type

Description

project_id*

String

file_id*

String

Headers

Name

Type

Description

Authorization*

String

Bearer SECRET_KEY or Bearer FILE_ACCESS_TOKEN

{
    "data": {
        "type": "files",
        "id": "f-aSNfnv1GIC1GVwTSdBXIv1",
        "attributes": {
            "uuid": "1687bbf8-b3ca-4323-b4c8-5e5f803bad82",
            "is_image": true,
            "status": "ready",
            "mime": {
                "mime": "image/png",
                "type": "image",
                "subtype": "png"
            },
            "original_url": "https://ucarecdn.com/1687bbf8-b3ca-4323-b4c8-5e5f803bad82/SCR20231117qnol.png",
            "original_name": "SCR-20231117-qnol.png",
            "size": 14,
            "original_protected": true,
            "chunked_upload": {
                "is_chunked_upload": false,
                "chunk_size": null,
                "is_complete": false
            },
            "metadata": {
                "foo": "bar"
            },
            "content": {
                "image": {
                    "dpi": [
                        144,
                        144
                    ],
                    "width": 378,
                    "format": "PNG",
                    "height": 352,
                    "sequence": false,
                    "color_mode": "RGBA",
                    "orientation": null,
                    "geo_location": null,
                    "datetime_original": null
                },
                "video": null
            },
            "created_at": "2023-11-26T09:27:28.398Z",
            "uploaded_at": "2023-11-26T09:27:27.850838Z",
            "removed_at": null,
            "expires_at": "2023-11-18T08:38:39.000Z"
        },
        "relationships": {
            "project": {
                "data": {
                    "type": "projects",
                    "id": "8a540ce633522d881e97"
                }
            }
        },
        "authentication": {
            "access_token": "fat-cUcMtSV4xOcbPBNsWAS5Fs"
        },
        "chunked_upload_urls": []
    }
}

Update

Update a File

PUT https://uc.alxgsv.com/api/v1/projects/:project_id/files/:file_id.json

Authentication specifics Files can be accessed either by Project's secret key or by File's access token.

There 2 ways to manipulate metadata. Pass an Object of new metadata to rewrite it completely, or pass an Array like [{"key": key, "value": "value"}, ...] to set only specific keys.

curl -X PUT -H "Authorization: Bearer ${SECRET_KEY}" -d "file[expires_at]=2023-11-18T08:38:39Z" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files/${FILE_ID}.json

or in JSON:

curl -X PUT -H "Authorization: Bearer ${SECRET_KEY}" -H "Content-Type: application/json" -d '{"file": {"expires_at": "2023-11-18T08:38:39Z"}}' https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files/${FILE_ID}.json

Path Parameters

Name

Type

Description

project_id*

String

file_id*

String

Headers

Name

Type

Description

Authorization*

String

Bearer SECRET_KEY or Bearer ACCESS_TOKEN

Request Body

Name

Type

Description

file[metadata]

Object

Metadata object to rewrite current metadata

file[metadata]

Array

List of {"key": KEY", value: "VALUE"} object to only set those keys without touching others.

file[expires_at]

String

When to remove this file

file[original_protected]

Boolean

Protected originals are not served by CDN to prevent metadata leaks. Default: true.

{
    "data": {
        "type": "files",
        "id": "f-aSNfnv1GIC1GVwTSdBXIv1",
        "attributes": {
            "uuid": "1687bbf8-b3ca-4323-b4c8-5e5f803bad82",
            "is_image": true,
            "status": "ready",
            "mime": {
                "mime": "image/png",
                "type": "image",
                "subtype": "png"
            },
            "original_url": "https://ucarecdn.com/1687bbf8-b3ca-4323-b4c8-5e5f803bad82/SCR20231117qnol.png",
            "original_name": "SCR-20231117-qnol.png",
            "size": 14,
            "original_protected": true,
            "chunked_upload": {
                "is_chunked_upload": false,
                "chunk_size": null,
                "is_complete": false
            },
            "metadata": {
                "foo": "bar"
            },
            "content": {
                "image": {
                    "dpi": [
                        144,
                        144
                    ],
                    "width": 378,
                    "format": "PNG",
                    "height": 352,
                    "sequence": false,
                    "color_mode": "RGBA",
                    "orientation": null,
                    "geo_location": null,
                    "datetime_original": null
                },
                "video": null
            },
            "created_at": "2023-11-26T09:27:28.398Z",
            "uploaded_at": "2023-11-26T09:27:27.850838Z",
            "removed_at": null,
            "expires_at": "2023-11-18T08:38:39.000Z"
        },
        "relationships": {
            "project": {
                "data": {
                    "type": "projects",
                    "id": "8a540ce633522d881e97"
                }
            }
        },
        "authentication": {
            "access_token": "fat-cUcMtSV4xOcbPBNsWAS5Fs"
        },
        "chunked_upload_urls": []
    }
}

Delete

Delete a File

DELETE https://uc.alxgsv.com/api/v1/projects/:project_id/files/:file_id.json

Authentication specifics Files can be accessed either by Project's secret key or by File's access token.

curl -X DELETE -H "Authorization: Bearer ${SECRET_KEY}" https://uc.alxgsv.com/api/v1/projects/${PROJECT_ID}/files/${FILE_ID}.json

Path Parameters

Name

Type

Description

project_id*

String

file_id*

String

Headers

Name

Type

Description

Authorization*

String

Bearer SECRET_KEY or Bearer ACCESS_TOKEN

{
    "data": {
        "type": "files",
        "id": "f-aSNfnv1GIC1GVwTSdBXIv1",
        "attributes": {
            "uuid": "1687bbf8-b3ca-4323-b4c8-5e5f803bad82",
            "is_image": true,
            "status": "ready",
            "mime": {
                "mime": "image/png",
                "type": "image",
                "subtype": "png"
            },
            "original_url": "https://ucarecdn.com/1687bbf8-b3ca-4323-b4c8-5e5f803bad82/SCR20231117qnol.png",
            "original_name": "SCR-20231117-qnol.png",
            "size": 14,
            "original_protected": true,
            "chunked_upload": {
                "is_chunked_upload": false,
                "chunk_size": null,
                "is_complete": false
            },
            "metadata": {
                "foo": "bar"
            },
            "content": {
                "image": {
                    "dpi": [
                        144,
                        144
                    ],
                    "width": 378,
                    "format": "PNG",
                    "height": 352,
                    "sequence": false,
                    "color_mode": "RGBA",
                    "orientation": null,
                    "geo_location": null,
                    "datetime_original": null
                },
                "video": null
            },
            "created_at": "2023-11-26T09:27:28.398Z",
            "uploaded_at": "2023-11-26T09:27:27.850838Z",
            "removed_at": "2023-11-27T08:38:39.000Z",
            "expires_at": 
        },
        "relationships": {
            "project": {
                "data": {
                    "type": "projects",
                    "id": "8a540ce633522d881e97"
                }
            }
        },
        "authentication": {
            "access_token": "fat-cUcMtSV4xOcbPBNsWAS5Fs"
        },
        "chunked_upload_urls": []
    }
}

Last updated 2 years ago

hashtagList

hashtagList Files

hashtagPath Parameters

hashtagHeaders

hashtagDirect uploads

hashtagDirect File upload

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagInternet uploads

hashtagUpload File from the internet

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagChunked uploads

hashtagStart Chunked upload

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagUpload one File chunk

hashtagFinalize Chunked upload

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagView

hashtagView File

hashtagPath Parameters

hashtagHeaders

hashtagUpdate

hashtagUpdate a File

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagDelete

hashtagDelete a File

hashtagPath Parameters

hashtagHeaders

List

List Files

Path Parameters

Headers

Direct uploads

Direct File upload

Path Parameters

Headers

Request Body

Internet uploads

Upload File from the internet

Path Parameters

Headers

Request Body

Chunked uploads

Start Chunked upload

Path Parameters

Headers

Request Body

Upload one File chunk

Finalize Chunked upload

Path Parameters

Headers

Request Body

View

View File

Path Parameters

Headers

Update

Update a File

Path Parameters

Headers

Request Body

Delete

Delete a File

Path Parameters

Headers