Files

Endpointhttps://api.kontier.eu/v1

Start a file upload

POST

https://api.kontier.eu/v1

/files

Registers the document and returns a URL to upload its bytes to, valid for 15 minutes. Call the confirm endpoint afterwards: until you do, the document is not visible anywhere, because the server has not yet checked that the bytes match what you declared. An upload that is never confirmed is discarded automatically after an hour.

Start a file upload › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

Start a file upload › Request Body

category

string · required

What the document is. Decides the size cap and the accepted formats.

declared_content_type

string · required

The format you believe the file is. The server checks the file's actual bytes when you confirm the upload, and rejects a file that disagrees.

declared_size

integer · int64 · min: 1 · required

The file's size in bytes. Checked against the limit for this category before the upload starts, and again against the real size afterwards.

filename

string · minLength: 1 · maxLength: 255 · required

The file's name, shown in lists.

owner_id

string · uuid · required

The owning record's UUID.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

owner_kind

string · required

What this document hangs off.

visibility

string · enum

Defaults to internal. Set shared to also show the document to the customer.

Enum values:

internal

shared

Start a file upload › Responses

object · required

POST/files

curl --request POST \
  --url https://api.kontier.eu/v1/files \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "category": "category",
  "declared_content_type": "declared_content_type",
  "declared_size": 1,
  "filename": "filename",
  "owner_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "owner_kind": "owner_kind",
  "visibility": "internal"
}
'

shell

Example Request Body

{
  "category": "category",
  "declared_content_type": "declared_content_type",
  "declared_size": 1,
  "filename": "filename",
  "owner_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "owner_kind": "owner_kind",
  "visibility": "internal"
}

json

Example Responses

{
  "data": {
    "expires_at": "2024-08-25T15:00:00Z",
    "file": {
      "byte_size": 0,
      "category": "category",
      "content_sha256": "content_sha256",
      "content_type": "content_type",
      "created_at": "2024-08-25T15:00:00Z",
      "declared_content_type": "declared_content_type",
      "filename": "filename",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "owner_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "owner_kind": "owner_kind",
      "retention_until": "2024-08-25T15:00:00Z",
      "source": "source",
      "status": "status",
      "uploaded_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "visibility": "visibility"
    },
    "upload_url": "upload_url"
  }
}

json

application/json

Delete a file

DELETE

https://api.kontier.eu/v1

/files/{id}

Removes the document immediately from every list and revokes any download link. The stored bytes are erased shortly afterwards.

Delete a file › path Parameters

id

string · uuid · required

File UUID

Delete a file › query Parameters

reason

string · maxLength: 200

Optional note recorded with the deletion.

Delete a file › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a file › Responses

No Content

No data returned

Change whether a file is shared with the customer

PATCH

https://api.kontier.eu/v1

/files/{id}

Visibility is the only editable field. The name, the category and the record a document belongs to are fixed when it is uploaded.

Change whether a file is shared with the customer › path Parameters

id

string · uuid · required

File UUID

Change whether a file is shared with the customer › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Change whether a file is shared with the customer › Request Body

visibility

string · enum · required

internal keeps the document on the operator surfaces; shared also shows it to the customer.

Enum values:

internal

shared

Change whether a file is shared with the customer › Responses

object · required

PATCH/files/{id}

curl --request PATCH \
  --url https://api.kontier.eu/v1/files/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "visibility": "internal"
}
'

shell

Example Request Body

{
  "visibility": "internal"
}

json

Example Responses

{
  "data": {
    "byte_size": 0,
    "category": "category",
    "content_sha256": "content_sha256",
    "content_type": "content_type",
    "created_at": "2024-08-25T15:00:00Z",
    "declared_content_type": "declared_content_type",
    "filename": "filename",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "owner_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "owner_kind": "owner_kind",
    "retention_until": "2024-08-25T15:00:00Z",
    "source": "source",
    "status": "status",
    "uploaded_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "visibility": "visibility"
  }
}

json

application/json

Confirm an uploaded file

POST

https://api.kontier.eu/v1

/files/{id}/confirm

Checks the uploaded bytes — their size, their real format and their checksum — and makes the document available. Returns 422 when the file is not what was declared or is not an accepted format for its category; the document is then held aside rather than published, and cannot be downloaded.

Confirm an uploaded file › path Parameters

id

string · uuid · required

File UUID

Confirm an uploaded file › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Confirm an uploaded file › Responses

object · required

POST/files/{id}/confirm

curl --request POST \
  --url https://api.kontier.eu/v1/files/:id/confirm \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "byte_size": 0,
    "category": "category",
    "content_sha256": "content_sha256",
    "content_type": "content_type",
    "created_at": "2024-08-25T15:00:00Z",
    "declared_content_type": "declared_content_type",
    "filename": "filename",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "owner_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "owner_kind": "owner_kind",
    "retention_until": "2024-08-25T15:00:00Z",
    "source": "source",
    "status": "status",
    "uploaded_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "visibility": "visibility"
  }
}

json

application/json

Get a download link for a file

GET

https://api.kontier.eu/v1

/files/{id}/url

Returns a temporary link to the file's bytes, valid for 5 minutes. Only available once the upload has been confirmed.

Get a download link for a file › path Parameters

id

string · uuid · required

File UUID

Get a download link for a file › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a download link for a file › Responses

object · required

Email Legal Identity

Start a file upload

POST

https://api.kontier.eu/v1

/files

Start a file upload › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Start a file upload › Request Body

category

string · required

What the document is. Decides the size cap and the accepted formats.

declared_content_type

string · required

The format you believe the file is. The server checks the file's actual bytes when you confirm the upload, and rejects a file that disagrees.

declared_size

integer · int64 · min: 1 · required

The file's size in bytes. Checked against the limit for this category before the upload starts, and again against the real size afterwards.

filename

string · minLength: 1 · maxLength: 255 · required

The file's name, shown in lists.

owner_id

string · uuid · required

The owning record's UUID.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

owner_kind

string · required

What this document hangs off.

visibility

string · enum

Defaults to internal. Set shared to also show the document to the customer.

Enum values:

internal

shared

Start a file upload › Responses

object · required

Delete a file

DELETE

https://api.kontier.eu/v1

/files/{id}

Removes the document immediately from every list and revokes any download link. The stored bytes are erased shortly afterwards.

Delete a file › path Parameters

id

string · uuid · required

File UUID

Delete a file › query Parameters

reason

string · maxLength: 200

Optional note recorded with the deletion.

Delete a file › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a file › Responses

No Content

No data returned

Change whether a file is shared with the customer

PATCH

https://api.kontier.eu/v1

/files/{id}

Visibility is the only editable field. The name, the category and the record a document belongs to are fixed when it is uploaded.

Change whether a file is shared with the customer › path Parameters

id

string · uuid · required

File UUID

Change whether a file is shared with the customer › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Change whether a file is shared with the customer › Request Body

visibility

string · enum · required

internal keeps the document on the operator surfaces; shared also shows it to the customer.

Enum values:

internal

shared

Change whether a file is shared with the customer › Responses

object · required

Confirm an uploaded file

POST

https://api.kontier.eu/v1

/files/{id}/confirm

Confirm an uploaded file › path Parameters

id

string · uuid · required

File UUID

Confirm an uploaded file › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Confirm an uploaded file › Responses

object · required

Get a download link for a file

GET

https://api.kontier.eu/v1

/files/{id}/url

Returns a temporary link to the file's bytes, valid for 5 minutes. Only available once the upload has been confirmed.

Get a download link for a file › path Parameters

id

string · uuid · required

File UUID

Get a download link for a file › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a download link for a file › Responses

object · required