Register a file by URL, or get a presigned upload URL

POST

https://api.cloudraker.com/v1/spaces/:spaceId/files

Adds a file to your reusable corpus, either by URL or by uploading the bytes yourself.

Two request shapes, both pure JSON — send one or the other, never both.

By URL. { url, name?, processing? } registers the file and fetches it over http(s). The media type is sniffed from the response, so any mimeType you send is ignored. You get the file back with status: "processing".

{ "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "fw9.pdf" }

By upload. { name, mimeType, processing? } reserves the record and returns uploadUrl plus uploadExpiresAt (15 minutes). PUT the bytes to that URL with a Content-Type header exactly equal to the mimeType you sent; parsing starts the moment they land.

{ "name": "recording.mp3", "mimeType": "audio/mpeg" }

Parsing engine — processing accepts auto (the default, self-upgrades to OCR on scans), ocr, simple, transcribe and transcribe_diarize. Audio and video default to transcribe_diarize.

Files registered here are persistent — no TTL — and reusable across any number of runs as file: { "id": "…" }. That is what makes parse-once-run-many work: pass the same id to extract, redact and pipeline without re-parsing.

Learn more: Working with files

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

spaceIdstringRequired

Request

This endpoint expects an object.

objectRequired

Response

The registered file.

object"file"

idstring

namestring

mimeTypestring

statusenum

Allowed values:

createdAtstring

parentFileIdstringOptional

metadatamap from strings to stringsOptional

errorstringOptional

uploadUrlstringOptional

uploadExpiresAtstringOptional

urlsobjectOptional

Errors

422

Unprocessable Entity Error

429

Too Many Requests Error

502

Bad Gateway Error