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 Nomic agent 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 ($uuid) | query

Pagination cursor from a previous response's nextCursor.

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",
      "workflowVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "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

403workflowVersionId names an unreleased version and the caller cannot edit the workflow

404Workflow or workflow version 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",
  "workflowVersionId": "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",
  "workflowVersionId": "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",
    "workflowVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "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",
    "workflowVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "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. Supports steps (thinking, tool, and compaction events).

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",
    "workflowVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "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",
    "workflowVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "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 ($uuid) | query

Pagination cursor from a previous response's nextCursor.

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

Return the caller's temporary upload folder, creating it on first use. Upload a file into it by passing the returned id as parentId on POST /files/upload. Launching an agent with that file id adopts the file into the agent's session folder. Files that are never launched are discarded. This is not a durable location. Requires the developer:files:upload scope.

Parameters

No parameters

Responses

200Temporary upload folder.

401Missing or invalid Authorization header / API key.

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

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

503Upload integration not configured for this instance.

Curl

curl -X 'POST' \
  'https://<your-domain>.nomic.ai/api/v0/files/temp-folder' \
  -H 'accept: application/json'

Example valueapplication/json

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

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:upload 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:upload 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 ($uuid) | query

Pagination cursor from a previous response's nextCursor.

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",
  "totalCount": 0
}

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, create, edit, and release the workflows agents are 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 ($uuid) | query

Pagination cursor from a previous response's nextCursor.

projectIdstring ($uuid) | query

Filter to workflows in a specific project.

querystring | query

Case-insensitive substring match on workflow name or description.

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

Create a workflow owned by the caller, private to them, with an unreleased first version. Test it with launch_agent and the returned versionId as workflowVersionId, then release_workflow_version when it works. Context files and tags are attached in the builder UI.

Parameters

No parameters

Responses

200Workflow created

400Validation error, or a capability or the model is not available

403No write access to the project

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/workflows' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "instructionMarkdown": "string",
  "metadata": {
    "greeting": "string",
    "placeholder": "string",
    "icon": "string",
    "workflowClass": "string",
    "inputs": "string",
    "outputs": "string"
  },
  "mode": "low",
  "model": "auto",
  "requestedFiles": [
    {
      "name": "string",
      "description": "string",
      "optional": false,
      "multiple": false
    }
  ],
  "capabilities": {
    "codeSearch": true,
    "webSearch": true
  },
  "linkedArtifacts": [
    {
      "name": "string",
      "content": "string"
    }
  ],
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

Request bodyapplication/json

{
  "name": "string",
  "description": "string",
  "instructionMarkdown": "string",
  "metadata": {
    "greeting": "string",
    "placeholder": "string",
    "icon": "string",
    "workflowClass": "string",
    "inputs": "string",
    "outputs": "string"
  },
  "mode": "low",
  "model": "auto",
  "requestedFiles": [
    {
      "name": "string",
      "description": "string",
      "optional": false,
      "multiple": false
    }
  ],
  "capabilities": {
    "codeSearch": true,
    "webSearch": true
  },
  "linkedArtifacts": [
    {
      "name": "string",
      "content": "string"
    }
  ],
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "versionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version": 0,
    "createdNewVersion": true,
    "linkedArtifacts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      }
    ],
    "builderPath": "string"
  }
}

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

Parameters

workflowIdstring ($uuid) | path*required

Workflow ID.

versionIdstring ($uuid) | query

Version to return. Omit for the latest version, which is the unreleased draft when one exists.

Responses

200The workflow and the requested version

403Can run the workflow, but not edit it

404Workflow or version 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/workflows/{workflowId}' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "metadata": {
      "additionalProp": null
    },
    "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "isPublic": true,
    "isShared": true,
    "isArchived": true,
    "releasedVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "latestVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "builderPath": "string",
    "version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 0,
      "isReleased": true,
      "instructionMarkdown": "string",
      "mode": "string",
      "model": "string",
      "requestedFiles": [
        {
          "name": "string",
          "description": "string",
          "optional": true,
          "multiple": true
        }
      ],
      "capabilities": {
        "additionalProp": null
      },
      "linkedArtifacts": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string",
          "type": "string",
          "content": "string"
        }
      ],
      "contextFiles": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string"
        }
      ],
      "tags": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string"
        }
      ]
    }
  }
}

Write a new candidate version, as saving in the builder does. Fields left out are copied from baseVersionId (default: the latest version). 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. Nothing is released: test the result with launch_agent and workflowVersionId, then release_workflow_version.

Parameters

workflowIdstring ($uuid) | path*required

Workflow ID.

Responses

200The written version

400Validation error, an artifact id not linked to the base version, or an unavailable capability or model

403Can run the workflow, but not edit it

404Workflow or base version not found

409The workflow is archived

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/workflows/{workflowId}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "baseVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "description": "string",
  "instructionMarkdown": "string",
  "metadata": {
    "greeting": "string",
    "placeholder": "string",
    "icon": "string",
    "workflowClass": "string",
    "inputs": "string",
    "outputs": "string"
  },
  "mode": "low",
  "model": "auto",
  "requestedFiles": [
    {
      "name": "string",
      "description": "string",
      "optional": false,
      "multiple": false
    }
  ],
  "capabilities": {
    "codeSearch": true,
    "webSearch": true
  },
  "linkedArtifacts": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    {
      "name": "string",
      "content": "string"
    }
  ]
}'

Request bodyapplication/json

{
  "baseVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "description": "string",
  "instructionMarkdown": "string",
  "metadata": {
    "greeting": "string",
    "placeholder": "string",
    "icon": "string",
    "workflowClass": "string",
    "inputs": "string",
    "outputs": "string"
  },
  "mode": "low",
  "model": "auto",
  "requestedFiles": [
    {
      "name": "string",
      "description": "string",
      "optional": false,
      "multiple": false
    }
  ],
  "capabilities": {
    "codeSearch": true,
    "webSearch": true
  },
  "linkedArtifacts": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    {
      "name": "string",
      "content": "string"
    }
  ]
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "versionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version": 0,
    "createdNewVersion": true,
    "linkedArtifacts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      }
    ],
    "builderPath": "string"
  }
}

List every version of a workflow with its run count and cost, newest first. Read a version's content with get_workflow and versionId. Requires edit access to the workflow.

Parameters

workflowIdstring ($uuid) | path*required

Workflow ID.

Responses

200Versions, newest first

403Can run the workflow, but not edit it

404No workflow 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/workflows/{workflowId}/versions' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 0,
      "isReleased": true,
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "changeNote": "string",
      "authorEmail": "string",
      "runCount": 0,
      "averageCostUsd": 0,
      "totalCostUsd": 0
    }
  ]
}

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

Parameters

workflowIdstring ($uuid) | path*required

Workflow ID.

versionIdstring ($uuid) | path*required

Workflow version ID.

Responses

200The released version

403Can run the workflow, but not edit it

404Workflow or version not found

409The workflow is archived

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/workflows/{workflowId}/versions/{versionId}/release' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "releasedVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version": 0,
    "previousReleasedVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Budgets

Read the budgets you administer and set per-member spend limits.

The budgets the caller administers, with funding, overage behavior, and per-user limit settings. Organization admins get the organization budget and every project budget; a project admin gets that project's budget. All budgets fit in one page, so nextCursor is always null.

Parameters

scopestring | query

Only return budgets of this scope type.

Available values : organization, project

projectIdstring ($uuid) | query

Only return this project's budget.

Responses

200Budgets in the organization.

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/budgets' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "scope": {
        "type": "organization",
        "projectBudgetsEnabled": true
      },
      "funding": {
        "amountCents": 0,
        "spentCents": 0,
        "remainingCents": 0,
        "renewal": {
          "cadence": "weekly",
          "amountCents": 0
        }
      },
      "onExhausted": "block",
      "memberLimits": {
        "enabled": true,
        "defaultCents": 0,
        "period": "daily",
        "resetsAt": "2026-01-15T09:30:00.000Z"
      }
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

Give a project its own budget, funded from the organization budget. Funding, onExhausted, renewal, and the member-limit default are applied together: if the organization budget cannot cover amountCents, nothing is created. Project budgets must be turned on for the organization. Requires admin access to the project; funding it also requires admin access to the organization budget.

Parameters

No parameters

Responses

201The new budget.

400Validation error, or a member-limit default without a period (invalid_budget_change).

403The caller cannot administer the project or the organization budget.

404No project with this ID the caller can read.

409The project already has a budget (budget_exists), the organization budget cannot cover the amount (insufficient_funds), or project budgets are turned off (project_budgets_disabled).

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/budgets' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amountCents": 0,
  "onExhausted": "block",
  "renewal": {
    "cadence": "weekly",
    "amountCents": 0
  },
  "memberLimits": {
    "enabled": true,
    "defaultCents": 0,
    "period": "daily"
  }
}'

Request bodyapplication/json

{
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amountCents": 0,
  "onExhausted": "block",
  "renewal": {
    "cadence": "weekly",
    "amountCents": 0
  },
  "memberLimits": {
    "enabled": true,
    "defaultCents": 0,
    "period": "daily"
  }
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scope": {
      "type": "organization",
      "projectBudgetsEnabled": true
    },
    "funding": {
      "amountCents": 0,
      "spentCents": 0,
      "remainingCents": 0,
      "renewal": {
        "cadence": "weekly",
        "amountCents": 0
      }
    },
    "onExhausted": "block",
    "memberLimits": {
      "enabled": true,
      "defaultCents": 0,
      "period": "daily",
      "resetsAt": "2026-01-15T09:30:00.000Z"
    }
  }
}

A single budget by ID. Pass organization as the ID for the organization budget, which holds the organization-wide per-user limits. Requires admin access to the budget.

Parameters

idstring ($uuid) | string | path*required

Budget ID, or organization for the organization budget.

Responses

200The budget.

404No budget with this ID that the caller administers.

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/budgets/{id}' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scope": {
      "type": "organization",
      "projectBudgetsEnabled": true
    },
    "funding": {
      "amountCents": 0,
      "spentCents": 0,
      "remainingCents": 0,
      "renewal": {
        "cadence": "weekly",
        "amountCents": 0
      }
    },
    "onExhausted": "block",
    "memberLimits": {
      "enabled": true,
      "defaultCents": 0,
      "period": "daily",
      "resetsAt": "2026-01-15T09:30:00.000Z"
    }
  }
}

Change a budget. Omitted fields keep their current value. On a project budget you can change funding, onExhausted, renewal, and member limits; a change that includes amountCents is applied as one step, so a refused allocation changes nothing. The organization budget is funded by its contract, so only its memberLimits can be changed. Pass organization as the ID for the organization budget. Requires admin access to the budget.

Parameters

idstring ($uuid) | string | path*required

Budget ID, or organization for the organization budget.

Responses

200The budget after the change.

400Validation error, a funding field on the organization budget (organization_budget_contract_funded), or a project member-limit default without a period (invalid_budget_change).

403The caller cannot administer the budget, or the parent budget it draws funding from.

404No budget with this ID that the caller administers.

409The parent budget cannot cover the new amount (insufficient_funds), or project budgets are turned off (project_budgets_disabled).

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/budgets/{id}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "amountCents": 0,
  "onExhausted": "block",
  "renewal": {
    "cadence": "weekly",
    "amountCents": 0
  },
  "memberLimits": {
    "enabled": true,
    "defaultCents": 0,
    "period": "daily"
  }
}'

Request bodyapplication/json

{
  "amountCents": 0,
  "onExhausted": "block",
  "renewal": {
    "cadence": "weekly",
    "amountCents": 0
  },
  "memberLimits": {
    "enabled": true,
    "defaultCents": 0,
    "period": "daily"
  }
}

Example valueapplication/json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scope": {
      "type": "organization",
      "projectBudgetsEnabled": true
    },
    "funding": {
      "amountCents": 0,
      "spentCents": 0,
      "remainingCents": 0,
      "renewal": {
        "cadence": "weekly",
        "amountCents": 0
      }
    },
    "onExhausted": "block",
    "memberLimits": {
      "enabled": true,
      "defaultCents": 0,
      "period": "daily",
      "resetsAt": "2026-01-15T09:30:00.000Z"
    }
  }
}

Each member's own limit, the limit that applies to them, and their spend in the budget's current window. The organization budget covers every user in the organization; a project budget covers the project's members. Requires admin access to the budget.

Parameters

idstring ($uuid) | string | path*required

Budget ID, or organization for the organization budget.

limitinteger | query

Max results (default 50, max 100).

Default value : 50

cursorstring | query

Pagination cursor from a previous response's nextCursor.

Responses

200Page of budget members.

404No budget with this ID that the caller administers.

409A project budget while project budgets are turned off (project_budgets_disabled).

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/budgets/{id}/members?limit=50' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "string",
      "name": "string",
      "limitCents": 0,
      "effectiveLimitCents": 0,
      "spentCents": 0,
      "status": "unlimited"
    }
  ],
  "nextCursor": "string",
  "totalCount": 0
}

Set or clear per-user limits in one batch, applied atomically: nothing is written unless every entry is valid. A limitCents of null clears the member's own limit so the budget default applies. Sending the same batch twice changes nothing. Member limits must be turned on for the budget, and every user must be one of the budget's members. Requires admin access to the budget.

Parameters

idstring ($uuid) | string | path*required

Budget ID, or organization for the organization budget.

Responses

200The changed members after the batch.

400Validation error, or an unknown, repeated, or non-member user.

403The organization budget, for a caller who is not an organization admin.

404No budget with this ID that the caller administers.

409Member limits are off for this budget (member_limits_disabled), or project budgets are turned off (project_budgets_disabled).

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/budgets/{id}/members' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "members": [
    {
      "user": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "limitCents": 0
    }
  ]
}'

Request bodyapplication/json

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

Example valueapplication/json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "string",
      "name": "string",
      "limitCents": 0,
      "effectiveLimitCents": 0,
      "spentCents": 0,
      "status": "unlimited"
    }
  ]
}

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

Inspect the calling key, and list and revoke API keys across the organization.

Describe the calling credential: its owner, the scopes it can exercise, and the operationIds it may call. Any valid key can call this; use it to verify a key before doing work.

Parameters

No parameters

Responses

200The calling credential

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/current' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "data": {
    "apiKeyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "string"
    },
    "organizationId": "string",
    "scopes": [
      "string"
    ],
    "operations": [
      "string"
    ]
  }
}

List all API keys in the organization.

Parameters

limitstring | query

Max results (default 100, max 1000)

cursorstring ($uuid) | query

Pagination cursor from a previous response's nextCursor.

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 ($uuid) | query

Pagination cursor from a previous response's nextCursor.

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",
      "workflowVersionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "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"
}

Integrations

List the drives (document libraries) under a SharePoint site and whether Nomic syncs each one. Pass driveId values to PUT /api/v0/integrations/sharepoint/sites to sync specific drives.

Parameters

siteUrlstring | query*required

The SharePoint site URL, e.g. https://example.sharepoint.com/sites/allcompany

Responses

200The drives under the site.

400Malformed site URL.

401Missing or invalid API key.

403The API key lacks the required scope, its owner is not an admin, or Nomic cannot access the site.

404The SharePoint integration is not installed, or the site does not exist.

409The SharePoint integration is disabled or has no credentials.

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/integrations/sharepoint/drives?siteUrl=string' \
  -H 'accept: application/json'

Example valueapplication/json

{
  "siteUrl": "string",
  "drives": [
    {
      "driveId": "string",
      "fileId": "string",
      "name": "string",
      "webUrl": "string",
      "syncing": true
    }
  ]
}

Start syncing the drives under a SharePoint site: every drive, or only the driveIds given. Drives Nomic already syncs are left as they are, so repeating a request is safe.

Parameters

No parameters

Responses

200Every drive under the site, with whether Nomic now syncs it.

400Malformed site URL, or a driveIds entry the site does not have.

401Missing or invalid API key.

403The API key lacks the required scope, its owner is not an admin, or Nomic cannot access the site.

404The SharePoint integration is not installed, or the site does not exist.

409The SharePoint integration is disabled or has no credentials.

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

Curl

curl -X 'PUT' \
  'https://<your-domain>.nomic.ai/api/v0/integrations/sharepoint/sites' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "siteUrl": "string",
  "driveIds": [
    "string"
  ]
}'

Request bodyapplication/json

{
  "siteUrl": "string",
  "driveIds": [
    "string"
  ]
}

Example valueapplication/json

{
  "siteUrl": "string",
  "drives": [
    {
      "driveId": "string",
      "fileId": "string",
      "name": "string",
      "webUrl": "string",
      "syncing": true,
      "created": true
    }
  ]
}