Examples and OpenAPI

Reference clients for the seven operations. GET /context requires Headless SDK. The other six work on Headless API alone. They use placeholder credentials. Opening a docs page does not call Antla.

Included files

File	Purpose
`/docs/assets/examples/antla-client.mjs`	Fetch-based client for all seven API operations, raw-byte upload, safe submission semantics and bounded polling
`/docs/assets/examples/custom-ui.html`	Plain browser custom-UI example with catalog check, funnel resolution, email gate, upload, generation and resume
`/docs/assets/examples/AntlaTryOn.tsx`	React wrapper that sets initial attributes before attaching the element
`/docs/assets/examples/AntlaClient.swift`	Swift URLSession transport, upload, visitor registration, generation and polling
`/docs/assets/examples/client.test.mjs`	Mocked transport tests; no live Antla calls
`/docs/openapi.json`	OpenAPI 3.1 description of the seven operations, plus CORS preflight

These are examples, not a published SDK. Your app still owns accessibility, sign-in, image processing, and production testing.

Use the JavaScript client

import { createAntlaClient } from "./antla-client.mjs";

const client = createAntlaClient({
  apiBaseUrl: "https://app-antla.com/api/headless",
  sdkKey: "YOUR_ANTLA_SDK_KEY",
});

const controller = new AbortController();
const started = await client.createGeneration({
  funnelId: 123,
  productId: "gid://shopify/Product/123",
  variantId: "gid://shopify/ProductVariant/456",
  imageUrl: "https://YOUR_PUBLIC_IMAGE_HOST/customer-photo.jpg",
}, controller.signal);

// Save started.jobId immediately in your application.
const final = await client.pollGeneration(started.jobId, {
  signal: controller.signal,
  uniqueUserId: started.uniqueUserId || undefined,
  onTemporary: (url) => showPreview(url),
  onIdentity: (id) => saveVisitorId(id),
});

showFinalImage(final.imageUrl);

showPreview, saveVisitorId and showFinalImage are your application functions. The supplied HTML example implements a basic visible flow.

The client never automatically retries generation POSTs. It throws SubmissionUncertainError for an ambiguous outcome, including a lost response or server error. Explicit 4xx errors remain AntlaApiError instances with status/code information.

Polling retries a limited number of consecutive transient GET failures and honors IP Retry-After within the overall deadline. It distinguishes job errors, pending storage, final storage and legacy results.

Run the browser example

Serve the downloaded /docs/assets/examples directory using your normal local web server, then open custom-ui.html. Enter your own matching environment/key, real product and variant GIDs, and an approved photo.

The sample supports the first 100 variants; paginate before using it with larger products. It keeps a visitor ID in local storage and the last job in session storage, scoped to the API environment and returned Shopify shop. It does not persist the SDK key.

The sample checks file type and size but does not reproduce all of the official browser SDK’s orientation and resize behavior. It has no checkout implementation and is not a finished native or production storefront.

Press Generate once to send real requests. That may consume generation credits. Resume saved job polls an existing job. Stop waiting only stops client work.

Use the Swift example

Provide an HTTPS base URL ending in /api/headless and the merchant’s SDK key. Connect the functions to your existing native image picker, storage and UI. After start, persist the returned job ID before calling poll.

The reference poller checks cancellation between calls and gives each request a 20-second timeout. Its overall loop deadline can be exceeded by an in-flight request by up to that request timeout; wrap the operation in an app-level deadline if you need a strict bound.

Marshal result/preview callbacks to your UI’s appropriate actor/thread. The file does not implement a screen, photo picker, funnel lookup or cart flow. Use the same endpoint contract for those operations.

OpenAPI use

Import /docs/openapi.json into your client generator. Replace the example server with the base URL from the merchant’s installation if it differs, and send X-Antla-SDK-Key on every Antla request.

The document version is the date of this reference. It is not a version segment in the API URL. Generated clients still need your email gate, visitor storage, consent, polling loop, and the rule against replaying an uncertain generation POST.

Verification

Run node --test docs/assets/examples/client.test.mjs in a modern Node environment for the mocked JavaScript checks. The test suite covers temporary/final results, job errors, legacy results, malformed states, uncertain POSTs, email rejection, upload-header separation, deadlines and throttling.

Device behavior, production credentials, image compatibility, and checkout belong on the launch checklist.