Files

/v1/files is the reusable document corpus behind the capability endpoints. Register a file once. Every later run then takes {"file": {"id": "…"}}. The platform does not fetch the document again and does not parse it again.

Files you register vs files a run creates

Both kinds are files, and an id addresses both. But they follow different rules:

A run that creates a file inline still returns its id. The parse is reusable inside that run’s TTL. If you plan to keep working with the document, register it first. Use keep to extend the lifetime of a run’s files after the fact.

Register by URL

This is the production-default path. The platform fetches 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 platform sniffs the MIME type from the response. It drops any mimeType you send with the url. Send url or name + mimeType, not both.

Presigned upload

Use this for local files, large files, and files 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. They appear only after the document was parsed. All three URLs are signed and expire after about 1 hour. Fetch the content. Do not store the URL.

Audio transcripts

Audio and video produce no markdown byproduct. urls.markdown stays absent for them. The transcript is urls.json.

Fetch that URL to read the transcript. The body is one object with a detected language and an ordered segments array.

1
{
2
  "language": "en",
3
  "segments": [
4
    {
5
      "start": 0.53,
6
      "end": 4.12,
7
      "text": "Good morning, thanks for calling the clinic.",
8
      "speaker": "SPEAKER_00",
9
      "words": [
10
        { "word": "Good", "start": 0.53, "end": 0.71, "score": 0.94, "speaker": "SPEAKER_00" },
11
        { "word": "morning,", "start": 0.78, "end": 1.14, "score": 0.91, "speaker": "SPEAKER_00" }
12
      ]
13
    },
14
    {
15
      "start": 4.60,
16
      "end": 7.02,
17
      "text": "Hi, I would like to book a follow-up.",
18
      "speaker": "SPEAKER_01",
19
      "words": [
20
        { "word": "Hi,", "start": 4.60, "end": 4.79, "score": 0.88, "speaker": "SPEAKER_01" }
21
      ]
22
    }
23
  ]
24
}

Join every segments[].text in order to rebuild the transcript as plain text.

A word the aligner cannot place comes back without start and end. This is rare. Fall back to the segment timing for those words.

Where the transcript arrives, per surface

The transcript is the same object everywhere. Only the delivery differs.

On /process, format=markdown returns null for audio content. Audio has no markdown byproduct. Always ask for format=json on a recording.

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 the file keep their results.

Processing

processing selects how the platform reads the document. It applies when you register the file, and again in file.processing on any capability call.

Parsing is automatic. A capability parses what is not parsed and never re-parses what is. A parse call 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. None re-reads the document. Send up to 100 file refs in one run with files: [...].

Next steps