API reference

Requires files:read. Cursor pagination within this organization and key mode.

Requires files:write. Reserve an immutable upload of up to 10 MiB in any accepted format.

PUT the exact bytes to upload.url with the returned headers, then complete the upload; the API verifies size, SHA-256 and the file's contents before it becomes ready. Live uploads need an approved account. Larger files use POST /v1/files/resumable. Idempotency-Key replays for 24 hours return a renewed upload URL.

Reserve a file larger than a simple upload allows, up to the plan's limit (at most 1 GiB).

Needs an approved account (or an internal storage grant). The answer is an S3 multipart upload: PUT each listed part to its URL (exact size, any order). Part URLs are capabilities: keep them private. Replay the same request with the same Idempotency-Key to resume or to renew URLs; parts already sent are kept (at most three new multipart starts per file, failed responses included). Complete assembles the parts and always queues background verification; poll the file until ready or rejected.

Requires files:read.

Requires files:write. Prefer: respond-async queues durable verification.

Poll GET /v1/files/{file_id} until ready or rejected before creating a job. Resumable uploads always complete asynchronously. Without the preference, bounded legacy uploads still complete synchronously. Repeated completion calls do not enqueue duplicate verification work.

Requires jobs:read. Cursor pagination within this organization and key mode.

Requires jobs:write. Queue a job for a ready file.

Sandbox (test-key) jobs return explicitly simulated results and incur no charge. A live job holds its expected cost in credits and is charged its run time when it finishes (usage); 402 insufficient_credits names the required and available credits when the balance cannot cover the hold (GET /v1/balance). 503 capacity_exhausted (with Retry-After and a reason) means a live job cannot start now: no GPU for a GPU recipe (paused, spend_limit, no_gpu_available, controller_offline), or no Exact Check worker running for a cad_check (cad_unavailable); nothing is queued or held. 501 feature_unavailable when live work, the input's format or size, or a live cad_check (its CPU lane's build) is not enabled. While a live job waits, queue gives its position, estimated_start_at and the GPU fleet's capacity (null for a cad_check); a queued live job fails free (capacity_exhausted) after 10 minutes without GPU capacity (a cad_check: without an Exact Check worker) or 24 hours in the queue. The Idempotency-Key is required; a replay within 24 hours returns the job as it is now, with Idempotent-Replayed: true.

Requires jobs:read. Poll status; analysis is published only after trusted verification.

Requires jobs:write. Fence the attempt; accepted cancellation prevents result publication.

Requires jobs:read. Free: judge the stored measurements of a succeeded cad_check job against the limits table of this organization, without a new job. Without process every process and material is judged; process alone judges each of its materials; material needs a process. 409 when the job is not a succeeded cad_check or its stored measurements expired; 503 (with Retry-After) when the limits table cannot be read.

Requires jobs:read. Durable ordered events; pass next_after to resume polling.

Requires jobs:read. The limits per process and material that apply to this organization: the global table with the organization's own overrides merged over it. version changes whenever either changes; nothing stores it with a check, and each evaluation answers with the version it judged by (table_version). gap_floor_mm is the higher of the global floor and any floor set for this organization.

Requires webhooks:manage. Every endpoint of the organization of this key's mode, oldest first, without secrets. Not paged: an account holds at most 20 endpoints of each mode, and all of them are in data.

Requires webhooks:manage. Register an HTTPS address to be told when a cad_check job finishes (name it in notify.webhook_endpoint when creating the job). The endpoint belongs to the key's mode: only keys of that mode can list, name or delete it. An account holds at most 20 endpoints of each mode; registering another is 409 conflict (delete one first).

The address must be https on port 443 or 1024 to 65535, and resolve to public hosts only: private, loopback, link-local and other non-routable addresses are refused (422, with the same sentence whether or not the name resolves), and checked again at every delivery.

The response holds the signing secret; verify Printy3D-Signature: t=<unix>,v1=<hex> as HMAC-SHA256 of <t>.<raw body> under it, in constant time, and reject a t more than 300 seconds from your clock. The payload is {event, job_id, status} and nothing else; fetch the job for the rest. A delivery is attempted up to 5 times in all, 1 m, 5 m, 30 m and 2 h apart. With an Idempotency-Key (kept 24 hours), a retry returns the same endpoint and secret with Idempotent-Replayed: true instead of registering a second one.

Requires webhooks:manage. An endpoint of this key's mode; deliveries still waiting for it are called off. One already being sent when the endpoint is deleted may still arrive.

Requires artifacts:read. Return a temporary download URL; keep it confidential.

Requires artifacts:read. Empty until the entire result manifest has passed verification.

Requires jobs:write. A succeeded job's mesh output in one format, every piece in it.

200 ready with the artifact when the job generated that format. Otherwise 202 converting: one conversion job (conversion_job_id) makes it on the GPU fleet and is charged like any convert job (credits held and charged; 402, 429 and 503 as for POST /v1/jobs). Asking again returns the same conversion, or starts a new one after a failure; poll GET /v1/jobs/{job_id}/exports/{format}. Test keys export only the formats a job generated (501 for a conversion).

Requires artifacts:read. The export's state; 404 when it was never asked for.

Requires usage:read. The organization's credits; 1 credit = 1 second of a job's run.

Live jobs hold credits when submitted and are charged their run time when they finish; test-mode jobs never change the balance. POST /v1/jobs answers 402 insufficient_credits when a live job's hold exceeds available_credits.

Requires usage:read. Every credit movement, newest first.

Requires keys:manage. Lists metadata in this organization and live/test mode.

Requires keys:manage; scopes and restrictions cannot exceed the issuer.

Idempotency-Key is retained for 24 hours. Replays return issuance metadata with secret=null and Idempotent-Replayed=true; plaintext is returned once.

Requires keys:manage. Never returns a credential secret or its hash.

Requires keys:manage. Repeated revocation of the same visible key is harmless.

Requires keys:manage. Creates one successor without broadening authority.

The old key works during its grace period unless expired or revoked. An idempotent replay returns metadata with secret=null. Retain a recovery manager when requesting zero-grace self-rotation.

Requires files:read. enabled is live qualification; test_enabled is local sandbox support.

Requires org:read. Returns only the authenticated organization.

Requires files:read. The values each repair profile fixes; the rest is filled from the engine's recommendation (recommended) or the documented defaults.

Liveness: the process is up. Never touches a dependency.

Check the migrated database, non-owner runtime role and local storage.

Redis is not required for the local sandbox. Hosted object storage is not probed here until staging qualifies it (render-platform.md §4).