Capabilities

Files & Workflows

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

List projects

To discover the projectId you pass when listing workflows or launching an agent, list the projects available to your API key:

GET /projects

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

For the full request and response shape — plus creating projects, updating their metadata, and managing members — see the Projects API.

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. Auto-indexable types (PDF and legacy Office) are queued for processing and return status: "processing". Other types are immediately ready. Poll Get file status before launching a workflow that needs the file.

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",
  "status": "processing"
}

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.
`status`	`processing` \| `ready` \| `failed`	Initial processing status. Poll Get file status until `ready` or `failed`.

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"

Get file status

GET /files/{id}/status

Poll whether an uploaded file is ready to attach to an agent or workflow. Use this instead of sleeping for an arbitrary delay after upload.

Scope: developer:files · Rate limit: Standard (300 req / min, shared with other standard-tier reads)

Suggested poll interval: 1–2 seconds. Stop when status is ready, failed, or a client-defined deadline expires. A processing response does not promise that processing will eventually complete.

Path parameters

Parameter	Type	Description
`id`	string (uuid)	File ID returned by upload.

Response

{
  "id": "019abc12-3456-7890-abcd-ef1234567890",
  "status": "ready"
}

Field	Type	Description
`id`	string (uuid)	File ID.
`status`	`processing` \| `ready` \| `failed`	`processing` — keep polling. `ready` — safe to launch. `failed` — stop.

Types that are never auto-indexed (CSV, XLSX, DOCX, images, and similar) are ready as soon as upload returns. A file the caller cannot read is reported as not found.

Errors

Status	Cause
`401`	Missing or invalid API key.
`403`	API key lacks `developer:files` scope.
`404`	File not found or not readable.
`429`	Standard rate limit exceeded.

Example

import time
import requests

BASE_URL = "https://<your-domain>.nomic.ai/api/v0"
HEADERS = {"Authorization": "Bearer $NOMIC_API_KEY"}

upload = requests.post(
    f"{BASE_URL}/files/upload",
    headers=HEADERS,
    files={"file": ("specs.pdf", open("specs.pdf", "rb"), "application/pdf")},
)
file_id = upload.json()["id"]
status = upload.json()["status"]
deadline = time.monotonic() + 300

while status == "processing":
    if time.monotonic() >= deadline:
        raise TimeoutError("File processing did not finish within 5 minutes")
    time.sleep(1)
    status = requests.get(
        f"{BASE_URL}/files/{file_id}/status", headers=HEADERS
    ).json()["status"]

if status == "failed":
    raise RuntimeError("File processing failed")
# status == "ready" — launch the workflow with file_id

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"

List projects​

Search files by name​

Query parameters​

Response​

Errors​

Example​

Upload a file​

Request​

Response​

Errors​

Example​

Get file status​

Path parameters​

Response​

Errors​

Example​

List workflows​

Query parameters​

Response​

Errors​

Example​

List projects

Search files by name

Query parameters

Response

Errors

Example

Upload a file

Request

Response

Errors

Example

Get file status

Path parameters

Response

Errors

Example

List workflows

Query parameters

Response

Errors

Example