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. The workflow authoring endpoints let you create, edit, test, and release workflows of your own.

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​

Response​

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

Errors​

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:

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"
}

Errors​

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​

Response​

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

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​

Example​

import os
import time
import requests

BASE_URL = "https://<your-domain>.nomic.ai/api/v0"
HEADERS = {"Authorization": f"Bearer {os.environ['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​

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
}

Errors​

Example​

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

Workflow authoring​

These endpoints create and edit workflows the same way the workflow builder does. Every save writes a version; agents launched from a workflow run its released version unless you pass workflowVersionId. A typical loop:

1. Create a workflow or update one. Both return the versionId they wrote, which is not released yet.
2. Launch an agent with workflowId and that versionId as workflowVersionId to test it.
3. Release the version once it works.

Writes require the developer:workflows scope; reads use developer:agent. Reading a workflow's full definition or its versions, editing it, and releasing it all require edit access to the workflow. A caller who can run a workflow but not edit it gets 403.

Create a workflow​

POST /api/v0/workflows

Scope: developer:workflows · Rate limit: Write (60 req / min)

Create a workflow owned by the caller, private to them, with an unreleased first version. Context files and tags are attached in the builder UI.

Request body:

Example:

curl -X POST "https://<your-domain>.nomic.ai/api/v0/workflows" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Submittal Review",
    "instructionMarkdown": "Review each file in Submittals against /artifacts/Checklist.md and list every deviation.",
    "requestedFiles": [
      { "name": "Submittals", "description": "Submittal PDFs to review", "multiple": true }
    ],
    "linkedArtifacts": [
      { "name": "Checklist", "content": "- Fire rating stated\n- Model numbers match the spec" }
    ]
  }'

Response:

{
  "data": {
    "id": "019def34-...",
    "versionId": "019def40-...",
    "version": 1,
    "createdNewVersion": true,
    "linkedArtifacts": [{ "id": "019ccc10-...", "name": "Checklist" }],
    "builderPath": "/workflows/019def34-.../edit"
  }
}

Errors:

Get a workflow​

GET /api/v0/workflows/{workflowId}

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

Get one version of a workflow in full: instructions, input slots, model, effort, capabilities, and linked artifacts.

Query parameters:

Response: data holds the workflow — id, name, description, metadata, projectId, isPublic, isShared, isArchived, releasedVersionId, latestVersionId, and builderPath — plus version, the requested version: id, version, isReleased, instructionMarkdown, mode, model, requestedFiles, capabilities, and linkedArtifacts (id, name, type, content). When latestVersionId differs from releasedVersionId, the latest version is an unreleased draft. isShared is true when anyone besides the owner can run the workflow.

Errors: 403 if you can run the workflow but not edit it; 404 if the workflow or version is not found.

List workflow versions​

GET /api/v0/workflows/{workflowId}/versions

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

List every version of a workflow, newest first, with its run count and cost. Read a version's content with Get a workflow and versionId.

Response:

{
  "data": [
    {
      "id": "019def41-...",
      "version": 2,
      "isReleased": false,
      "createdAt": "2026-04-09T10:30:00.000Z",
      "updatedAt": "2026-04-09T11:05:00.000Z",
      "changeNote": null,
      "authorEmail": "alice@example.com",
      "runCount": 3,
      "averageCostUsd": 0.42,
      "totalCostUsd": 1.26
    }
  ]
}

runCount counts agents launched on the version by anyone. updatedAt changes without a new version number when a draft is edited in place.

Errors: 403 if you can run the workflow but not edit it; 404 if no workflow with that ID is visible to you.

Update a workflow​

POST /api/v0/workflows/{workflowId}

Scope: developer:workflows · Rate limit: Write (60 req / min)

Write a new candidate version, as saving in the builder does. Takes the same fields as Create a workflow except projectId, all optional, plus baseVersionId. Fields you leave out are copied from baseVersionId (default: the latest version). Nothing is released.

The latest version is edited in place only when it is an unreleased draft that no agent has run and you start from it; otherwise a new version is created, so every run stays tied to the content it ran. The response has the same shape as Create a workflow.

Errors: 400 for a validation error, an artifact id not linked to the base version, or an unavailable capability; 403 if you can run the workflow but not edit it; 404 if the workflow or base version is not found; 409 if the workflow is archived.

Release a workflow version​

POST /api/v0/workflows/{workflowId}/versions/{versionId}/release

Scope: developer:workflows · Rate limit: Write (60 req / min)

Make a version the one everyone who can run the workflow gets by default — forward to a new version or back to an earlier one. Sharing is unchanged, but on a shared workflow (isShared: true) this changes what other people run.

Response:

{
  "data": {
    "id": "019def34-...",
    "releasedVersionId": "019def41-...",
    "version": 2,
    "previousReleasedVersionId": "019def40-..."
  }
}

To roll back, release previousReleasedVersionId again.

Errors: 403 if you can run the workflow but not edit it; 404 if the workflow or version is not found; 409 if the workflow is archived.