Files & Workflows

These endpoints let you discover the IDs you need to launch an agent: find files by name, upload new ones, and list the workflows available on your instance.

Search files by name

GET /files/search

Search files readable by the authenticated user by file name. Use the returned id as a file ID in other API calls.

Scope: developer:files · Rate limit: Standard (300 req / min)

Query parameters

Parameter	Type	Required	Default	Description
query	string	Yes	—	Case-insensitive substring to match file names.
limit	number	No	10	Number of files to return. Minimum 1, maximum 50.
cursor	string	No	—	Pagination cursor from a previous response.
integrationId	string	No	—	Restrict results to files from a specific integration.

Response

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "name": "quarterly.pdf",
      "mimeType": "application/pdf",
      "parentId": null,
      "path": "Project%20Alpha/reports/quarterly.pdf"
    }
  ],
  "nextCursor": null
}

Field	Type	Description
data	array	Page of matching files.
id	string (uuid)	File ID.
name	string	File name.
mimeType	string	File MIME type.
parentId	string (uuid) or null	Parent folder ID, or null if at root.
path	string	Slash-delimited, URL-encoded display path including integration root and file.
nextCursor	string (uuid) or null	Cursor for the next page, or null when there are no more results.

Errors

Status	Cause
400	Missing or invalid query parameters.
401	Missing or invalid API key.
403	API key lacks developer:files scope.
429	Standard rate limit exceeded.

Example

curl "https://<your-domain>.nomic.ai/api/v0/files/search?query=quarterly&limit=10" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

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"

---

List workflows

GET /api/v0/workflows

Scope: developer:agent · Rate limit: Standard (300 req / min)

List workflows available to the authenticated user. Use the returned id as workflowId when launching an agent. Each workflow includes its input shape (requestedFiles) so callers can build launch requests correctly.

Query parameters

Parameter	Type	Default	Description
limit	int	20	Max results per page (1–100).
cursor	string	—	Opaque cursor from a previous page.
projectId	uuid	—	Filter to workflows in a project.

Response

{
  "data": [
    {
      "id": "019def34-...",
      "name": "Submittal Review",
      "description": "Reviews submittals against project specifications and codes",
      "requestedFiles": [
        {
          "name": "submittals",
          "description": "Submittal PDFs to review",
          "optional": false,
          "multiple": true
        }
      ]
    },
    {
      "id": "019def35-...",
      "name": "Code Compliance Check",
      "description": "Checks drawings against applicable building codes",
      "requestedFiles": []
    }
  ],
  "nextCursor": null
}

Field	Type	Description
data[].id	uuid	Workflow ID — pass as workflowId when launching.
data[].name	string	Display name.
data[].description	string?	Optional description.
data[].requestedFiles	array	File-input slots. Empty for prompt-only workflows.
requestedFiles[].name	string	Slot name — use as the key in workflowInputs when launching.
requestedFiles[].description	string	What this slot expects.
requestedFiles[].optional	boolean	Whether the slot can be omitted.
requestedFiles[].multiple	boolean	Whether the slot accepts more than one file.
nextCursor	string?	Opaque cursor for the next page, or null if there are no more results.

Errors

Status	Cause
401	Missing or invalid API key.
403	API key lacks developer:agent scope.
429	Standard rate limit exceeded.

Example

curl "https://<your-domain>.nomic.ai/api/v0/workflows?limit=10" \
  -H "Authorization: Bearer $NOMIC_API_KEY"