Overview

The Nomic HTTP API connects your systems to the same platform capabilities you use in the product—agents, file ingest, parsing, extraction, 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.

Extract

Structured extraction from supported file types.

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:

Authorization: Bearer npk_...

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, API keys, and audit logs.

Errors

All 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.
• 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
401	Missing or invalid API key
403	API key lacks the required scope
404	Resource not found or not accessible
413	Payload too large (file upload exceeds 500 MB)
422	Schema validation failed
429	Rate limit exceeded — see Rate limits
500	Internal server error
501	Feature unavailable on this instance
503	Dependent service not configured

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

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)