Files

/v1/files is the reusable document corpus behind the capability endpoints. Register a file once and every later run takes {"file": {"id": "…"}}: the document is not fetched again and not parsed again.

Files you register vs files a run creates

Both kinds are files and both are addressed by id, but they live by different rules:

A run that creates a file inline still returns its id, so the parse is reusable inside that run’s TTL — but if you plan to keep working with the document, register it first. Extending the lifetime of a run’s files after the fact is what keep is for.

Register by URL

The production-default path: we fetch the bytes server-side over http(s).

$
curl -X POST https://api.cloudraker.com/v1/files \
>
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf",
>
    "name": "w9.pdf",
>
    "processing": "auto"
>
  }'

1
{
2
  "object": "file",
3
  "id": "a04d6597-4e34-4a99-94ea-964c289a4c68",
4
  "name": "w9.pdf",
5
  "mimeType": "application/pdf",
6
  "status": "uploading",
7
  "createdAt": "2026-07-25T18:00:39.453Z"
8
}

With a url the MIME type is sniffed from the response, so any mimeType you send alongside it is dropped rather than honored. Send url or name + mimeType, never a mix you expect to be respected.

Presigned upload

For local files, large files, and anything not reachable by URL. No multipart, pure JSON.

$
curl -X POST https://api.cloudraker.com/v1/files \
>
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "name": "recording.mp3", "mimeType": "audio/mpeg", "processing": "transcribe_diarize" }'

$
curl -X PUT "<uploadUrl>" \
>
  -H "Content-Type: audio/mpeg" \
>
  --data-binary @./recording.mp3

Read a file

$
curl https://api.cloudraker.com/v1/files/a04d6597-4e34-4a99-94ea-964c289a4c68 \
>
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY"

1
{
2
  "object": "file",
3
  "id": "a04d6597-4e34-4a99-94ea-964c289a4c68",
4
  "name": "w9.pdf",
5
  "mimeType": "application/pdf",
6
  "status": "ready",
7
  "createdAt": "2026-07-25T18:00:39.453Z",
8
  "urls": {
9
    "content": "https://cdn.cloudraker.com/…/latest?token=…&fn=w9.pdf",
10
    "markdown": "https://cdn.cloudraker.com/…/processed.md?token=…&fn=w9.pdf",
11
    "json": "https://cdn.cloudraker.com/…/processed.json?token=…&fn=w9.pdf"
12
  }
13
}

urls.content is the original bytes; urls.markdown and urls.json are the parse byproducts and appear only once the document was parsed. All three are signed and short-lived (~1 hour) — fetch the content, don’t store the URL.

List and delete

$
curl "https://api.cloudraker.com/v1/files?limit=50" \
>
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY"
$
$
curl -X DELETE https://api.cloudraker.com/v1/files/a04d6597-4e34-4a99-94ea-964c289a4c68 \
>
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY"

?limit caps the page (1–200, default 50), newest first. There is no cursor today — paging is by limit only. DELETE returns 204 and removes the parse byproducts with the file; runs that already used it keep their results.

Processing

processing picks how the document is read. It applies when the file is registered and again in file.processing on any capability call.

Parsing is automatic: a capability parses whatever isn’t parsed and never re-parses what is. Calling parse first is optional, not a prerequisite.

Reuse a file

$
curl -X POST https://api.cloudraker.com/v1/extract \
>
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "file": { "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" },
>
    "schema": { "type": "object", "properties": { "business_name": { "type": ["string", "null"] } } }
>
  }'

Parse once, run many: several narrow extractions, a redaction, and a fill can all read the same file id without re-reading the document. Send up to 100 file refs in one run with files: [...].

Next steps