Build a 3D product pipeline into your application.

Overview

One API, from source file to published 3D

The Platform API is designed for backend integrations. Your application creates a model record, uploads a file directly to Cadloom-managed storage, waits for conversion to finish, then publishes the saved viewer configuration.

1. 1
   CreateCreate the model container.
2. 2
   UploadTransfer the source file securely.
3. 3
   ProcessPoll revisions or receive a webhook.
4. 4
   PublishMake the configured viewer live.

Authentication

Keep API keys on your server

Create an API key in your workspace. Its secret is displayed once. Send it in the Authorization header and never place it in browser code, mobile applications, public repositories, or iframe markup.

Authorization: Bearer cad_live_your_secret_key

Quickstart

Create your first model

Export your key as an environment variable, then create a model container. The returned modelId is used by every following request.

curl --request POST https://cadloom.com/api/v1/models \
  --header "Authorization: Bearer $CADLOOM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"ApexFlow valve"}'

Start the upload

curl --request POST https://cadloom.com/api/v1/models/mod_abc12345/uploads \
  --header "Authorization: Bearer $CADLOOM_API_KEY" \
  --header "Idempotency-Key: upload-order-4821-v1" \
  --header "Content-Type: application/json" \
  --data '{
    "filename":"valve.step",
    "contentType":"application/step",
    "sizeBytes":18420591,
    "quality":"balanced"
  }'

Transfer and complete the upload

# Use the target returned by the previous request.
# Send every target.headers value exactly as returned.
curl --request PUT "$UPLOAD_URL" \
  --header "Content-Type: application/step" \
  --upload-file ./valve.step

curl --request POST \
  "https://cadloom.com/api/v1/models/mod_abc12345/revisions/rev_def67890/complete" \
  --header "Authorization: Bearer $CADLOOM_API_KEY"

Files and uploads

Direct signed upload

The upload-intent response contains a short-lived target with its URL, HTTP method, and required headers. Upload the entire binary with a single PUT request to that URL; resumable upload sessions are not currently supported. Do not send your Cadloom API key to the storage URL. When the transfer succeeds, call /complete to verify the object and queue processing.

Choose draft, balanced, fine, or ultra quality. balanced is the default and recommended starting point.

Asynchronous processing

Track the revision, not the request

Completing an upload queues conversion and returns immediately. Poll the revisions endpoint with backoff, or subscribe to processing webhooks. Wait for READY before publishing; the AR requirements below and your plan limits also apply. Terminal failure is FAILED.

GET https://cadloom.com/api/v1/models/{modelId}/revisions
Authorization: Bearer $CADLOOM_API_KEY

Publishing choices

Publish without opening the editor

For an automated website-only workflow, send {"includeAr":false} to the publish endpoint. This disables AR only in that publication; your saved viewer settings remain unchanged. Repeating the same publish is idempotent.

curl --request POST https://cadloom.com/api/v1/models/{modelId}/publish \
  --header "Authorization: Bearer $CADLOOM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"includeAr":false}'

To include AR, open and save the viewer in Cadloom first so its current AR files are prepared, then publish without this option. The API does not generate AR files. Missing or outdated AR files return 409 ARTIFACT_NOT_READY; retrying alone cannot prepare them.

API reference

Model lifecycle endpoints

Errors and retries

Every error includes a request ID

{
  "schemaVersion": 1,
  "error": {
    "code": "ARTIFACT_NOT_READY",
    "message": "Process a 3D file before publishing this model.",
    "retryable": true,
    "requestId": "req_01h...",
    "details": {}
  }
}

Log the requestId for support. Retry only when retryable is true, using exponential backoff with jitter. A 401 means an API key is missing, invalid, or revoked; a 403 means the key lacks a required permission. A 402 indicates a plan or usage entitlement; 409 means the resource is not ready or conflicts with its current state; 429 indicates rate limiting.

Webhooks

React when processing or publishing changes

Configure a public HTTPS endpoint in Workspace → Developers. Cadloom sends processing.completed, processing.failed, publication.published, and publication.unpublished. Cadloom makes up to three immediate delivery attempts in total. Delivery runs in-process rather than through a durable queue, so events can be lost if the service restarts. Poll revision status as a fallback; do not rely on exactly-once delivery.

{
  "id": "evt_abc123",
  "type": "processing.completed",
  "createdAt": "2026-09-11T16:42:00Z",
  "data": {
    "tenantId": "ten_...",
    "modelId": "mod_...",
    "resourceId": "rev_..."
  }
}

Verify every delivery

Compute HMAC-SHA256 over timestamp + "." + rawBody with the webhook signing secret. Compare it with Cadloom-Webhook-Signature using a timing-safe comparison and reject timestamps older than five minutes.

const crypto = require("node:crypto");

function verifyCadloomWebhook(rawBody, headers, secret) {
  const timestamp = headers["cadloom-webhook-timestamp"];
  const received = headers["cadloom-webhook-signature"]?.replace(/^v1=/, "");
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  return received?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Website delivery

Embed the published experience

The REST API manages the model lifecycle. To place a published viewer on a product page, use the iframe code generated by Cadloom or the optional web component SDK.