> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nerdit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API reference

> Authenticate, deploy, wait for results, and handle safe retries using the Engine API.

Use `/api/*` for integrations. The Engine's default local base URL is `http://127.0.0.1:9321`; change it to your configured address. Only `/health` and `/gpus` retain root-level compatibility aliases.

The Engine serves its interactive reference at `/api/docs` and its machine-readable schema at `/api/openapi.json`. Browse [HTTP endpoints](/engine/api/health/health) for the 0.6.0 source contract, or fetch `/api/openapi.json` from your installed Engine to match its exact version. The schema includes request types, response types, required fields and operation IDs. MCP is a separate protocol and is not described by that OpenAPI file.

## Authenticate

Most requests require the Engine's Bearer token when authentication is configured. Use a scoped token for an integration; [Security](/engine/security) explains roles, scope, expiry and ownership. HTTP on loopback is appropriate for local requests; use a trusted encrypted connection for remote requests.

The examples assume you have securely provided a token as `NERDIT_TOKEN` in the current shell. This is an example variable used by curl, not an environment setting consumed by Nerdit.

```bash theme={null}
curl --fail http://127.0.0.1:9321/api/health
curl --fail -H "Authorization: Bearer ${NERDIT_TOKEN}" \
  http://127.0.0.1:9321/api/auth/check
curl --fail -H "Authorization: Bearer ${NERDIT_TOKEN}" \
  http://127.0.0.1:9321/api/services
```

The health endpoint is public. Successful auth check returns `{"ok": true}`. Readonly can read allowed resources but cannot write. A submitter can manage its own allowed workloads; administrator-only operations require admin. Do not infer permissions from an endpoint's visibility in this reference.

## Deploy a folder

Create the files from [Quickstart](/engine/quickstart), stay inside its `nerdit-hello` directory, then archive the **contents** of the application directory, with the Dockerfile and `nerdit.toml` at the ZIP root. This standard-library command writes the ZIP alongside the directory, avoiding self-inclusion:

```bash theme={null}
python3 -m zipfile -c ../nerdit-hello.zip Dockerfile index.html nerdit.toml
DEPLOY_REQUEST_ID=$(python3 -c 'import uuid; print(uuid.uuid4())')
curl --fail -H "Authorization: Bearer ${NERDIT_TOKEN}" \
  -F "archive=@../nerdit-hello.zip" -F "name=nerdit-hello" 'http://127.0.0.1:9321/api/deploy?dry_run=true'
curl --fail -H "Authorization: Bearer ${NERDIT_TOKEN}" \
  -H "Idempotency-Key: ${DEPLOY_REQUEST_ID}" \
  -F "archive=@../nerdit-hello.zip" -F "name=nerdit-hello" http://127.0.0.1:9321/api/deploy
```

The example creates a fresh `DEPLOY_REQUEST_ID` for this deployment. Retain it for an identical retry; do not regenerate it on each retry. A deploy response means accepted, not ready. Inspect `last_deploy.version`, then wait for that generation:

```bash theme={null}
curl --fail -H "Authorization: Bearer ${NERDIT_TOKEN}" \
  'http://127.0.0.1:9321/api/services/nerdit-hello/wait?timeout=300'
curl --fail -H "Authorization: Bearer ${NERDIT_TOKEN}" \
  http://127.0.0.1:9321/api/services/nerdit-hello/diagnose
```

Use the actual service name from `nerdit.toml` or the deploy response. Add the returned generation as the `version` query parameter when concurrent deployments are possible. For remote agents generating new files, use the workspace endpoints: write files, then deploy the workspace. A local filesystem path is not a remote upload.

## Retries and errors

Writes accept `Idempotency-Key`; configuration can make it mandatory. Reuse the same key only for the same logical operation. An identical successful replay does not repeat the mutation. A method/path mismatch, and a changed body where body comparison applies, return `422 idempotency_key_conflict`. Secret-carrying and multipart requests deliberately do not use a body digest: never rely on a reused key to apply changed content.

A dry run does not claim its idempotency key. A mutation interrupted after a committed write can return `409 idempotency_interrupted`; inspect the resource before choosing a new key. Secret-returning responses do not replay plaintext: token creation or rotation shows the new credential once.

Errors provide `code`, `message`, optional `hint`, compatibility `detail` and usually `request_id`. Branch on the code, preserve request IDs for diagnosis, and redact credentials from client logs.

## Bounded reads and streams

Follow each paginated response's `next_cursor` until it is absent. Logs support bounded tails and literal `grep` / ISO-8601 `since` filters; check their endpoint parameters in the schema. `/api/events` provides the durable event feed, while stream endpoints use server-sent events. Clients must send their normal authorization on authenticated streams; do not assume a browser EventSource will attach a Bearer header.

## Secrets and recovery

Secret writes return key names, not values. Resource configuration and diagnostics redact Engine-managed secrets, but application output is still your responsibility. Control-plane backup and logical database dump operations return server-side archive metadata; they are not file-download endpoints. Read [Backups and recovery](/engine/backup-recovery) before restoring anything.

## Endpoint reference

Browse [HTTP endpoints](/engine/api/health/health) in this area's navigation for the full typed reference: request fields, response schemas, constraints and examples. Use the schema from your installed Engine for client generation when its version differs from this source reference.