Files [v2]

List Files

Endpoint:

URL	`/api/v2/files/`
Method	`GET`
Expected response code	`200`
Expected response type	`JSON`

Example:

BASH

curl -v \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/files/

Example response:

File list JSON

JSON

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 148
    },
    "objects": [
        {
            "aspects": {
                "letterout": {
                    "date": "2016-10-10T00:00:00"
                }
            },
            "digest": "9466839db23434b227368ef661b92249",
            "dynatype": {
                "caption_plural": "dynatypes_labels:MeetingNote_plural:",
                "caption_singular": "dynatypes_labels:MeetingNote_singular:",
                "id": "90b0ec58-86fb-11e6-b9c5-4b05689b8c93",
                "title": "MeetingNote"
            },
            "filename": "Meeting notes.pdf",
            "folder": "",
            "id": "2bb7fb5e-8ef6-11e6-89e1-87ce876944be",
            "mime_type": "application/pdf",
            "parent": "07dcc00c-897e-11e6-b174-db079186c95c",
            "project": {
                "id": "07b4c6c4-897e-11e6-b174-2386ea6a6cb1",
                "identifier": "2016-13",
                "title": "Board meeting"
            },
            "resource_uri": "/api/v2/files/2bb7fb5e-8ef6-11e6-89e1-87ce876944be/",
            "size": 27655,
            "snapshot_id": "2bb8dd8a-8ef6-11e6-89e1-03c0dbcab4b1",
            "space": {
                "id": "b895b576-895a-11e6-90e8-cf6626673e98",
                "title": "Board management"
            },
            "tags": [],
            "template": null,
            "title": "Meeting notes",
            "type": "File",
            "userhome": null,
            "version": "0.1",
        },
        // ...
    ]
}

List Favourite Files

See User home | List-favourite-Files.

Get File details

Show details about an existing File.

Endpoint:

URL	`/api/v2/files/$file_id/`
Method	`GET`
Expected response code	`200`
Expected response type	`JSON`

URL parameters:

file_id – is a File ID (UUID).

Example:

BASH

file_id=e139a8ac-7368-11ee-b992-57663b1559fb

curl -v \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/files/$file_id/

Example response:

File details JSON

JSON

{
    "aspects": {},
    "blob_name": "103d0b48a25b4197bb3b90bc462abc29",
    "category": "main",
    "created": "2023-10-25T19:01:18",
    "created_by": "Administrator Administrator",
    "description": "",
    "digest": "4b41a3475132bd861b30a878e30aa56a",
    "dynatype": {
        "caption_plural": "dynatypes_labels:File_plural:",
        "caption_singular": "dynatypes_labels:File_singular:",
        "id": "6d19dacc-71cf-11ee-b1e9-8f8e8372e41a",
        "title": "File"
    },
    "filename": "sample.pdf",
    "fileplan": "",
    "fileplan_title": "",
    "folder": "",
    "id": "e139a8ac-7368-11ee-b992-57663b1559fb",
    "mime_type": "application/pdf",
    "modified": "2023-10-25T19:01:18",
    "modified_by": "Administrator Administrator",
    "owner": null,
    "parent": "313ae0be-71cf-11ee-b1e9-ebd554949e29",
    "path": "/domain/spaces/Spaces/Space/Projects/Project/2023-3/sample.pdf",
    "project": {
        "id": "3122576a-71cf-11ee-848e-b7be3292bc02",
        "identifier": "2023-3",
        "title": "Document title"
    },
    "resource_uri": "/api/v2/files/e139a8ac-7368-11ee-b992-57663b1559fb/",
    "size": 3028,
    "snapshot_id": "e139e880-7368-11ee-b992-4bf81dd1b7a4",
    "space": {
        "id": "2a3b87be-71cf-11ee-a5ea-1b559886a85c",
        "title": "Space"
    },
    "tags": [],
    "template": null,
    "title": "sample",
    "type": "File",
    "userhome": null,
    "version": "0.1"
}

Download File content

Endpoint:

URL	`/api/v2/files/$file_id/content/`
Method	`GET`
Expected response code	`302`

URL parameters:

file_id – is the ID of the File to download content from.

Example:

BASH

file_id=e139a8ac-7368-11ee-b992-57663b1559fb

curl -v \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/files/$file_id/content/

In response it is expected to get code 302 Found, and the Location header should contain the direct link to the File content like this:

CODE

Location: https://tenant.coredata.is/laika/103d0b48a25b4197bb3b90bc462abc29?response-content-disposition=%20attachment%3B%20filename%2A%3Dutf-8%27%27sample.pdf&response-content-type=application%2Fpdf&AWSAccessKeyId=s3f%3Amyuser&Expires=1698326799&Signature=3TfPcpCwS8FrZExv%2FHfzERYFXAA%3D

The URL above should be used to download the content like this:

CODE

curl -v \
    "https://tenant.coredata.is/laika/103d0b48a25b4197bb3b90bc462abc29?response-content-disposition=%20attachment%3B%20filename%2A%3Dutf-8%27%27sample.pdf&response-content-type=application%2Fpdf&AWSAccessKeyId=s3f%3Amyuser&Expires=1698326799&Signature=3TfPcpCwS8FrZExv%2FHfzERYFXAA%3D"

The request above should return the content itself and the headers like these:

CODE

...
< Content-Type: application/pdf
< Content-Length: 3028
< Last-Modified: Wed, 25 Oct 2023 19:01:17 GMT
< Content-Disposition: attachment; filename*=utf-8''sample.pdf
< Accept-Ranges: bytes

Create File

Create a File in a Project, Folder or Filespace.

Create File by uploading content to CoreData

Endpoint:

URL	`/api/v2/files/`
Method	`POST`
Content-Type	`multipart/form-data`
Expected response code	`201`

The endpoint accepts the following parameters:

Parameter	Type	Description	Mandatory
`content`	`Bytes`	The binary content of the file. Example: `<binary content>`.	Yes
`filename`	`String`	The name of the file to be uploaded. Example: `sample.pdf`.	Yes
`title`	`String`	The title of the File. Filename without ending. Example: `Sample document`.	Yes
`parent`	`String`	ID of the parent, e.g. of a `Filespace`, `Project` or `Folder` etc.	Yes
`dynatype`	`String`	Name of the `Dynatype` to use. Example: `Memo`. See list of available dynatypes below.	No
`contacts`	`String`	A comma separated list of contact IDs. Requires `dynatype` parameter to be specified, see details below.	No
`tags`	`String`	A comma separated list of tags. Example: `tag1, another, one long tag`.	No

Response Location header contains URL of newly created File. The ID of the File can be derived from the Location, for example in a File URL [...]/api/v2/files/389a5280-8efc-11e6-a6e0-2f4ee7e36368/, the 389a5280-8efc-11e6-a6e0-2f4ee7e36368 is the ID of the created File.

Selecting a dynatype is optional, if no parameter is provided, then CoreData will use the dynatype File by default. Some predefined dynatype for files are:

File
Contract
LetterIn
LetterOut
Memo
Other
Report

The contacts will not be linked with the file if File dynatype is used.

Example:

BASH

filename=sample.pdf
filepathname=~/sample.pdf
title="Sample document"
parent=313ae0be-71cf-11ee-b1e9-ebd554949e29

curl -v \
    -X POST \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: multipart/form-data" \
    -F "content=@$filepathname" \
    -F "filename=$filename" \
    -F "title=$title" \
    -F "parent=$parent" \
    $COREDATA_BASE_URL/api/v2/files/

Where:

filepathname – path and name of a local file to upload;
filename – the name of the new File to be created in CoreData;
title – the title of the new File to be created in CoreData;
parent – the container in of the new File, can be ID of either Filespace, Project or Folder.

The response contains Location header which looks like this:

CODE

Location: /api/v2/files/cb2cca52-7422-11ee-91ce-dff1c719d262/

Where the value of the reader contains the newly created file’s URL path on the target CoreData instance. The new File’s ID cb2cca52-7422-11ee-91ce-dff1c719d262 can be extracted from the Location header value.

For more information see:

Dynatypes document model.

Create File by uploading content directly to document storage server

The upload of file content directly to document storage server includes 3 steps which are described in details below. Here is an example combining all steps, creating a file within a project:

BASH

# Step 1 – Create a new BLOB.
# Note that a v3 endpoint is used to upload file content.
# There is no such alternative in v2.
filepathname=sample.pdf
content_length=$(stat -f%z "$filepathname")
content_type=application/pdf

blob_info=$(curl -v \
    -X POST -G \
    -H "Authorization: apikey $API_KEY" \
    --data-urlencode "content_type=$content_type" \
    --data-urlencode "content_length=$content_length" \
    $COREDATA_BASE_URL/api/v3/blob/presigned-upload-url/)

blob_name=$(echo $blob_info | jq .blobName | tr -d '"')
presigned_url=$(echo $blob_info | jq .presignedUrl | tr -d '"')

# Step 2 – Upload file content to storage backend
curl -v \
    -X PUT \
    -H "Content-Type: $content_type" \
    -H "Slug: $filename" \
    --data-binary "@$filepathname" \
    $presigned_url

# Step 3 – Create file
title="Sample document"
project_id=01350bc0-7971-11ee-bf90-138377a015b3

curl -v \
    -X POST \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: multipart/form-data" \
    -F "blob_name=$blob_name" \
    -F "filename=$filename" \
    -F "title=$title" \
    -F "parent=$project_id" \
    $COREDATA_BASE_URL/api/v2/files/

The previous example is explained in details below.

Step 1 – Create a new BLOB

First create a new BLOB via Files [v3] | Create-File-BLOB and get a response with a JSON like this:

CODE

{
    "blobName": "98c59d020fe547b08cd0df36b1c01b37",
    "presignedUrl": "https://home.coredata.is/laika/98c59d020fe547b08cd0df36b1c01b37?AWSAccessKeyId=s3f%3Amyuser&Expires=1698929283&Signature=vjbmLRn1MjwLVAuYRP8pY9TvNtc%3D"
}

Where:

presignedUrl – field containing a URL for file content upload used on Step 2 – Upload file content to storage backend below.
blobName – contains the newly created BLOB name used on Step 3 – Create file below.

Step 2 – Upload file content to storage backend

Using the presignedUrl obtained on the previous step Step 1 – Create a new BLOB, here we should upload file content directly to storage backend. The presignedUrl directs to the following endpoint:

URL	`<presignedUrl>`
Method	`PUT`
Content-Type	MIME type of the BLOB
Expected response code	`201`

Step 3 – Create file

Using the Create File endpoint described above create a new File. The only exception is that instead of the content parameter the blob_name should be provided which must contain value of blobName obtained earlier on Step 1 – Create a new BLOB above.

Update File metadata

This endpoint allows editing of a File’s metadata, not its content.

Endpoint:

URL	`/api/v2/files/$file_id/`
Method	`PUT`
Content-Type	`application/json`
Expected response code	`204`

URL parameters:

file_id – is a placeholder for an existing File ID.

The endpoint accepts a JSON with the following fields:

Parameter	Type	Description	Mandatory
`filename`	`String`	The name of the file to be uploaded. Example: `sample.pdf`.	Yes
`title`	`String`	The title of the File. Filename without ending. Example: `Sample document`.	Yes
`parent`	`String`	The uuid of the parent, e.g. of a `Filespace`, `Project` or `Folder`. Example: `291972c4-9cf3-11e5-b7b3-5cf938a42124`.	Yes
`dynatype`	`String`	Name of the `Dynatype` to use. Example: `Memo`.	No
`contacts`	`String`	A comma separated list of contact UUIDs. Example: `d3383d1a-d0e8-11e6-b3f8-339d6545b0f5`.	No
`tags`	`String`	A comma separated list of tags. Example: `tag1, another, one long tag`.	No

Example:

BASH

file_id=a3ddc64a-7422-11ee-b596-6b440b17d53b
title="Sample document (updated)"
filename=sample-updated.pdf
parent=30bdbf12-71cf-11ee-a5ea-a7771304e664

curl -v \
    -X PUT \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"title\": \"$title\", \"filename\": \"$filename\", \"parent\": \"$parent\"}" \
    $COREDATA_BASE_URL/api/v2/files/$file_id/

Where:

file_id – ID of a File to update metadata for;
title – new File title to set;
filename – new filename for the File;
parent – ID of the File’s parent to set, the file will be moved if another parent ID is be specified.

Update File content

Update content of an existing File.

Endpoint:

URL	`/api/v2/files/$file_id/content/?filename=$filename`
Method	`PUT`
Content-Type	`application/octet-stream`
Expected response code	`201`

URL parameters:

file_id – ID of an existing File;
filename – the name of a file to be uploaded (optional, if file extension is changed during re-upload then the new extension is taken from filename parameter).

URL optional parameters:

snapshot_id – document version to update. Is used for document version control, the upload operation will fail if the last document snapshot_id on the backend differs from the values passed in the parameter;
blob_name – name of pre-uploaded content, see Files [v3] | Create-File-BLOB (requires digest parameter to be passed as well, see below);
digest – digest of the pre-uploaded content, must be used together with the blob_name parameter.

Request body must contain the new file content to upload if no blob_name parameter is provided.

Example via uploading file content to CoreData

Example:

BASH

file_id=a3ddc64a-7422-11ee-b596-6b440b17d53b
filename=sample.pdf
filepathname=~/$filename

curl -v \
    -X PUT -G \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    -H "Content-Type: application/octet-stream" \
    --data-binary "@$filepathname" \
    $COREDATA_BASE_URL/api/v2/files/$file_id/content/?filename=$filename

Where:

file_id – ID of a File to upload content for;
filename – new filename for the File;
filepathname – path and name of a local file to upload content from.

The response contains useful headers, here are some of them:

X-Coredata-fields-filedigest: d41d8cd98f00b204e9800998ecf8427e – the uploaded content’s digest to check;
X-Coredata-fields-snapshot-id: 25d74cea-7430-11ee-91ce-b785f71967fe – the new File version’s snapshot ID.

Example via uploading file content to storage server

Example:

BASH

# Step 1 – Create a new BLOB.
# Note that a v3 endpoint is used to upload file content.
# There is no such alternative in v2.
filename=sample.pdf
filepathname=~/$filename
content_length=$(stat -f%z "$filepathname")
content_type=application/pdf

blobInfo=$(curl -v \
    -X POST -G \
    -H "Authorization: apikey $API_KEY" \
    --data-urlencode "content_type=$content_type" \
    --data-urlencode "content_length=$content_length" \
    $COREDATA_BASE_URL/api/v3/blob/presigned-upload-url/)

# Step 2 – Upload file content to storage backend
blob_name=$(echo $blobInfo | jq .blobName | tr -d '"')
presigned_url=$(echo $blobInfo | jq .presignedUrl | tr -d '"')

curl -v \
    -X PUT \
    -H "Content-Type: $content_type" \
    -H "Slug: $filename" \
    --data-binary "@$filepathname" \
    $presigned_url

# Step 3 – Update content of existing file
file_id=58321016-8796-11ee-bd02-83c3e72c591e
filedigest=`openssl md5 $filepathname | awk '{print $2}'`

curl -v \
    -X PUT \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    "$COREDATA_BASE_URL/api/v2/files/$file_id/content/?blob_name=$blob_name&digest=$filedigest"

Delete File

Delete an existing File.

Endpoint:

URL	`/api/v2/files/$file_id/`
Method	`DELETE`
Expected response code	`204`

URL parameters:

file_id – the ID of an existing File to delete.

Example:

BASH

file_id=e139a8ac-7368-11ee-b992-57663b1559fb

curl -v \
    -X DELETE \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/files/$file_id/

List Files in a Project

Get list of files in a project.

Endpoint:

URL	`/api/v2/projects/$project_id/files/`
Method	`GET`
Expected response code	`200`
Expected response type	`JSON`

URL parameters:

project_id – ID of an existing project to get list of files from.

Example:

BASH

project_id=3122576a-71cf-11ee-848e-b7be3292bc02

curl -v \
    -H "Authorization: apikey $API_USER:$API_KEY" \
    $COREDATA_BASE_URL/api/v2/projects/$project_id/files/

Example response:

Project's File list JSON

JSON

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "aspects": {},
            "blob_name": "73940fa7c3aa49e4a4416887c0cdd6c3",
            "category": "main",
            "created": "2023-10-26T17:12:08",
            "created_by": "Administrator Administrator",
            "description": "",
            "digest": "4b41a3475132bd861b30a878e30aa56a",
            "dynatype": {
                "caption_plural": "dynatypes_labels:File_plural:",
                "caption_singular": "dynatypes_labels:File_singular:",
                "id": "6d19dacc-71cf-11ee-b1e9-8f8e8372e41a",
                "title": "File"
            },
            "filename": "sample.pdf",
            "fileplan": "",
            "fileplan_title": "",
            "folder": "",
            "id": "cb2cca52-7422-11ee-91ce-dff1c719d262",
            "mime_type": "application/pdf",
            "modified": "2023-10-26T17:12:08",
            "modified_by": "Administrator Administrator",
            "owner": null,
            "parent": "313ae0be-71cf-11ee-b1e9-ebd554949e29",
            "path": "/domain/spaces/Space folder/Space with projects/Projects/Project with files/2023-3/sample.pdf",
            "project": {
                "id": "3122576a-71cf-11ee-848e-b7be3292bc02",
                "identifier": "2023-3",
                "title": "Project with files"
            },
            "resource_uri": "/api/v2/files/cb2cca52-7422-11ee-91ce-dff1c719d262/",
            "size": 3028,
            "snapshot_id": "cb2ce4ce-7422-11ee-91ce-3be7d5677268",
            "space": {
                "id": "2a3b87be-71cf-11ee-a5ea-1b559886a85c",
                "title": "Space with projects"
            },
            "tags": [],
            "template": null,
            "title": "Sample document",
            "type": "File",
            "userhome": null,
            "version": "0.1"
        }
    ]
}

Create Comment for a File

See Comments | Create-Comment.

Contents

List Files

List Favourite Files

Get File details

Download File content

Create File

Create File by uploading content to CoreData

Create File by uploading content directly to document storage server

Step 1 – Create a new BLOB

Step 2 – Upload file content to storage backend

Step 3 – Create file

Update File metadata

Update File content

Example via uploading file content to CoreData

Example via uploading file content to storage server

Delete File

List Files in a Project

Create Comment for a File