Overview

The Nomic HTTP API connects your systems to the same platform capabilities you use in the product—agents, file ingest, parsing, codes search, and organization administration.

Every request is versioned under one base URL on your Nomic instance. Use API keys from the Developer Console; responses follow shared conventions for errors, pagination, and rate limits.

Start here

Quickstart

Key, SKILL.md, and first API calls on the Agent API page.

Agent API

Launch, poll, follow-ups, artifacts, and workflows.

Rate limits

Tiers, headers, and 429 behavior.

What you can use

Agents

Background agents, workflows, and structured artifacts.

Files

Upload, search, and manage files your integrations process.

Parse

Submit and poll document parse jobs.

Codes search

Search building codes and standards programmatically.

Base URL

https://<your-domain>.nomic.ai/api/v0

Replace <your-domain> with your organization's Nomic domain.

Authentication

Authenticate every request with an API key in the Authorization header. Two schemes are accepted — use whichever your HTTP client makes easier:

Authorization: Bearer npk_...

or HTTP Basic with the key as the username and an empty password (handy for curl -u and many SIEM/enterprise clients):

curl "https://<your-domain>.nomic.ai/api/v0/users" -u "$NOMIC_API_KEY:"

Create and manage API keys in the Developer Console at /developer on your Nomic instance. Each key is scoped to a specific user, and usage is attributed to that user's account.

Scopes

API keys are granted scopes that control which API areas they can access. When creating a key, choose one or both of the broad scopes below.

Developer scope

Scope	Grants access to
developer	Developer APIs such as files, parsing, agents, codes.

Admin scope

Admin access requires the key owner to be an organization admin.

Scope	Grants access to
admin	Admin APIs such as users, analytics, API keys, and audit logs.

The admin scope covers the granular admin scopes, including admin:analytics:read used by the Analytics endpoints.

Errors

API error responses return a JSON body with:

• error: Human-readable description of what went wrong.
• code: Machine-readable error code you can use for programmatic handling. Present on validation, authentication, authorization, spend, and rate-limit failures; a few handlers (file upload, and requests to an unknown path) return error alone, so treat code as optional.
• issues (optional): Validation details for schema/path/query/body validation failures.

{
  "error": "File version not found",
  "code": "not_found"
}

Validation failures may include additional field-level details:

{
  "error": "Invalid request body",
  "code": "bad_request",
  "issues": [
    {
      "path": ["fileVersionId"],
      "message": "Required"
    }
  ]
}

Status codes

Code	Meaning
400	Bad request — invalid or missing parameters, including schema validation failures
401	Missing or invalid API key
403	API key lacks the required scope
404	Resource not found or not accessible
409	Request conflicts with current state
413	Payload too large (file upload exceeds 500 MB)
429	Rate limit exceeded — see Rate limits
500	Internal server error
501	Feature unavailable on this instance
503	Dependent service not configured

Error codes

Where a code is present, branch on it rather than parsing the human-readable error message:

code	Typical status	Meaning
bad_request	400	Invalid or missing parameters, including schema validation failures
unauthorized	401	Missing or invalid API key
payment_required	402	Spend limit reached
forbidden	403	Authenticated but missing the required scope
not_found	404	Resource not found or not accessible
conflict	409	Request conflicts with current state
rate_limited	429	Rate limit exceeded — see the Retry-After header
internal_server_error	500	Unexpected server error
not_implemented	501	Feature unavailable on this instance

Pagination

List endpoints use cursor-based pagination. Pass limit to control page size and cursor to fetch the next page.

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

The response includes:

Field	Type	Description
data	array	Items for the current page
nextCursor	string or absent	Pass as cursor to fetch the next page. Absent when there are no more results.
totalCount	number	Total matching items across all pages. Returned by users, audit logs, API keys, and analytics; not by agents, workflows, or file search.

Stability

All v0 endpoints are currently experimental. Request and response shapes may change between releases. We recommend testing against your integration when upgrading.

More resources

Platform documentation

Welcome page, product guides, and capabilities.

Product quickstart

Get started in the Nomic app (not the HTTP API).

API reference

OpenAPI explorer for every v0 endpoint.

Agents in depth: Agent API · Quickstart · SKILL.md (plain text)