Files
Upload files for use with Parse and other platform features.
Upload a file
POST /files/upload
Upload a file using multipart/form-data. The file is streamed directly to storage without buffering. Ingestable file types (PDF, images, Office documents) are automatically queued for processing after upload.
Scope: developer:files · Rate limit: Heavy (30 req / min) · Max file size: 500 MB
Request
Send a multipart/form-data request with the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | The file to upload. |
path | string | No | Slash-delimited path including filename, e.g. reports/2026/quarterly.pdf. Intermediate folders are created automatically. The last segment is used as the filename. |
parentId | string (uuid) | No | UUID of an existing folder to upload into. |
If neither path nor parentId is provided, the file is placed at the root of your file tree.
Response
{
"id": "019abc12-3456-7890-abcd-ef1234567890",
"name": "quarterly.pdf",
"mimeType": "application/pdf",
"size": 1048576,
"fileType": "DOCUMENT",
"parentId": null,
"fileVersionId": "019abc12-3456-7890-abcd-ef1234567891",
"createdAt": "2026-04-05T12:00:00.000Z"
}
| Field | Type | Description |
|---|---|---|
id | string (uuid) | File ID. |
name | string | File name. |
mimeType | string | MIME type of the uploaded file. |
size | number | File size in bytes. |
fileType | string | Always "DOCUMENT" for uploaded files. |
parentId | string (uuid) or null | Parent folder ID, or null if at root. |
fileVersionId | string (uuid) | ID of the created file version. Use this to submit a parse job. |
createdAt | string (ISO 8601) | Creation timestamp. |
Errors
| Status | Cause |
|---|---|
400 | Missing file field, empty file, or Content-Type is not multipart/form-data. |
401 | Missing or invalid API key. |
403 | API key lacks developer:files scope. |
413 | File exceeds the 500 MB size limit. |
503 | Upload integration not configured on this instance. |
Example
curl -X POST "https://<your-domain>.nomic.ai/api/v0/files/upload" \
-H "Authorization: Bearer $NOMIC_API_KEY" \
-F "file=@drawings/floor-plan.pdf" \
-F "path=project-alpha/drawings/floor-plan.pdf"