File Upload
The Hatz API provides the functionality to upload files, which you can then use across chat, app builder, and workflows.
This API is for uploading source files into Hatz and polling their processing status. It does not expose arbitrary files from a code execution sandbox by filesystem path. If a chat or tool run creates an output inside a sandbox, have Hatz create a downloadable generated file for that output, then use the product-provided download flow or support diagnostics for that generated file.
Upload Methods
There are two ways to upload files:
| Method | Best for | How it works |
|---|---|---|
Single-request upload (POST /v1/files/upload) |
Server-to-server / API integrations | One multipart POST; the API streams the file to storage and returns a file_id for polling |
Presigned URL upload (POST /v1/files/upload-url) |
Browser / mobile clients | Request a signed URL, PUT the file directly, then poll for completion |
Both methods trigger the same asynchronous processing pipeline (text extraction, embeddings). Poll GET /v1/files/{file_id}/status until status is ready.
Firewall note: Presigned URL uploads use the domain
uploads.hatz.ai. Enterprise customers should whitelist this domain for outbound HTTPS traffic.
Single-Request Upload
Best for API integrations where you want a single HTTP call.
Step 1: Upload the file
curl -X POST 'https://ai.hatz.ai/v1/files/upload' \
-H 'X-API-Key: $HATZ_API_KEY' \
-F 'file=@report.pdf' \
-F 'scope_type=chat' \
-F 'scope_id=a90cb2a4-a4d5-4403-9b6a-6def06b0d4af'
Response:
{
"file_id": "8fb5bc1d-5a8d-4015-86a6-b0ca394e7793",
"status": "uploading",
"message": "File uploaded successfully. Poll GET /v1/files/{file_id}/status for processing status."
}
Step 2: Poll for completion
curl 'https://ai.hatz.ai/v1/files/8fb5bc1d-5a8d-4015-86a6-b0ca394e7793/status' \
-H 'X-API-Key: $HATZ_API_KEY'
Status values: uploading → processing → ready | failed
Presigned URL Upload
Best for browser and mobile clients. Keeps large file transfers off the API server and provides a stable domain (uploads.hatz.ai) for enterprise firewall whitelisting.
Step 1: Request an upload URL
curl -X POST 'https://ai.hatz.ai/v1/files/upload-url' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"file_name": "report.pdf",
"file_size": 1048576,
"mime_type": "application/pdf",
"scope_type": "chat",
"scope_id": "a90cb2a4-a4d5-4403-9b6a-6def06b0d4af"
}'
Response:
{
"presigned_url": "https://uploads.hatz.ai/uploads/...",
"file_id": "8fb5bc1d-5a8d-4015-86a6-b0ca394e7793",
"expires_in": 900
}
Step 2: Upload the file
PUT the file directly to the presigned URL. The URL is valid for 15 minutes.
curl -X PUT "$PRESIGNED_URL" \
-H 'Content-Type: application/pdf' \
--data-binary '@report.pdf'
Step 3: Poll for completion
Same as single-request upload — poll GET /v1/files/{file_id}/status.
Parameters
POST /v1/files/upload (multipart form)
| Parameter | Required | Description |
|---|---|---|
file |
Yes | The file to upload. Max 75 MB for documents, images, audio and archives; 50 MB for text, code and spreadsheet files (see Size limits) |
scope_type |
Yes | Context where this file will be used. One of: chat, workflow, app, agent, workflow_run, user, entity |
scope_id |
Yes | The ID of the resource specified by scope_type (e.g. the chat_id, app_id, etc.) |
purpose |
No | File purpose. One of: context (default), tmp, tool_output |
only_calculate_tokens |
No | If true, returns the token count without storing the file |
POST /v1/files/upload-url (JSON body)
| Parameter | Required | Description |
|---|---|---|
file_name |
Yes | Original filename |
file_size |
Yes | File size in bytes. Max 75 MB for documents, images, audio and archives; 50 MB for text, code and spreadsheet files (see Size limits) |
mime_type |
Yes | MIME type of the file |
scope_type |
Yes | Context where this file will be used. One of: chat, workflow, app, agent, workflow_run, user, entity |
scope_id |
Yes | The ID of the resource specified by scope_type (e.g. the chat_id, app_id, etc.) |
purpose |
No | File purpose. One of: context (default), tmp, tool_output |
Specialist formats for code tools
After the specialist-format update reaches your environment, uploads also accept
.exp, .bas, .jsonl, .tsv, .pcapng, .evtx, .mpp, and .xlsb.
| Formats | Processing |
|---|---|
| EXP, BAS | Decoded as text; the original file remains available to code tools |
| JSONL, TSV | Decoded as text with line and tab boundaries preserved; the original remains available to code tools |
| PCAPNG, EVTX, MPP, XLSB | Original file made available to code tools, without native text extraction or embeddings |
These files require a flow that supports code execution. Acceptance and ready
status mean the upload is available for use; they do not guarantee that a parser
for that format is installed or that every API compatibility mode can use it.
Uploading a script does not automatically execute it. Other unsupported extensions
remain rejected; renaming a file does not convert its contents. The iOS Files
picker may show files that the upload service does not accept.
EXP, BAS, JSONL and TSV use the 50 MB text limit. PCAPNG, EVTX, MPP and XLSB use the ordinary 75 MB limit, or 100 MB where that increase is enabled. XLSB is a binary sandbox input, rather than a native spreadsheet-processing format.
Size limits
Both upload routes enforce the same per-file ceiling, chosen by file type:
| File type | Maximum size |
|---|---|
| Documents (PDF, Word, PowerPoint, etc.), images, audio, archives | 75 MB |
| Text, structured text (Markdown, JSON, XML, etc. — SVG follows this row, not the image row), code, spreadsheets (CSV, XLSX, etc.) | 50 MB |
A further raise to 100 MB for documents, images, audio and archives is rolling out progressively; where it is enabled for your organization, those types accept up to 100 MB. Text, code and spreadsheet files stay at 50 MB either way.
A request over the applicable limit is rejected with 413 and a message naming the limit that applied to that file, so a 76 MB PDF and a 51 MB CSV get different messages.
Audio has a second, separate bound on POST /v1/files/batch-upload-url: at most 3 audio files per request, and at most 180 estimated minutes summed across them, estimated from bytes at an assumed 64 kbps. A batch is refused with 422 — not 413 — only when it breaks one of those two.
One recording at the 75 MB ceiling is about 164 estimated minutes, which leaves 16 minutes for the rest of that request: at 64 kbps that is a second file of up to 7,680,000 bytes (about 7.3 MB). Larger recordings do have to go in separate requests, but a short follow-up clip does not.
GET /v1/files/{file_id}/status
Returns the current processing status of a file.
| Field | Description |
|---|---|
file_uuid |
The file identifier |
status |
Usually uploading, processing, ready or failed. Other values can appear. A file can still be downloadable when its status is not ready: if text extraction was abandoned (extraction_abandoned), the original file is served when it was kept. To find out whether a file can be downloaded, call the content endpoint. |
tokens |
Token count (populated when ready) |
error |
Error message (populated when failed) |
original_filename |
The name the file was uploaded with |
mime_type |
The file's content type |
bytes |
File size in bytes |
{
"file_uuid": "8fb5bc1d-5a8d-4015-86a6-b0ca394e7793",
"status": "ready",
"tokens": 12,
"error": null,
"original_filename": "notes.txt",
"mime_type": "text/plain",
"bytes": 44
}
A failed file has "status": "failed" and a general error such as "File processing failed. Please try again."
You can read a file's status if you uploaded it, or if it is attached to an app or workflow that is shared with you. Otherwise, and for unknown IDs, the response is 404 with "File not found."
GET /v1/files/{file_id}/content
Downloads a file. The response is a 307 redirect to a short-lived download URL, valid for 5 minutes. Send your API key only to the Hatz API, not to the download URL. With curl, read the redirect first, then download from it without the key:
URL=$(curl -s -o /dev/null -w '%{redirect_url}' \
'https://ai.hatz.ai/v1/files/8fb5bc1d-5a8d-4015-86a6-b0ca394e7793/content' \
-H "X-API-Key: $HATZ_API_KEY")
curl -o notes.txt "$URL"
Don't use curl -L with the X-API-Key header: curl sends custom headers to the redirect target too.
Request a new redirect each time you download; don't store the URL.
Query parameters:
disposition(optional):attachment(default) to download, orinlineto display in a browser. File types that are unsafe to display are always served asattachment. Any other value returns422.
The same access rules as the status endpoint apply.
| Status | error.details.code |
When |
|---|---|---|
307 |
Redirect to the download URL | |
403 |
download_restricted |
Your organization's file policy blocks direct downloads |
404 |
Unknown file, or a file you can't access | |
409 |
file_not_ready |
The file's status is not ready yet |
410 |
file_deleted |
The file was deleted |
422 |
file_processing_failed |
Processing failed, so the file is unavailable |
DELETE /v1/files/{file_id}
Deletes a file. Only the user who uploaded it can delete it.
curl -X DELETE 'https://ai.hatz.ai/v1/files/8fb5bc1d-5a8d-4015-86a6-b0ca394e7793' \
-H "X-API-Key: $HATZ_API_KEY"
{
"file_uuid": "8fb5bc1d-5a8d-4015-86a6-b0ca394e7793",
"storage_version": 2,
"deleted": true
}
- A user who can see the file but did not upload it gets
403with"Not authorized to delete this file." - Users who can't see the file, and requests for unknown or already deleted files, get
404with"File not found." - After deletion, the status and content endpoints return
404to the user who deleted it. Other users who had access may get410(file_deleted) from the content endpoint.
A malformed file_id returns 422 on all three endpoints.
Using Files
Once a file reaches ready status, use its file_id across the API.
Chat Completions
curl 'https://ai.hatz.ai/v1/chat/completions' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"messages": [{"role": "user", "content": "tell me about this file"}],
"model": "gpt-4o",
"stream": false,
"file_uuids": ["8fb5bc1d-5a8d-4015-86a6-b0ca394e7793"]
}'
App Builder
curl 'https://ai.hatz.ai/v1/app/5ae6e9dd-0296-4409-8fe4-1fc646bb22f7/query' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"inputs": {
"report_file": "8fb5bc1d-5a8d-4015-86a6-b0ca394e7793"
},
"stream": false
}'
Workflows
curl -X POST 'https://ai.hatz.ai/v1/workflows/run' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "5ae6e9dd-0296-4409-8fe4-1fc646bb22f7",
"inputs": {
"report_file": "8fb5bc1d-5a8d-4015-86a6-b0ca394e7793"
}
}'
In all cases, pass the file's UUID as the input value for any file_upload input.