Introduction

The Nucleus AI API lets you take an open-weight base model, fine-tune it on your own data and serve the result as a private model. Most integrations use the managed path: upload a dataset, submit a fine-tuning job and poll it to completion. Teams running RL, DPO or custom losses drive the low-level training loop directly. The managed fine-tuning and training loop guides walk through each path end to end.

This page covers the conventions every route shares. Each reference page then documents its endpoints with parameters, example requests and example responses.

Base URLs

One API key works across all three surfaces. All traffic is HTTPS.

Authentication

Every route except GET /v1/health requires an API key in the request header. There is no session, no cookie and no token exchange: one long-lived key, presented on every call.

Authorization: Bearer nk_live_8xQ2...

Keys use the nk_live_ prefix in production and nk_test_ in the sandbox. Each key carries one or more scopes (read, train, infer, admin), and every endpoint in this reference declares the scope it needs. Never pass the key in a query string; it lands in access logs and browser history. The Anthropic-compatible routes also accept Anthropic's native x-api-key header; if both are present, Authorization wins.

See Authentication for scopes, project-bound keys and rotation.

Errors

Every error returns a JSON envelope with a machine-readable type and a human-readable message:

{
  "error": {
    "type": "authentication_error",
    "message": "No API key provided. Pass Authorization: Bearer <key>."
  }
}

A 403 adds required_scope so you can see which scope the key is missing. Rate limits apply per key; a 429 carries a Retry-After header in seconds, and you should back off on that value rather than a fixed interval. See Errors and retries and Rate limits.

Pagination

List endpoints accept limit and offset query parameters and return newest-first. Responses carry a cursor object with offset and total_count so you can page through the full set:

{
  "data": ["..."],
  "cursor": { "offset": 0, "total_count": 7 }
}

See Pagination for the full contract.

Idempotency

All GET and DELETE routes are safe to retry. Five POST routes allocate real resources (GPUs, storage or a queue slot) and accept an Idempotency-Key header so a retried request cannot allocate twice:

• Upload a dataset
• Create a fine-tuning job
• Create a training run
• Create a checkpoint
• Export weights

Send the header whenever your client retries automatically. See Errors and retries.

Asynchronous operations

Long-running requests return 202 Accepted with an operation ID. Poll GET /v1/operations/{operation_id} until it completes, or register a webhook to be notified.

Content types

Requests and responses are application/json unless a route states otherwise. The exceptions: dataset uploads are multipart/form-data, streaming endpoints emit text/event-stream, and 204 No Content responses have no body.

Endpoints