API

API reference

Servers

StabilityExperimentalMay change or be removed without notice.

Agents

Launch background agents, inspect their status, and manage follow-up turns.

List all assistant sessions for the authenticated user, with optional filtering by status or workflow.

Parameters

limitinteger | query

Max results (default 20, max 100)

Default value : 20

cursorstring | query

Pagination cursor

statusstring | query

Filter by status (waiting, running, finished, stopped, failed)

Available values : waiting, running, awaiting_tool, finished, stopped, failed

workflowIdstring ($uuid) | query

Filter by workflow ID. Pass null to exclude agents launched from a workflow.

Responses

200List of agents

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/agents?limit=20' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "waiting",
      "title": "string",
      "retry": {
        "kind": "provider_retry",
        "category": "string",
        "nextRetryAt": "2026-01-15T09:30:00.000Z",
        "attemptCount": 0,
        "provider": "string",
        "model": "string",
        "reason": "string",
        "operatorActionRequired": true
      },
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "workflowName": "string",
      "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectName": "string",
      "artifacts": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "type": "string",
          "name": "string",
          "createdAt": "2026-01-15T09:30:00.000Z"
        }
      ],
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "nextCursor": "string"
}

Launch a new background agent. A simple agent runs from prompt.text with optional fileIds for files the agent can read. Pass workflowId to instead launch a workflow agent; for workflows with file-input slots, use workflowInputs in place of prompt.

Parameters

No parameters

Responses

201Agent created

400Validation error

402Spend limit exceeded

404Workflow not found

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/agents' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": {
    "text": "string",
    "images": [
      {
        "media_type": "image/jpeg",
        "data": "string"
      }
    ]
  },
  "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fileIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "workflowInputs": {
    "additionalProp": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "capabilities": {
    "codeSearch": true,
    "webSearch": true
  },
  "model": "auto",
  "mode": "low"
}'

Request bodyapplication/json

{
  "prompt": {
    "text": "string",
    "images": [
      {
        "media_type": "image/jpeg",
        "data": "string"
      }
    ]
  },
  "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fileIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "workflowInputs": {
    "additionalProp": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "capabilities": {
    "codeSearch": true,
    "webSearch": true
  },
  "model": "auto",
  "mode": "low"
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "waiting",
    "title": "string",
    "retry": {
      "kind": "provider_retry",
      "category": "string",
      "nextRetryAt": "2026-01-15T09:30:00.000Z",
      "attemptCount": 0,
      "provider": "string",
      "model": "string",
      "reason": "string",
      "operatorActionRequired": true
    },
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "workflowName": "string",
    "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "projectName": "string",
    "artifacts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "string",
        "name": "string",
        "createdAt": "2026-01-15T09:30:00.000Z"
      }
    ],
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "activeFileIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "parentSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "model": "claude-haiku-4-5"
  }
}

Get detailed information about a specific agent, including derived source files and artifact references. Organization admin analytics keys can read agents owned by any user in their organization.

Parameters

idstring ($uuid) | path*required

Agent ID

Responses

200Agent details

404Agent not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "waiting",
    "title": "string",
    "retry": {
      "kind": "provider_retry",
      "category": "string",
      "nextRetryAt": "2026-01-15T09:30:00.000Z",
      "attemptCount": 0,
      "provider": "string",
      "model": "string",
      "reason": "string",
      "operatorActionRequired": true
    },
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "workflowName": "string",
    "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "projectName": "string",
    "artifacts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "string",
        "name": "string",
        "createdAt": "2026-01-15T09:30:00.000Z"
      }
    ],
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "activeFileIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "parentSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "model": "claude-haiku-4-5"
  }
}

Delete an agent session and all of its messages. If the agent is currently running, an abort is broadcast first and delete waits up to 10 seconds for the pipeline to release its presence before tearing down the row. Attachment rows are orphaned and their S3 objects reclaimed by a background sweep. Artifacts produced by the agent are not deleted (their creatingSessionId is set to null).

Parameters

idstring ($uuid) | path*required

Agent ID

Responses

204Agent deleted

404Agent not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'DELETE' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}' \
  -H 'accept: application/json'

Retrieve the conversation history for an agent, linearized to the current active branch. By default returns user, assistant, and error messages. Pass ?include=steps to additionally receive thinking, tool, and compaction events. Organization admin analytics keys can read agents owned by any user in their organization.

Parameters

idstring ($uuid) | path*required

Agent ID

includearray<string> | query

Comma-separated list of optional detail to include. Currently supports steps (thinking, tool, and compaction events).

Available values : steps

Default value : List []

Responses

200Conversation messages

404Agent not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}/conversation' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "string",
    "messages": [
      {
        "id": "string",
        "createdAt": "2026-01-15T09:30:00.000Z",
        "type": "user",
        "text": "string"
      },
      {
        "id": "string",
        "createdAt": "2026-01-15T09:30:00.000Z",
        "type": "assistant",
        "text": "string"
      },
      {
        "id": "string",
        "createdAt": "2026-01-15T09:30:00.000Z",
        "type": "error",
        "text": "string"
      },
      {
        "id": "string",
        "createdAt": "2026-01-15T09:30:00.000Z",
        "type": "thinking",
        "redacted": true,
        "text": "string"
      },
      {
        "id": "string",
        "createdAt": "2026-01-15T09:30:00.000Z",
        "type": "tool",
        "toolName": "string",
        "status": "started",
        "subAgentIds": [
          "string"
        ]
      },
      {
        "id": "string",
        "createdAt": "2026-01-15T09:30:00.000Z",
        "type": "compaction"
      }
    ]
  }
}

Per-model token usage and USD cost for an agent run, summed over the agent session and its sub-agent sessions. Cost is the agent run only; it excludes any external grading/eval spend. Sum across the array for run totals. Organization admin analytics keys can read agents owned by any user in their organization.

Parameters

idstring ($uuid) | path*required

Agent ID

Responses

200Per-model usage for the agent run

404Agent not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}/usage' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "spend": [
      {
        "model": "string",
        "costUsd": 0,
        "inputTokens": 0,
        "outputTokens": 0,
        "cacheCreationTokens": 0,
        "cacheReadTokens": 0
      }
    ]
  }
}

Retrieve the content of a specific artifact produced by an agent. Returns the latest version. For MARKDOWN_DOCUMENT artifacts, content is a string. For TABLE artifacts, content is an object with schema and elements.

Parameters

idstring ($uuid) | path*required

Agent ID

artifactIdstring ($uuid) | path*required

Artifact ID

Responses

200Artifact content

404Agent or artifact not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}/artifacts/{artifactId}' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "type": "string",
    "version": 0,
    "content": "string",
    "createdAt": "2026-01-15T09:30:00.000Z"
  }
}

Export table data as CSV or XLSX, or an annotated Drawing Review PDF. Pass format as a query parameter and receive a signed URL valid for five minutes.

Parameters

idstring ($uuid) | path*required

Agent ID.

artifactIdstring ($uuid) | path*required

Artifact ID.

formatstring | query*required

Export format: csv or xlsx for a TABLE artifact, or drawing_review_pdf for an annotated Drawing Review PDF.

Available values : csv, xlsx, drawing_review_pdf

versioninteger | query

Artifact version. Defaults to the latest version.

fileVersionIdstring ($uuid) | query

Source PDF file version for a Drawing Review PDF that cites multiple files.

Responses

200Artifact export URL.

400Unsupported artifact/format combination or ambiguous Drawing Review PDF source.

404Agent, artifact, artifact version, or source file was not found or is inaccessible.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}/artifacts/{artifactId}/exports?format=csv' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "type": "TABLE",
    "version": 0,
    "format": "csv",
    "mimeType": "string",
    "filename": "string",
    "url": "https://example.com",
    "expiresAt": "2026-01-15T09:30:00.000Z",
    "fileVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "annotationCount": 0
  }
}

Request cancellation of a running agent. Idempotent — calling stop on an already-terminal agent is a no-op. Status transition is asynchronous; poll GET /agents/{id} to observe the final stopped status.

Parameters

idstring ($uuid) | path*required

Agent ID

Responses

200Stop requested

404Agent not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}/stop' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "waiting",
    "title": "string",
    "retry": {
      "kind": "provider_retry",
      "category": "string",
      "nextRetryAt": "2026-01-15T09:30:00.000Z",
      "attemptCount": 0,
      "provider": "string",
      "model": "string",
      "reason": "string",
      "operatorActionRequired": true
    },
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "workflowName": "string",
    "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "projectName": "string",
    "artifacts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "string",
        "name": "string",
        "createdAt": "2026-01-15T09:30:00.000Z"
      }
    ],
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

Continue a finished, stopped, or failed agent with a new user prompt. Kicks off a new pipeline turn in the background; poll GET /agents/{id} to observe progress.

Parameters

idstring ($uuid) | path*required

Agent ID

Responses

202Follow-up queued

400Validation error

402Spend limit exceeded

404Agent not found

409Agent is not in a terminal state

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/agents/{id}/followup' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": {
    "text": "string",
    "images": [
      {
        "media_type": "image/jpeg",
        "data": "string"
      }
    ]
  }
}'

Request bodyapplication/json

{
  "prompt": {
    "text": "string",
    "images": [
      {
        "media_type": "image/jpeg",
        "data": "string"
      }
    ]
  }
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "waiting",
    "title": "string",
    "retry": {
      "kind": "provider_retry",
      "category": "string",
      "nextRetryAt": "2026-01-15T09:30:00.000Z",
      "attemptCount": 0,
      "provider": "string",
      "model": "string",
      "reason": "string",
      "operatorActionRequired": true
    },
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "workflowName": "string",
    "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "projectName": "string",
    "artifacts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "string",
        "name": "string",
        "createdAt": "2026-01-15T09:30:00.000Z"
      }
    ],
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "activeFileIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "parentSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "model": "claude-haiku-4-5"
  }
}

Files

Upload and manage files for use with agents and projects.

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

Parameters

querystring | query*required

Case-insensitive substring to match file names.

limitinteger | query

Max results (default 10, max 50).

Default value : 10

cursorstring | query

Pagination cursor from a previous response.

integrationIdstring | query

Filter to files from a specific integration.

Responses

200List of matching files.

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/files/search?query=string&limit=10' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "mimeType": "string",
      "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "path": "string"
    }
  ],
  "nextCursor": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Poll whether an uploaded file is ready to attach to an agent or workflow. Returns processing while ingest is in progress, ready when there is no processing race left, or failed if ingest failed. Types that are never auto-indexed are immediately ready. A file the caller cannot read is reported as not found. Requires the developer:files scope.

Parameters

idstring ($uuid) | path*required

File ID

Responses

200File processing status

401Missing or invalid Authorization header / API key.

403API key is missing the required developer:files scope.

404File not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/files/{id}/status' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "processing"
}

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 /files/{id}/status before launching a workflow. Requires the developer:files scope.

Parameters

No parameters

Responses

200File uploaded successfully.

400Bad request — missing file field, empty file, or invalid Content-Type.

401Missing or invalid Authorization header / API key.

403API key is missing the required developer:files scope.

413File exceeds the 500MB size limit.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

500Internal server error.

503Upload integration not configured for this instance.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/files/upload' \
  -H 'accept: application/json' \
  -F 'file=@./local-file.pdf'

Example valueapplication/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "mimeType": "string",
  "size": 0,
  "fileType": "DOCUMENT",
  "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fileVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "status": "processing"
}

Projects

Create projects, edit their metadata, and manage who belongs to them and at what role.

List projects available to the authenticated user, which for an organization admin is every project in the organization. Pass membership=mine to narrow it to projects the caller belongs to. Use the returned id as projectId when listing workflows or launching an agent.

Parameters

limitinteger | query

Max results (default 20, max 100)

Default value : 20

cursorstring | query

Pagination cursor

searchstring | query

Filter by project name or project number (case-insensitive substring).

membershipstring | query

Which projects to list. any (the default) returns everything the caller may see, which for an organization admin is every project in the organization. mine narrows it to projects the caller belongs to. For a caller who is not an admin the two are the same set.

Available values : mine, any

Default value : any

Responses

200List of projects

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/projects?limit=20&membership=mine' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "description": "string",
      "projectNumber": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "nextCursor": "string"
}

Create a project. The authenticated user becomes its first administrator.

Parameters

No parameters

Responses

201Project created

400Validation error

429Rate limit exceeded — max 60 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/projects' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "projectNumber": "string"
}'

Request bodyapplication/json

{
  "name": "string",
  "description": "string",
  "projectNumber": "string"
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "projectNumber": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

Get a single project by ID. A project the caller cannot read is reported as not found.

Parameters

idstring ($uuid) | path*required

Project ID

Responses

200Project details

404Project not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/projects/{id}' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "projectNumber": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

Update a project. Every field is optional and one left out is untouched; null clears a nullable field. Requires admin access to the project, or organization admin.

Parameters

idstring ($uuid) | path*required

Project ID

Responses

200The updated project

400Validation error, or no fields to update

403Read access to the project, but not admin

404No project with that ID is visible to the caller

429Rate limit exceeded — max 60 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/projects/{id}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "projectNumber": "string"
}'

Request bodyapplication/json

{
  "name": "string",
  "description": "string",
  "projectNumber": "string"
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "projectNumber": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

List the members of a project and the role each holds. Roles map to the names used in the app: admin is an Admin, editor is a Member, and viewer is a Read-only member. Requires read access to the project.

Parameters

idstring ($uuid) | path*required

Project ID

limitinteger | query

Max results (default 50, max 100).

Default value : 50

cursorstring | query

Pagination cursor from a previous response's nextCursor.

Responses

200Page of project members.

404No project with that ID is visible to the caller.

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/projects/{id}/members?limit=50' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "string",
      "name": "string",
      "image": "string",
      "role": "admin"
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

Grant, change, or revoke project roles in one batch, applied atomically: nothing is written unless every entry is valid. A role of null removes the member. Removing a non-member, and re-stating the role a member already reports, are both no-ops, so a list read from GET /projects/{id}/members can be sent back unchanged. Members must already belong to the organization, and the caller must be a project admin. Roles map to the names used in the app: admin is an Admin, editor is a Member, and viewer is a Read-only member; most integrations use admin or editor.

Parameters

idstring ($uuid) | path*required

Project ID

Responses

200The project members after the batch

400Validation error, or an unknown or repeated user

403Read access to the project but not admin, or project sharing is disabled on this instance

404No project with that ID is visible to the caller

429Rate limit exceeded — max 60 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/projects/{id}/members' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "members": [
    {
      "user": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "role": "admin"
    }
  ]
}'

Request bodyapplication/json

{
  "members": [
    {
      "user": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "role": "admin"
    }
  ]
}

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "string",
      "name": "string",
      "image": "string",
      "role": "admin"
    }
  ]
}

Parse

Submit documents for parsing and poll job status.

Submit a document for parsing. Only uploaded files are supported — integration files (SharePoint, Egnyte, Google Drive) are not. Returns a taskId that can be polled via GET /api/v0/parse/{taskId}. Requires the developer:parse scope.

Parameters

No parameters

Responses

200Parse job submitted successfully.

400Bad request — invalid body fields, or the file is an integration file (SharePoint, Egnyte, Google Drive) which is not supported.

401Missing or invalid Authorization header / API key.

403API key is missing the required developer:parse scope.

404File version not found or not accessible by the authenticated user.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

501S3 cache is disabled on this instance — document parsing is unavailable.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/parse' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "fileVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "options": {
    "ocrLanguage": "en",
    "figureSummary": {
      "enabled": true
    },
    "tableSummary": {
      "enabled": true
    },
    "summaryWordLimit": 10,
    "embedChunks": true,
    "summaryChunks": {
      "enabled": true,
      "summaryBy": "page",
      "summaryMode": "rolling_summary",
      "batchSize": 0,
      "contextSize": 0
    },
    "experimentalOptions": {
      "layoutModel": "string",
      "usePaddlePostprocessing": true
    }
  }
}'

Request bodyapplication/json

{
  "fileVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "options": {
    "ocrLanguage": "en",
    "figureSummary": {
      "enabled": true
    },
    "tableSummary": {
      "enabled": true
    },
    "summaryWordLimit": 10,
    "embedChunks": true,
    "summaryChunks": {
      "enabled": true,
      "summaryBy": "page",
      "summaryMode": "rolling_summary",
      "batchSize": 0,
      "contextSize": 0
    },
    "experimentalOptions": {
      "layoutModel": "string",
      "usePaddlePostprocessing": true
    }
  }
}

Example valueapplication/json

{
  "taskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Poll the status of a parse task. Returns pending while processing, completed with a presigned resultUrl on success, or failed with an error message. The resultUrl is valid for 1 hour. Requires the developer:parse scope.

Parameters

taskIdstring ($uuid) | path*required

Responses

200Parse task status.

401Missing or invalid Authorization header / API key.

403API key is missing the required developer:parse scope.

404Task not found or not accessible by the authenticated user.

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

501S3 cache is disabled on this instance — document parsing is unavailable.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/parse/{taskId}' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "status": "pending"
}

Codes and Standards

Search and retrieve building codes and standards information.

Search building codes, fire codes, and other regulatory documents by jurisdiction, code type, and natural language query. Returns enriched metadata including code details, jurisdiction info, and adoption status.

Parameters

No parameters

Responses

200Search results with enriched metadata

429Rate limit exceeded — max 60 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/codes/search' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "string",
  "jurisdiction": "general",
  "codeType": "Accessibility Code",
  "year": 0,
  "limit": 10,
  "keywords": [
    "string"
  ]
}'

Request bodyapplication/json

{
  "query": "string",
  "jurisdiction": "general",
  "codeType": "Accessibility Code",
  "year": 0,
  "limit": 10,
  "keywords": [
    "string"
  ]
}

Workflows

List the workflows an agent can be launched from.

List workflows available to the authenticated user. Use the returned id as workflowId when launching an agent.

Parameters

limitinteger | query

Max results (default 20, max 100)

Default value : 20

cursorstring | query

Pagination cursor

projectIdstring ($uuid) | query

Filter to workflows in a specific project.

Responses

200List of workflows

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/workflows?limit=20' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "description": "string",
      "requestedFiles": [
        {
          "name": "string",
          "description": "string",
          "optional": true,
          "multiple": true
        }
      ]
    }
  ],
  "nextCursor": "string"
}

Users

Manage organization user accounts and their access status.

Disable a user account and revoke all their API keys. This is typically used as a SOAR action in response to security incidents.

Parameters

idstring ($uuid) | path*required

User ID

Responses

200User disabled successfully

404User not found

429Rate limit exceeded — max 60 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/users/{id}/disable' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string"
}'

Request bodyapplication/json

{
  "reason": "string"
}

Example valueapplication/json

{
  "success": true,
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "disabled": true,
    "disabledAt": "2026-01-15T09:30:00.000Z"
  },
  "revokedApiKeys": 0
}

Re-enable a previously disabled user account.

Parameters

idstring ($uuid) | path*required

User ID

Responses

200User enabled successfully

404User not found

429Rate limit exceeded — max 60 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/users/{id}/enable' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string"
}'

Request bodyapplication/json

{
  "reason": "string"
}

Example valueapplication/json

{
  "success": true,
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "disabled": true
  }
}

Get detailed information about a specific user.

Parameters

idstring ($uuid) | path*required

User ID

Responses

200User details

404User not found

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/users/{id}' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "name": "string",
  "disabled": true,
  "disabledAt": "2026-01-15T09:30:00.000Z",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "apiKeyCount": 0,
  "sessionCount": 0
}

List all users in the organization.

Parameters

limitstring | query

Max results (default 100, max 1000)

cursorstring | query

Pagination cursor

emailstring | query

Filter by email (partial match)

Responses

200List of users

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/users' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "user@example.com",
      "name": "string",
      "disabled": true,
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

API Keys

List and revoke API keys across the organization.

List all API keys in the organization.

Parameters

limitstring | query

Max results (default 100, max 1000)

cursorstring | query

Pagination cursor

userIdstring | query

Filter by user ID

includeRevokedstring | query

Include revoked keys (default false)

Responses

200List of API keys

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/api-keys' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "keyPrefix": "string",
      "name": "string",
      "scopes": [
        "string"
      ],
      "createdAt": "2026-01-15T09:30:00.000Z",
      "lastUsedAt": "2026-01-15T09:30:00.000Z",
      "expiresAt": "2026-01-15T09:30:00.000Z",
      "revokedAt": "2026-01-15T09:30:00.000Z",
      "user": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "user@example.com"
      }
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

Revoke an API key immediately. This is typically used as a SOAR action in response to compromised credentials.

Parameters

idstring ($uuid) | path*required

API key ID

Responses

200API key revoked successfully

404API key not found

409API key already revoked

429Rate limit exceeded — max 60 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/api-keys/{id}/revoke' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string"
}'

Request bodyapplication/json

{
  "reason": "string"
}

Example valueapplication/json

{
  "success": true,
  "apiKey": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "keyPrefix": "string",
    "revokedAt": "2026-01-15T09:30:00.000Z"
  }
}

Audit Logs

Query the audit trail for security and compliance monitoring.

Query audit logs with optional filtering. Useful for SIEM/SOAR integration.

Parameters

limitstring | query

Max results (default 100, max 1000)

cursorstring | query

Pagination cursor

actionstring | query

Filter by action type

sincestring | query

Filter events after this ISO timestamp

Responses

200List of audit logs

429Rate limit exceeded — max 300 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/audit-logs' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "action": "string",
      "occurredAt": "2026-01-15T09:30:00.000Z",
      "actor": {
        "id": "string",
        "type": "string",
        "name": "string",
        "metadata": {
          "additionalProp": null
        }
      },
      "targets": [
        {
          "id": "string",
          "type": "string",
          "name": "string",
          "metadata": {
            "additionalProp": null
          }
        }
      ],
      "context": {
        "location": "string",
        "userAgent": "string"
      },
      "metadata": {
        "additionalProp": null
      }
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

Analytics

Organization-wide cost, usage, and activity analytics for users, workflows, and projects — parity with the admin dashboards.

Per-user analytics matching the admin Members dashboard: AI usage, spend cap, spend status, organization role, and last-active time. Requires an organization admin API key.

Parameters

limitinteger | query

Max results (default 100, max 1000).

Default value : 100

cursorstring ($uuid) | query

Pagination cursor from a previous response's nextCursor.

emailstring | query

Filter by email (partial, case-insensitive match).

Responses

200Page of user analytics rows.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/analytics/users?limit=100' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "user@example.com",
      "name": "string",
      "disabled": true,
      "role": "string",
      "joinedAt": "2026-01-15T09:30:00.000Z",
      "lastActiveAt": "2026-01-15T09:30:00.000Z",
      "aiUsageCents": 0,
      "spendCapCents": 0,
      "spendStatus": "unlimited"
    }
  ],
  "spendLimitsEnabled": true,
  "defaultSpendCapCents": 0,
  "nextCursor": "string",
  "totalCount": 0
}

Org-wide workflow analytics matching the admin Workflows dashboard: owner, visibility, project, run count, last run, and average spend per run. Requires an organization admin API key.

Parameters

limitinteger | query

Max results (default 20, max 100).

Default value : 20

cursorstring | query

Pagination cursor from a previous response's nextCursor.

searchstring | query

Filter by workflow name or owner name/email (partial match).

sortstring | query

Sort order for the results.

Available values : recent, runs, spend, last-run, name

Default value : recent

periodstring | query

Time window shortcut for run count and average spend (all = all time). Ignored when startDate/endDate are provided.

Available values : 1d, 7d, 30d, all

Default value : all

startDatestring | query

Start of the time window (inclusive). Accepts ISO 8601, a YYYY-MM-DD day, a Unix timestamp (seconds or milliseconds), or a relative shortcut like 7d, 24h, or now. Overrides period when set.

endDatestring | query

End of the time window (inclusive). Same formats as startDate. A bare YYYY-MM-DD day (or today/yesterday) covers the whole UTC day through 23:59:59.999Z. Overrides period when set.

Responses

200Page of workflow analytics rows.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/analytics/workflows?limit=20&sort=recent&period=1d' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "description": "string",
      "owner": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string",
        "email": "user@example.com"
      },
      "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectName": "string",
      "projectNumber": "string",
      "visibility": "public",
      "runCount": 0,
      "lastRunAt": "2026-01-15T09:30:00.000Z",
      "avgSpendCents": 0
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

Org-wide project analytics matching the admin Projects dashboard: owners, members, attached files, workflow/session counts, and AI session spend. Requires an organization admin API key. This data is not otherwise available through the API.

Parameters

limitinteger | query

Max results (default 50, max 100).

Default value : 50

cursorstring | query

Pagination cursor from a previous response's nextCursor.

searchstring | query

Filter by project name, project number, or owner name/email (partial match).

sortstring | query

Sort order for the results.

Available values : spend, members, workflows, workflow_runs, assistant_sessions, files, recent, last_used, name, project_number

Default value : spend

periodstring | query

Time window shortcut for session counts and AI spend (all = all time). Ignored when startDate/endDate are provided.

Available values : 1d, 7d, 30d, all

Default value : all

startDatestring | query

Start of the time window (inclusive). Accepts ISO 8601, a YYYY-MM-DD day, a Unix timestamp (seconds or milliseconds), or a relative shortcut like 7d, 24h, or now. Overrides period when set.

endDatestring | query

End of the time window (inclusive). Same formats as startDate. A bare YYYY-MM-DD day (or today/yesterday) covers the whole UTC day through 23:59:59.999Z. Overrides period when set.

Responses

200Page of project analytics rows.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/analytics/projects?limit=50&sort=spend&period=1d' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "projectNumber": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "owners": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string",
          "email": "string",
          "image": "string"
        }
      ],
      "memberCount": 0,
      "attachedFileCount": 0,
      "workflowCount": 0,
      "workflowRunCount": 0,
      "assistantSessionCount": 0,
      "aiSessionSpendCents": 0,
      "lastUsedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

Granular, per-event AI spend with token breakdowns — the source of truth the aggregate analytics endpoints roll up. Filter by date range, user, project, workflow, or model, and sum costCents to reconcile totals to the cent. Defaults to the last 30 days when no range is given. Newest first. Requires an organization admin API key.

Parameters

limitinteger | query

Max results (default 100, max 1000).

Default value : 100

cursorstring ($uuid) | query

Pagination cursor from a previous response's nextCursor.

startDatestring | query

Start of the time window (inclusive). Accepts ISO 8601, a YYYY-MM-DD day, a Unix timestamp (seconds or milliseconds), or a relative shortcut like 7d, 24h, or now. Overrides period when set.

endDatestring | query

End of the time window (inclusive). Same formats as startDate. A bare YYYY-MM-DD day (or today/yesterday) covers the whole UTC day through 23:59:59.999Z. Overrides period when set.

userIdstring ($uuid) | query

Filter to events attributed to a specific user.

projectIdstring ($uuid) | query

Filter to events attributed to a specific project.

workflowIdstring ($uuid) | query

Filter to events attributed to a specific workflow.

modelstring | query

Filter to events for a specific model name.

Responses

200Page of usage events.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/analytics/usage-events?limit=100' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "occurredAt": "2026-01-15T09:30:00.000Z",
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "model": "string",
      "costCents": 0,
      "source": "assistant",
      "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectNumber": "string",
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "assistantSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "inputTokens": 0,
      "outputTokens": 0,
      "cacheCreationTokens": 0,
      "cacheReadTokens": 0
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

AI spend bucketed by UTC day over a date range, optionally split by user, project, workflow, or model. Defaults to the last 30 days when no range is given. Requires an organization admin API key.

Parameters

startDatestring | query

Start of the time window (inclusive). Accepts ISO 8601, a YYYY-MM-DD day, a Unix timestamp (seconds or milliseconds), or a relative shortcut like 7d, 24h, or now. Overrides period when set.

endDatestring | query

End of the time window (inclusive). Same formats as startDate. A bare YYYY-MM-DD day (or today/yesterday) covers the whole UTC day through 23:59:59.999Z. Overrides period when set.

bystring | query

Dimension to split each day by. none returns one total per day; otherwise each row carries the dimension value in groupKey.

Available values : none, user, project, workflow, model

Default value : none

Responses

200Daily spend buckets.

429Rate limit exceeded — max 30 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/analytics/daily-spend?by=none' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "date": "string",
      "groupKey": "string",
      "spendCents": 0,
      "eventCount": 0
    }
  ],
  "startDate": "2026-01-15T09:30:00.000Z",
  "endDate": "2026-01-15T09:30:00.000Z"
}

List sessions for every organization member. The response has the same shape as GET /agents. Requires an organization admin API key.

Parameters

limitinteger | query

Max results (default 20, max 100)

Default value : 20

cursorstring | query

Pagination cursor

statusstring | query

Filter by status (waiting, running, finished, stopped, failed)

Available values : waiting, running, awaiting_tool, finished, stopped, failed

workflowIdstring ($uuid) | query

Filter by workflow ID. Pass null to exclude agents launched from a workflow.

Responses

200List of agents

429Rate limit exceeded — max 20 requests per 1 minute per user. Retry after the Retry-After period.

Curl

curl -X 'GET' \
  'https://<your-domain>.nomic.ai/api/v0/analytics/agents?limit=20' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "waiting",
      "title": "string",
      "retry": {
        "kind": "provider_retry",
        "category": "string",
        "nextRetryAt": "2026-01-15T09:30:00.000Z",
        "attemptCount": 0,
        "provider": "string",
        "model": "string",
        "reason": "string",
        "operatorActionRequired": true
      },
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "workflowName": "string",
      "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectName": "string",
      "artifacts": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "type": "string",
          "name": "string",
          "createdAt": "2026-01-15T09:30:00.000Z"
        }
      ],
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "nextCursor": "string"
}