AtlasAR Cloud API

Introduction

The AtlasAR Cloud API turns 3D files and product photos into light, true-size models for the web and AR (Android Scene Viewer, iOS Quick Look, WebXR), hosts them on a CDN, and tells your server when they are ready. It is a REST API: resources have predictable URLs, requests and responses are JSON (model files are sent as their own bytes), and errors use standard HTTP status codes with a stable machine-readable code.

Quick start

Optimise a GLB and get a hosted, true-size model in two calls: upload it, then read it back (or wait for the webhook).

# 1. Upload a GLB: made exactly 30 cm tall, optimised at the default level
curl -X POST "https://cloud.wpaugmentedreality.com/v1/models/upload?name=Vase&height_cm=30" \
  -H "Authorization: Bearer $ATLASAR_KEY" \
  -H "Content-Type: model/gltf-binary" \
  --data-binary @vase.glb

# 2. Read it until "status" is "ready" (or use a webhook)
curl "https://cloud.wpaugmentedreality.com/v1/models/mdl_9yX2…" -H "Authorization: Bearer $ATLASAR_KEY"

// Node.js 18+ (fetch is built in)
import { readFile } from 'node:fs/promises';

const res = await fetch('https://cloud.wpaugmentedreality.com/v1/models/upload?name=Vase&height_cm=30', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ATLASAR_KEY}`, 'Content-Type': 'model/gltf-binary' },
  body: await readFile('vase.glb'),
});
const model = await res.json(); // 202: { id: "mdl_…", status: "queued", … }

$res = wp_remote_post( 'https://cloud.wpaugmentedreality.com/v1/models/upload?name=Vase&height_cm=30', array(
    'headers' => array( 'Authorization' => 'Bearer ' . ATLASAR_KEY, 'Content-Type' => 'model/gltf-binary' ),
    'body'    => file_get_contents( 'vase.glb' ),
    'timeout' => 60,
) );
$model = json_decode( wp_remote_retrieve_body( $res ), true ); // 202: [ 'id' => 'mdl_…', 'status' => 'queued' ]

Authentication

Every /v1 request carries the site's API key as a bearer token. Keys look like ar_live_… (32 random characters) and are stored only as a SHA-256 hash: they are shown once, when created.

Authorization: Bearer ar_live_Xq3…

• One key per site. A key sees only its own site's models, webhook and statistics.
• Server side only. Never put a key in browser code: the viewer SDK needs none.
• Active or pending. A new email gets an active key at once. A new site for an existing account gets a pending key: every call answers 403 approval_required until the account owner approves the emailed link.
• WordPress sites connect from AtlasAR › Integrations in the plugin, which registers the site and stores the key encrypted; no key needs to be copied.

Errors

Successful requests answer 2xx. Errors answer 4xx (your request) or 5xx (ours), always with the same body, so code can branch on error.code. The full list is under Error codes.

{
  "error": {
    "code": "invalid_height",
    "message": "height_cm must be a number from 0.5 to 1000 (the real product height), or left out to keep the size of the model."
  }
}

Idempotency

Send an Idempotency-Key header (8–80 characters: letters, digits, _, -) with model-creating requests. A retry with the same key never creates or bills a second model: it answers 200 with the model of the first request.

Idempotency-Key: order-1042-vase

Plans, limits and billing

Usage is counted in units: optimising a GLB costs 1 unit, photo to 3D costs 10. Models are billed on success: a request is accepted at 0 units (202) and billed only when its model is ready. A model that fails, or that you delete before it is ready, is never billed.

• At most 5 models per account are processed at a time (429 too_many_in_progress).
• The monthly allowance is checked when a model is accepted, so the last accepted model may finish just past the limit.
• Busy servers answer 503 server_busy with Retry-After; such requests are never billed.

Sites and usage

curl -X POST "https://cloud.wpaugmentedreality.com/v1/projects/register" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "custom", "site_url": "https://shop.example", "email": "owner@shop.example" }' 

{
  "api_key": "ar_live_Xq3…",
  "key_prefix": "ar_live_Xq3",
  "project_id": 41,
  "plan": "free",
  "approval": "active"
}

curl "https://cloud.wpaugmentedreality.com/v1/usage" -H "Authorization: Bearer $ATLASAR_KEY"

{
  "usage": {
    "plan": "free",
    "period": "2026-10",
    "units_used": 7,
    "units_limit": 20,
    "units_remaining": 13,
    "resets_at": "2026-11-01T00:00:00Z"
  }
}

Models

The model object

curl -X POST "https://cloud.wpaugmentedreality.com/v1/models/upload?name=Vase&height_cm=30&level=balanced" \
  -H "Authorization: Bearer $ATLASAR_KEY" \
  -H "Content-Type: model/gltf-binary" \
  -H "Idempotency-Key: vase-2026-10" \
  --data-binary @vase.glb

{
  "id": "mdl_9yX2kQ4LrT8vN1pA6sZ3bW",
  "name": "Vase",
  "source": "glb",
  "status": "queued",
  "height_cm": 30,
  "files": null,
  "units": 0,
  "usage": { "plan": "free", "units_used": 7, "units_limit": 20, … }
}

curl -X POST "https://cloud.wpaugmentedreality.com/v1/models?name=Mug&height_cm=10" \
  -H "Authorization: Bearer $ATLASAR_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @mug.jpg

{
  "data": [ { "id": "mdl_9yX2…", "name": "Vase", "status": "ready", … } ],
  "next_before": "mdl_7aB1…"
}

{
  "id": "mdl_9yX2kQ4LrT8vN1pA6sZ3bW",
  "name": "Vase",
  "status": "ready",
  "height_cm": 30,
  "source": "glb",
  "files": { "glb": "https://cloud.wpaugmentedreality.com/files/p/41/mdl_9yX2kQ4LrT8vN1pA6sZ3bW/3f9c8a1d2b7e4f60.glb" },
  "stats": { "triangles": 29871, "glb_mb": 0.77, "texture_px": 1024, "texture_count": 2, "level": "balanced" },
  "budget": "pass",
  "viewer": null,
  "error": null,
  "created_at": "2026-10-18T09:12:44Z",
  "expires_at": null
}

{
  "viewer": {
    "title": "Oak chair",
    "background": "#f5f5f4",
    "arPlacement": "floor",
    "hotspots": [ { "position": "0 0.4 0.2", "normal": "0 1 0", "label": "Solid oak seat" } ]
  }
}

{ "ok": true }

Optimisation levels

The level of an upload sets how far a model is simplified. high is the default and suits most product pages. The browser optimiser in the SDK uses the same table, so a model looks the same wherever it was made. A quality from 0–100 is also accepted (90+ maximum, 75+ high, 60+ balanced, 40+ low, below that minimum).

Direct uploads

Large files go straight from your server or the browser to storage, never through the API. Three steps:

1. Ask for an upload URL with the exact size and type.
2. PUT the file to upload_url with exactly the headers given (type and size are signed).
3. Create the model with POST /v1/models/upload (or /v1/models) and a JSON body { "upload_id", "name", "height_cm" }. An upload is used once, by the site that asked for it, within 15 minutes.

{
  "id": "upl_4Hq…",
  "upload_url": "https://cloud.wpaugmentedreality.com/…",
  "method": "PUT",
  "headers": { "Content-Type": "model/gltf-binary", "Content-Length": "48211330" },
  "expires_at": "2026-10-18T09:27:44Z"
}

Free 3D model library

Ready-made, optimised models published by AtlasAR (made by us, or CC0 / CC BY). Any site key may use them, on any plan, at no cost: nothing is metered.

{
  "data": [ {
    "id": "lib_2Kd…", "slug": "oak-dining-chair", "name": "Oak dining chair",
    "category": "furniture", "tags": ["chair", "wood"], "height_cm": 82,
    "size": 1048576, "triangles": 31204, "license": "CC0-1.0",
    "credit": "", "poster_url": "https://cloud.wpaugmentedreality.com/library/posters/lib_2Kd….webp"
  } ],
  "total": 118,
  "categories": { "furniture": "Furniture", "decor": "Decor", "…": "…" }
}

Viewer analytics

How shoppers use your models' 3D views on every website that shows them. The viewer SDK counts by itself for <atlasar-viewer model="mdl_…"> and sends only totals (no cookies, no IP address, no visitor or page data). A page can turn it off with analytics="none".

Events: view, turn, open, ar, tryon, tryon_sample, snapshot, and with Premium modules hotspot, other_model, variant. Daily totals are kept 400 days.

{
  "days": 30,
  "totals": { "view": 1840, "turn": 612, "ar": 233, "tryon": 41 },
  "daily": { "2026-10-17": { "view": 71, "ar": 9 } },
  "models": [ { "id": "mdl_9yX2…", "name": "Vase", "counts": { "view": 902, "ar": 120 } } ]
}

Webhooks

AtlasAR Cloud calls your HTTPS endpoint when a model is ready or failed, so you never need to poll. One endpoint per site. Events: model.ready, model.failed (data.model is the model object) and ping.

{ "url": "https://shop.example/atlasar-webhook", "secret": "whsec_…" }

Verify a delivery

Each delivery carries AtlasAR-Event-Id, AtlasAR-Event-Type and AtlasAR-Signature: t=<unix time>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" with your secret. Check it on the raw body, refuse deliveries older than 5 minutes, and answer 2xx within 10 seconds. Delivery is at-least-once: drop repeated event ids. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h; redirects are never followed.

$body = file_get_contents( 'php://input' );
parse_str( str_replace( ',', '&', $_SERVER['HTTP_ATLASAR_SIGNATURE'] ?? '' ), $sig );
$fresh = isset( $sig['t'] ) && abs( time() - (int) $sig['t'] ) <= 300;
$valid = isset( $sig['v1'] ) && hash_equals( hash_hmac( 'sha256', $sig['t'] . '.' . $body, $secret ), $sig['v1'] );
if ( ! $fresh || ! $valid ) {
    http_response_code( 401 );
    exit;
}
$event = json_decode( $body, true ); // [ 'type' => 'model.ready', 'data' => [ 'model' => … ] ]

import crypto from 'node:crypto';

// Express: app.post('/atlasar-webhook', express.raw({ type: 'application/json' }), handler)
function handler(req, res) {
  const sig = Object.fromEntries(String(req.get('AtlasAR-Signature') || '').split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', SECRET).update(`${sig.t}.${req.body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
  const valid = sig.v1 && expected.length === sig.v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!fresh || !valid) return res.sendStatus(401);
  const event = JSON.parse(req.body); // { type: 'model.ready', data: { model } }
  res.sendStatus(204);
}

Error codes