File upload

CCA supports two ways of uploading an image, (1) a "direct" upload, i.e. all the bytes are uploaded using an AWS S3 pre-signed URL created by CCA and (2) a more "client oriented" upload that make use of tus (which among other things enables "resumable uploads") to upload files. The examples in the documentation uses cURL to show how the API works. You can optionally specify a filename (shown in 1.2).

Upload file - direct mode

Upload the bytes of the file at once (in one request).

1: Create upload

Initiate direct upload.

Request

curl --location --request POST 'https://cca-eu-west-1.saas-stage.infomaker.io/twirp/cca.Files/CreateUpload' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{}'

Response

HTTP/2 200
content-type: application/json; charset=utf-8
{
    "uploadId": "29f9e665-180a-488b-a289-c6ad06db754d",
    "uploadUrl": "{PRESIGNED_PUT_URL}"
}

Note the uploadId in the response, this id is used in requests for getting status, creating document for file etc.

1.2: Create upload with filename

You can optionally add a filename to the request, which later will be used when a default naviga document is created (which is produced and available as an artifact).

Request

curl --location --request POST 'https://cca-eu-west-1.saas-stage.infomaker.io/twirp/cca.Files/CreateUpload' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{"filename":"my_very_special_filename.jpeg"}'

2: Upload file

Use the pre-signed upload URL and PUT to upload the bytes.

Request

curl --location --request PUT '{PRESIGNED_PUT_URL}' \
--header 'Content-Type: {IMAGE_CONTENT_TYPE}' \
--data-binary '@{FILE_TO_UPLOAD}}'

Response

HTTP/2 200

3. Get Status for upload

Note that before you can start polling for status, the actual file upload (see previous request) must have finished (polling for status has to do with the processing of the uploaded file).

In order to know when the processing of the uploaded file has been done, you need to poll CCA for status.

Request

curl --location --request POST 'https://cca-eu-west-1.saas-stage.infomaker.io/twirp/cca.Files/GetStatus' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "uploadId": "{UPLOAD_ID}"
}'

Response

Until CCA is done processing the upload, the response would be:

HTTP/2 200
content-type: application/json; charset=utf-8
{
    "status": "IN_PROGRESS"
}

When the file has been successfully uploaded, CCA will respond with:

HTTP/2 200
content-type: application/json; charset=utf-8
{
    "status": "DONE",
    "manifest": {
        "uuid": "ee0552c8-a547-59a2-8fc0-c069f624093a",
        "hashedFilename": "hW5kiMRr8wjjmlQEjqDyx9csCOg.jpg",
        "uri": "im://image/hW5kiMRr8wjjmlQEjqDyx9csCOg.jpg",
        "contentClass": "image",
        "artifacts": [{
            "type": "image",
            "name": "hW5kiMRr8wjjmlQEjqDyx9csCOg.jpg",
            "mimeType": "image/jpeg"
        }, {
            "type": "navigadoc",
            "name": "hW5kiMRr8wjjmlQEjqDyx9csCOg.json",
            "mimeType": "application/json"
        }, {
            "type": "thumb",
            "name": "thumb/hW5kiMRr8wjjmlQEjqDyx9csCOg.jpg",
            "mimeType": "image/jpg"
        }, {
            "type": "preview",
            "name": "preview/hW5kiMRr8wjjmlQEjqDyx9csCOg.jpg",
            "mimeType": "image/jpg"
        }]
    }
}

As part of the response, CCA has created a manifest for the uploaded file including:

  • uuid - The v5 uuid to use when creating a document corresponding with the file (see below)

  • hashedFilename - The hashed name for the file

  • uri - The uri for the file (used to calculate the uuid)

  • contentClass - Type of file

  • artifacts - These are the different artifacts created as part of the uploading of the file

If there was an error uploading the file, CCA will respond with "status": "ERROR" and an error message.

4. Get artifact (optional)

The artifacts described in the manifest can now be fetched if desired as described below.

Request

curl --location --request POST 'https://cca-eu-west-1.saas-stage.infomaker.io/twirp/cca.Files/GetArtifact' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "uploadId": "{UPLOAD_ID}",
    "name": "{ARTIFACT_NAME}"
}'

Response

HTTP/2 200
content-type: application/json; charset=utf-8
{"content":"W3sKICAiU291cmNlRmlsZSI6ICIvdG1wLzRlNGVkMWRkYWE1OGZjMzc4YjVlNjUzNGQxMTUxOTliMTQ5OTU4NDc2IiwKICAiRXhpZlRvb2xWZXJzaW9uIjogMTEuNjUsCiAgIkZpbGVOYW1lIjogIjRlNGVkMWRkYWE1OGZjMzc4YjVlNjUzNGQxMTUxOTliMTQ5OTU4NDc2IiwKICAiRGlyZWN0b3J5IjogIi90bXAiLAogICJGaWxlU2l6ZSI6ICIzLjQgTUIiLAogICJGaWxlTW9kaWZ5RGF0ZSI6ICIyMDIwOjAzOjAyIDEzOjQxOjM3KzAwOjAwIiwKICAiRmlsZUFjY2Vzc0RhdGUiOiAiMjAyMDowMzowMiAxMzo0MTozNyswMDowMCIsCiAgIkZpbGVJbm9kZUNoYW5nZURhdGUiOiAiMjAyMDowMzowMiAxMzo0MTozNyswMDowMCIsCiAgIkZpbGVQZXJtaXNzaW9ucyI6ICJydy0tLS0tLS0iLAogICJGaWxlVHlwZSI6ICJKUEVHIiwKICAiRmlsZVR5cGVFeHRlbnNpb24iOiAianBnIiwKICAiTUlNRVR5cGUiOiAiaW1hZ2UvanBlZyIsCiAgIkltYWdlV2lkdGgiOiAyMDAwLAogICJJbWFnZUhlaWdodCI6IDE0MDAsCiAgIkVuY29kaW5nUHJvY2VzcyI6ICJCYXNlbGluZSBEQ1QsIEh1ZmZtYW4gY29kaW5nIiwKICAiQml0c1BlclNhbXBsZSI6IDgsCiAgIkNvbG9yQ29tcG9uZW50cyI6IDMsCiAgIllDYkNyU3ViU2FtcGxpbmciOiAiWUNiQ3I0OjI6MCAoMiAy

Note! The response in content is base64 encoded.

5. Create file document

The file has now been uploaded. Next step is to create a NavigaDoc document with the metadata for the file. CCA has created, as part of the artifacts in the manifest, a NavigaDoc document including the metadata that has been extracted from the binary. The NavigaDoc document can be used by downloading the artifact with type navigadoc. This document can then be uploaded to CCA (either as-is or updated with own data if necessary).

The request and response for creating a document is described in the "Documents" part of the API documentation.

Upload file - patch mode

Upload the bytes of the file in chunks (PATCH). CCA uses the TUS protocol which supports "resumable uploads". There are a number of TUS clients available at the Official TUS site.

1: Create upload

Initiate patch upload.

Request

curl --location --request POST 'https://cca-eu-west-1.saas-stage.infomaker.io/files/' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Upload-Length: {FILE_SIZE}' \
--header 'Tus-Resumable: 1.0.0'

Response

HTTP/2 201
location: https://cca-eu-west-1.saas-stage.infomaker.io/files/4e4ed1ddaa58fc378b5e6534d115199b+PDrE71KbY_sJHmaC1ZR6ZTFkmTswW...

2. Start the upload

Now that the upload has been initiated, start uploading the actual bytes. Use the URL in the location header from the response in step 1 as the {UPLOAD_URL}.

Note that this is a PATCH, and you can upload any number of bytes per request.

Request

curl --location --request PATCH '{UPLOAD_URL}' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Length: {LENGTH}' \
--header 'Upload-Offset: 0' \
--header 'Tus-Resumable: 1.0.0' \
--header 'Content-Type: application/offset+octet-stream' \
--data-binary '@{FILE_NAME}'

Response

HTTP/2 204
upload-offset: 3525278

3. Get status, artifacts and create file documents

Note that before you can start polling for status, the actual file upload (see previous request) must have finished (polling for status has to do with the processing of the uploaded file).

These steps are the same as described for "Upload file - direct mode" above.

Note that the {UPLOAD_ID} is fetched from the response header location in the first request. The actual id is a part of the url, between the .../files/ and the + sign (see example below).

Given this URL:

https://cca-eu-west-1.saas-stage.infomaker.io/files/7d4b5ce4eaa7041229bcb97e01634058+XiLOusuVToLATVRO2LKG8kMYexSfd...

{UPLOAD_ID} would be:

7d4b5ce4eaa7041229bcb97e01634058
PreviousNewsMLDocumentsNextFiles

Last updated