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. It is available on Business and Enterprise organization instances.

Start here​

What you can use​

Base URL​

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

Replace <your-domain> with the part of your instance's hostname before .nomic.ai — for example, acme.drive if you sign in at acme.drive.nomic.ai, giving https://acme.drive.nomic.ai/api/v0. Individual plan accounts do not include the Agent API.

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 the broad developer scope, the broad admin scope, or any of the granular developer and admin scopes.

Developer scopes​

Developer scopes grant access to an API area; each request still runs as the key's owner, so project roles, file permissions, and budget admin rights apply as they would in the app.

Admin scopes​

Admin access requires the key owner to be an organization admin. A key keeps its admin scopes only while its owner remains an admin, so give integrations such as a SIEM poller a key owned by a dedicated admin account.

The admin scope includes every granular admin scope. Prefer the narrowest scope an integration needs; a SIEM integration only needs admin:audit:read.

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, rate-limit, and unknown-path failures; a few handlers (file upload, user lookups and enable/disable, API key revocation, and parse status) 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​

Error codes​

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

Artifact exports return their own, more specific codes, listed on that page.

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:

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​

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