Upload

The Upload API handles document ingestion. Submit your file details to initiate an upload session — the platform returns an upload URL and manages the transfer. Once confirmed, your file is available for processing.

Supported File Types

Type	MIME Type
PDF	`application/pdf`
JPEG	`image/jpeg`
PNG	`image/png`
WebP	`image/webp`
DOCX	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
PPTX	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
XLSX	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
EPUB	`application/epub+zip`
RTF	`application/rtf`
ODT	`application/vnd.oasis.opendocument.text`
CSV	`text/csv`
TXT	`text/plain`

Maximum file size: 50 MB (52,428,800 bytes)

Upload Flow

Call POST /v1/upload/initiate to start a session — you'll receive an upload_url and a file_id
Upload your file to the returned upload_url via a PUT request
The platform automatically confirms the upload and marks the file as ready
Your file is now ready to use — proceed to the Process API

Endpoints

POST /v1/upload/initiate

Initiates an upload session and returns a URL to upload your file directly.

Request Body

Field	Type	Required	Description
`filename`	string	Yes	Original filename including extension (e.g. `invoice.pdf`)
`mimetype`	string	Yes	MIME type of the file (must be a supported type)
`bytes`	number	Yes	File size in bytes (must be ≤ 52,428,800)
`schema_id`	string	No	Optional schema UUID to associate with this file at upload time

curl -X POST \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "invoice_2024_01.pdf",
    "mimetype": "application/pdf",
    "bytes": 245760
  }' \
  "https://api.exelensia.com/v1/upload/initiate"

Response

{
  "file_id": "019760a0-0020-7000-8000-000000000020",
  "upload_url": "https://uploads.exelensia.com/teams/019760a0-0000-7000-8000-000000000000/019760a0-0020-7000-8000-000000000020.pdf?token=...&expires=1706961600",
  "expires_in": 900
}

Field	Description
`file_id`	UUID of the created file record — use this when calling the Process API
`upload_url`	Upload URL — valid for `expires_in` seconds (15 minutes)
`expires_in`	Seconds until the upload URL expires

Uploading Your File

After receiving the upload_url, upload the file using a PUT request with the exact Content-Type you specified:

curl -X PUT \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice_2024_01.pdf \
  "https://uploads.exelensia.com/..."

Important: Use PUT, not POST. The Content-Type header must match the mimetype you specified in the initiate request.

Status Codes

Status	Description
`201`	Upload session created, upload URL returned
`400`	Invalid request body, unsupported mimetype, or file too large
`401`	Missing or invalid authentication

Supported File Types

Type

MIME Type

PDF

application/pdf

JPEG

image/jpeg

PNG

image/png

WebP

image/webp

DOCX

application/vnd.openxmlformats-officedocument.wordprocessingml.document

PPTX

application/vnd.openxmlformats-officedocument.presentationml.presentation

XLSX

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

EPUB

application/epub+zip

RTF

application/rtf

ODT

application/vnd.oasis.opendocument.text

CSV

text/csv

TXT

text/plain

Maximum file size: 50 MB (52,428,800 bytes)

Endpoints

Initiates an upload session and returns a URL to upload your file directly.

Field

Type

Required

Description

filename

string

Yes

Original filename including extension (e.g. invoice.pdf)

mimetype

string

Yes

MIME type of the file (must be a supported type)

bytes

number

Yes

File size in bytes (must be ≤ 52,428,800)

schema_id

string

Optional schema UUID to associate with this file at upload time

curl -X POST \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "invoice_2024_01.pdf",
    "mimetype": "application/pdf",
    "bytes": 245760
  }' \
  "https://api.exelensia.com/v1/upload/initiate"

{
  "file_id": "019760a0-0020-7000-8000-000000000020",
  "upload_url": "https://uploads.exelensia.com/teams/019760a0-0000-7000-8000-000000000000/019760a0-0020-7000-8000-000000000020.pdf?token=...&expires=1706961600",
  "expires_in": 900
}

Field

Description

file_id

UUID of the created file record — use this when calling the Process API

upload_url

Upload URL — valid for expires_in seconds (15 minutes)

expires_in

Seconds until the upload URL expires

After receiving the upload_url, upload the file using a PUT request with the exact Content-Type you specified:

curl -X PUT \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice_2024_01.pdf \
  "https://uploads.exelensia.com/..."

Important: Use PUT, not POST. The Content-Type header must match the mimetype you specified in the initiate request.

Status

Description

201

Upload session created, upload URL returned

400

Invalid request body, unsupported mimetype, or file too large

401

Missing or invalid authentication