/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 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 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 asNERDIT_TOKEN in the current shell. This is an example variable used by curl, not an environment setting consumed by Nerdit.
{"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, stay inside itsnerdit-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:
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:
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 acceptIdempotency-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’snext_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.