Lolly Beta
Launch App

ManageJobs, sharing and delivery

Render jobs and batches

Note: Lolly Work

This guide covers the optional organisation service. Configuration, console and API paths refer to your Lolly Work instance. The packaged console keeps its release-matched copy of this guide.

This page is for the automation builder or admin who renders through Lolly Work and needs the result to survive a restart: submit a render or a batch, fetch the file, check the result and recover work a crash interrupted. A render job uses your instance's tools, inputs and renderer, and each job belongs to the person or service token that submitted the job.

For a quick render straight to bytes, with no stored job, use GET /render (server renders).

Render once and fetch the file

Save a request as render.json, using a tool from your instance:

{
  "toolId": "qr-code",
  "format": "svg",
  "inputs": { "url": "https://example.com" },
  "priority": 0,
  "maxAttempts": 3
}
lw renders submit render.json --idempotency-key campaign-qr-v1 --json
lw renders list --json
lw renders show <renderId> --json
lw renders output <renderId> --out qr.svg
lw renders evidence <renderId> --out evidence.json
lw renders cancel <renderId>
lw renders retry <renderId> --idempotency-key campaign-qr-retry --json
lw renders deliver <renderId> --destination campaign-archive --name "Launch QR"
Check: What a finished render shows

submit returns the job's id at once. show reports its state, the number of attempts and a structured failure when one occurs. The output is available after success, and downloading it verifies the stored bytes against the job's SHA-256 receipt.

  1. queuedwaiting for a runner
  2. runningclaimed under a 30-second lease
  3. succeededoutput and receipt stored
  • failedAttempts used up, an invalid input or a policy refusal.
  • cancelledYou cancelled it while it was queued or running.
  • RetryA new job with retryOf pointing back. The original history stays.
  • A crashThe expired claim lets another replica take the job, spending an attempt.

A job is queued, then running, then succeeded, failed or cancelled. A retry is a new job that points back at the one it replaces.

signed by Lollywork-renders-states.htmlHTMLpixels, not shapes11 KBAI generatedgenerated by Claude Opus 5.5Check it yourselfGet the signed file

HTTP

Method and pathResult
POST /api/v1/rendersThe request above; 202 for a new job, 200 for an idempotent replay
GET /api/v1/renders?limit=50&offset=0Caller-owned jobs the caller may still see; nextOffset for paging; limit 1 to 100
GET /api/v1/renders/:idRequest, state, attempts and output receipt
GET /api/v1/renders/:id/output/defaultThe stored bytes; 409 before success or on an integrity failure, 410 OUTPUT_EXPIRED after retention removed them, 410 OUTPUT_UNAVAILABLE if they are otherwise missing
GET /api/v1/renders/:id/evidenceThe execution receipt and render identity; 409 before success, on a receipt or identity integrity failure, or for an identity version this server cannot check; 404 EVIDENCE_UNAVAILABLE for older outputs with no evidence
DELETE /api/v1/renders/:idCancel queued or running work; completed history is kept and returns 409
POST /api/v1/renders/:id/retryA new job from a failed or cancelled predecessor; accepts Idempotency-Key
POST /api/v1/renders/:id/deliveriesSends the finished output to an organisation destination by reference (delivering an automation output); Idempotency-Key accepted

Authentication is required even on an open instance. Creating, running and reading a job check current tool visibility, tool.use and export.server. Each attempt reads the current member or service token, so disabling the member, revoking the token or removing the grant stops queued work from running. The owner can still cancel after losing a tool grant. These routes share rateLimit.automation. A service token minted with scopes reaches them with render, and sends an output with delivery (service tokens). An agent holding such a token can submit and follow the same renders and batches, and cancel a render, over the organisation MCP endpoint (connect an agent over MCP).

Batches with durable rows

Use /api/v1/render-batches when each row needs its own stored result and recovery history. Save this as batch.json:

{
  "toolId": "qr-code",
  "format": "svg",
  "inputs": {},
  "rows": [
    { "key": "home", "inputs": { "url": "https://example.com" } },
    { "key": "support", "inputs": { "url": "https://example.com/support" } }
  ]
}
lw render-batches submit batch.json --idempotency-key campaign-qr-v1 --json
lw render-batches list --json
lw render-batches show <batchId> --json
lw render-batches manifest <batchId> --out manifest.json
lw render-batches archive <batchId> --out outputs.zip
lw render-batches cancel <batchId>
lw render-batches retry <batchId> --idempotency-key campaign-qr-v1-retry --json
lw renders output <childRenderId> --out qr.svg

show and manifest read a consistent snapshot of the parent and its children: counts per state, and ordered rows with the row key, render id, request, attempt, failure and, after success, the output URL and SHA-256 receipt. The downloadable JSON adds manifestVersion: 1. It is a status snapshot, not an approved release. Fetch each output through its child render URL, or download them together from the archive. Successful rows stay downloadable even when another row fails.

A batch starts queued and becomes running when any row starts or finishes. Once every row has finished, the batch is failed if any row failed, otherwise cancelled if any row was cancelled, otherwise succeeded. progress.done counts every finished row, including failures and cancellations. Counts come from the child records, so they cannot drift from a saved counter.

Cancel and retry. Cancelling stops every unfinished child at once and keeps successful and failed rows. A retry needs a finished batch with at least one failed or cancelled row.

Batch A

Finished, state failed

  • homesucceeded
  • supportfailed
  • presscancelled
  • Retry batch A

Batch B, retryOf A

A new parent

  • homereused: same job, same bytes
  • supportnew job
  • pressnew job
  • Batch A stays as it wasIts manifest never changes.
  • New rows use current contentSo one batch can hold outputs from different content versions.

A batch retry makes a new parent that reuses the rows that succeeded and re-runs only the ones that did not.

signed by Lollywork-renders-batch-retry.htmlHTMLpixels, not shapes12 KBAI generatedgenerated by Claude Opus 5.5Check it yourselfGet the signed file

The retry creates a new parent with retryOf, reuses successful child jobs and creates new linked renders only for the rows that did not succeed. The old manifest stays unchanged. Retried rows use current policy and content while reused rows keep their original bytes, so a retried batch can hold outputs from different content versions. A direct lw renders retry creates an independent render; use the batch retry to get a new parent manifest with the replacements.

The batch routes
Method and pathResult
POST /api/v1/render-batchesThe request above; 202 on creation, 200 on idempotent replay
GET /api/v1/render-batches?limit=10&offset=0Caller-owned summaries and nextOffset; limit 1 to 20
GET /api/v1/render-batches/:idParent and ordered child status
GET /api/v1/render-batches/:id/manifestDownload the current JSON manifest
GET /api/v1/render-batches/:id/archiveDownload a finished batch as one ZIP; 409 until every row has finished or when no row has output
DELETE /api/v1/render-batches/:idCancel unfinished rows; 409 if already finished with no cancelled rows
POST /api/v1/render-batches/:id/retryA new parent keeping successes; accepts Idempotency-Key

Batch idempotency keys are scoped to the submitting principal and separate from single-render keys. Creating, reading and retrying check current tool grants, and the owner can still cancel after a grant is removed. These routes also share rateLimit.automation. The older /api/v1/batch job and ZIP contract is separate and does not create these child jobs.

Fill the rows from a data source

Send bind in place of rows to read the rows from a governed JSON or CSV source, with the same source, query and as rules as /api/v1/batch:

{
  "toolId": "qr-code",
  "format": "svg",
  "bind": { "source": "cms://products/current.csv", "keyField": "sku" }
}

keyField is the column that holds each row's key, and that column is not passed to the tool as an input. Without one the rows are named row-1, row-2 and so on, in source order. A source that cannot be read, has an unusable or repeated key, or does not hold 1 to 200 rows answers 400 DATA_BINDING_ERROR and creates nothing. Each row then passes the same input checks as a typed row.

The source is read once, at submission, by a caller who holds the grants, and the rows are kept on the batch. An idempotent replay identifies the batch by its source, so it returns the original batch and reads nothing. A retry reruns the rows the batch already has, even if the source has changed since.

Download a batch as one ZIP

GET /api/v1/render-batches/:id/archive answers a finished batch with a ZIP, streamed so it does not wait for the whole archive. Members are named <row key>.<format>, and each is checked against its receipt before any of it is written.

manifest.json, the last member, holds an entry per row: its key, render id, state and whether the row is in the archive, with the file name, size and SHA-256 when it is, and a reason when it is not. The reason is NOT_SUCCEEDED, OUTPUT_EXPIRED, OUTPUT_UNAVAILABLE or OUTPUT_INTEGRITY, and a row that failed also carries its error.

An archive holds at most 2 GiB, and a larger batch answers 413 ARCHIVE_TOO_LARGE before any byte is sent: download those rows from their own output URLs. If something breaks after streaming has started, the connection closes, and the truncated file has no central directory for an extractor to read.

Be told when a render finishes

Add callbackUrl to a render or batch request, and Work sends one signed POST when the job finishes, whether it succeeded, failed or was cancelled. A batch calls back once, when its last row finishes, and its rows send nothing of their own.

The URL must exactly match notify.webhook.url or use an origin listed in automation.callbacks.allowedOrigins. Anything else answers 403 CALLBACK_URL_NOT_ALLOWED at submission, and is checked again before each send. A redirect from the receiver counts as a failed attempt.

These callbacks use the same outbox as job callbacks: the same x-lolly-signature and x-lolly-timestamp headers, the same x-lolly-delivery-id on every attempt, the same retries over about 45 minutes and the same recorded outcomes. The stored entry is written by the call that finishes the record, so a restart cannot lose one.

Render bodyMeaning
renderId, state, statusUrl, deliveryIdThe job, how it ended, where to read it and the idempotency key
outputUrl, outputSha256, outputTokenAfter success: the file, its digest and a token that reads the file. null otherwise
error{ code, message } after a failure
Batch bodyMeaning
batchId, state, progress, statusUrl, deliveryIdThe batch, how it ended, its counts, where to read it and the idempotency key
manifestUrl, archiveUrlThe manifest, and the archive when any row succeeded
outputTokenA token to read the manifest and archive

outputToken lasts 24 hours. Send it as the x-lw-render-token header, and the receiver needs no account of its own. It reads that render's output and evidence, or that batch's manifest and archive, and nothing else, and it reads under the owner's current grants, so removing a grant stops it too. It travels only in the signed body and the header, never in a URL.

GET /api/v1/renders/:id and GET /api/v1/render-batches/:id report callback, with its id, state, attempts, lastOutcome, lastStatus and nextAttemptAt, once the job has finished. A 2xx answer is recorded as acknowledged, which says the receiver answered and not what it did next.

The URL is part of the request for idempotency, so the same key with another URL answers 409 IDEMPOTENCY_KEY_REUSED. It is not part of the render identity, because where a result is announced says nothing about what was rendered. A manual retry keeps the URL, and the new job makes its own call.

Verify the produced file

Add "verification": "output-v1" to a render or batch request to require a file check before the output is published. To require particular dimensions, use an object:

{
  "toolId": "card",
  "format": "png",
  "inputs": {},
  "verification": {
    "profile": "output-v1",
    "widthPx": 1200,
    "heightPx": 630
  }
}

Use a tool that produces those dimensions: the numbers are assertions about the delivered file and do not resize the artwork. Each dimension is optional, and the string form and { "profile": "output-v1" } mean the same. Submit through lw renders submit or lw render-batches submit as usual.

The work/output-v1 profile checks the actual format, MIME type, readability and requested dimensions after watermarking, provenance and signing. SVG is parsed as XML without running scripts or loading linked resources, and PNG and JPEG are fully decoded with sharp. The receipt's inspection records each check, its result, the measured dimensions, the final SHA-256 and the detector version.

OutputEvidenceLimit
SVGXML root and namespace; explicit absolute viewport dimensions, with CSS units converted at 96 px/in2 MiB; DTDs unsupported; no rendering, linked-resource or visibility check; percentages and viewBox-only dimensions stay unknown
PNG, JPEGRecognised container and a complete pixel decode; pixel dimensions32 MiB and 16 million pixels; one frame; decoding limited to 10 seconds
PDFContainer signatureNo independent PDF decoder in Lolly Work; readability and dimensions stay undetermined

A required check must return pass. Missing, failed and undetermined checks stop a verified render with OUTPUT_VERIFICATION_FAILED; the failed record keeps error.inspection, and no output is published. A mismatch stops after one attempt, and a manual retry keeps the original requirements and creates a new record. Batch children have the same checks and keep their own outcomes.

Draft requests without verification keep ordinary export behaviour, including PDF export where a worker is configured. New durable draft receipts also carry inspection results, which may show failed or undetermined checks; older receipts without inspection have unknown check coverage. A verified request always runs fresh and never reuses a draft cache entry.

Evidence and identity

Every new durable render, batch children included, keeps two records with its output: an execution receipt of what the attempt read and produced, and a render identity that fingerprints what it resolved. Download both with lw renders evidence <renderId> --out evidence.json.

Execution evidence

The output descriptor links to /api/v1/renders/:id/evidence and reports the receipt id and coverage: "partial".

FactReceiptIdentity
Loaded tool version, its file digests and combined source hash, engine and document API versionsyestool version, source hash, engine and document API versions
The request: tool, format, inputs, verification and production settingshashes of the prepared input values, and the formatthe whole typed request with key order ignored, plus the resolved input values; priority and attempts left out
Profile and groupshashesprofile digest and group set
Policy and catalog versionsyescatalog version
Design-system revision and a digest of the effective policyyesyes
Format, pixel dimensions, watermark, renderer, rasterizer, signing-certificate digestyesyes
Catalog and provider assets read through Lolly Work's bridges: id, format, declared version, actual byte digest and sizeyesid, format, declared version and digest
For the local runtime: hashes of initialized inputs and hydrated markup, hook-error and dropped-asset countsyesno
Output SHA-256 and a digest of the whole receiptyesno

The effective policy covers this tool's enforcement settings, the access each input resolves to for the caller's groups after design-system rules are applied, and any managed design-system rules. Profile values, provider credentials, asset bytes and internal storage references are never copied into the receipt. Asset digests come from the bytes actually read, not from a catalog checksum.

Leases, caching and storage bounds

Output and evidence settle under the same worker lease, so a stale attempt cannot replace either. Durable attempts bypass the output cache, so observations come from the attempt that produced the stored bytes; an idempotent replay still returns the original job and its original receipt. Ordinary render-cache keys distinguish nested input values, profiles, export dimensions, watermark settings and loaded source content, and hooks run afresh because they can read state outside the host.

Storage is bounded to 256 distinct asset receipts and 128 KiB of asset metadata. More observations set asset-observation-limit, and a provider result whose bytes cannot be observed sets asset-bytes-unobserved. Evidence lives in the existing output JSON record and needs no extra migration. Earlier successful outputs stay downloadable but have no invented receipt, so their evidence endpoint reports 404 EVIDENCE_UNAVAILABLE. Evidence can be read even if the stored output bytes later become unavailable, and reads use the same ownership and current-grant checks as the render itself.

Render identity

The request fingerprint used for idempotency identifies the typed request. The render identity binds that request to what the successful attempt resolved, and the output descriptor reports identity.id with coverage: "partial".

The evidence download recomputes the identity from the stored request and receipt, and reports 409 EVIDENCE_INTEGRITY when they disagree. What the work/render-identity-v1 identity hashes is fixed, so a later release that hashes something else uses a new apiVersion, and a server that meets an identity version it cannot check reports 409 IDENTITY_VERSION_UNSUPPORTED. A receipt for a different tool or format fails the attempt with RENDER_EVIDENCE_MISMATCH before any output is stored. Outputs made before identities existed, and outputs without a receipt, have no identity.

What a receipt does not prove

Note: Receipts are partial evidence, not a lockfile or an approval
  • Coverage is partial. The pinned engine does not yet emit a canonical dependency graph. Template and global resource reads, fonts, composition and historical replay are not fully attested, and every receipt carries explicit limitations for these boundaries.
  • A worker render is attested less. Its receipt records the tool loaded for Lolly Work's own validation and the prepared context; the worker's actual engine, inputs, profile, tool, asset and font environment are not attested, and it has no local-runtime section.
  • An empty asset list means no bridge reads were recorded, not that the output is proven free of dependencies.
  • Nothing is pinned for later attempts. Attempts and manual retries use the current mounted content, profile and policy. Neither the request fingerprint nor the render identity is a lockfile for every font, asset, token, engine and policy version, and neither proves a historical reconstruction.
  • It is not a signed attestation, cache-reuse authority or an automatic stale or current decision. Lolly Work does not reuse outputs by identity.
  • It is not approval. A render identity says which bytes a render read, not whether anyone approved them, and a passing file check does not establish brand compliance, protected copy or chart preservation, correct fonts, matching appearance, accessibility, print readiness or publication approval. The file check is separate from the proposed still-2d/1 visual conformance suite and from C2PA signing.

Hosting and recovery

The standalone server starts the runner automatically.

Note: Before you rely on recovery

Apply 0032_render_resources.sql, 0033_render_batches.sql and, for callbacks, delivery by reference and output retention, 0079_durable_render_parity.sql through the normal migrations runner. Use PostgreSQL and a persistent BlobStore for recovery across restarts; memory mode is for evaluation and loses its data when the process exits. Every replica must use the same database, byte store and compatible mounted content.

Storage. Finished requests and outputs are kept with no automatic expiry or deletion unless you set policy.retention.renderOutputDays, so include them in storage sizing and backups. Losing attempts normally delete their unreferenced blobs; an ambiguous database commit or a failed cleanup may leave an orphan for later collection. Changes to jobs are audited.

Output retention. With renderOutputDays set, a daily sweep on the long-lived server marks each output older than that many days as expired, and removes its bytes on a later pass. From the moment it is marked, the output answers 410 OUTPUT_EXPIRED and its descriptor reports expiredAt. The record, the receipt and the identity stay, so lw renders evidence keeps working. Each expiry is audited as render.output.expire. A delivery that points at a render keeps its output for as long as the delivery exists. A batch retry renders an expired row again rather than reusing it, and an archive lists that row as OUTPUT_EXPIRED.

Not built yet. Dependency snapshots, campaign reconciliation, a general event feed with subscriptions and collection-wide approval and promotion. Callbacks announce the end of the job that asked for one, and no other event. A successful render alone publishes nothing to a destination, so send the output when it is ready to leave.

Production still checks and permitted repairs

A durable request can carry production beside verification. output-v1 keeps its contract, and the additional lolly/production-still-v1 engine profile checks explicit requirements on the final file. It can also try a bounded set of input alternatives you permit, to repair a failed check.

The engine also offers lolly/production-motion-v1 to Lolly's CLI and MCP. Lolly Work's governed renderer accepts only the still profile and refuses a motion contract when it parses the request, so updating the engine pin does not add video rendering to Lolly Work.

An example request with a contract and a repair plan
{
  "toolId": "card",
  "format": "svg",
  "inputs": { "legalCopy": "Legal 125", "layout": "short" },
  "production": {
    "contract": {
      "profile": "lolly/production-still-v1",
      "id": "campaign-card",
      "revision": "1",
      "format": "svg",
      "width": 200,
      "height": 100,
      "pages": 1,
      "alpha": "any",
      "requirements": [
        { "id": "legal", "kind": "text", "location": "legal", "expected": "Legal 125" }
      ]
    },
    "repair": {
      "protected": ["legalCopy"],
      "permitted": { "layout": ["short", "long"] },
      "maxAttempts": 2,
      "when": [{ "findingId": "requirement.legal", "input": "layout" }]
    }
  }
}
What each kind of requirement can check

Files. SVG inspection parses XML without running scripts or fetching linked resources. Text requirements address exact SVG ids, links compare href values and node requirements compare a serialized XML element digest; text presence does not prove visible placement. PNG and JPEG use bounded sharp decoding. Optional pdfinfo, pdftotext and pdftoppm enable PDF page geometry, full extracted page text (page:1 and so on) and one-page pixels at 96 dpi; missing programs give unknown coverage. PDF colour, overprint and press conformance are outside this profile.

Inputs. An input requirement uses a declared input id as its location and a canonical JSON SHA-256 as its expected value (productionDigest(value) in the engine). Local renders collect the requested values from the exporting runtime. Chromium observations are matched to the downloaded SVG and included in the signed worker response, and the client checks that every observed id was requested. Conflicting observations, missing collectors and older web shells stay undetermined. The report keeps hashes, within a 1 MiB combined JSON observation budget.

For Lolly Chart, protect the exact CSV data, field mappings, number format, units in axis titles, yScaleType, yZero and yMax that the approved brief requires. Reusable Lolly Design tools use their declared copy and data inputs. JSON types and array order are kept. A contract-protected input cannot become a repair target even if a repair plan lists that input. These checks establish source identity; visible labels, chart geometry and clipping need separate output checks, and shell observations are not an attestation against hostile tool code.

Comparison with a reference. An optional contract comparison takes referenceSha256, channelTolerance, maxChangedFraction and regions with id, x, y, width, height, minSsim and maxInkDelta. Put the exact reference bytes in production.referenceBase64; the request's 1 MB cap still applies. The reference digest is validated on admission and inspection. Comparison uses native decoded 8-bit sRGB pixels, whole-image RGBA differences and region luminance and ink measurements. It never resizes a reference or borrows a preview comparison's success, and explicit text requirements stay independent.

Sources and resources. Optional source and context digest requirements, and resource requirements, use actual execution observations. Local source hashes follow evidence.tool.sourceHash, and context hashes use the canonical evidence.context object. Resource locations are observed asset ids or worker response URLs. Conflicting digests under one resource id are unresolved, and a required old identity that is unavailable never silently resolves to the catalog's latest content.

Browser renders. Production browser renders need an upgraded worker: its signed response binds the request and SVG digests and includes bounded observations of actual network use, and profile-bound inputs are resolved into its render URL. These observations are partial: font shaping, resource use, runtime profile API reads and a complete browser dependency graph are not attested. Ordinary worker requests stay compatible with existing deployments, and worker PDF export uses the actual SVG viewport instead of Chromium's default paper size.

A successful measurement is not a human approval, permission to deliver or a claim of complete reproducibility. Local review files cannot grant Lolly Work permissions, and destination approval chains, current grants and delivery integrity checks keep their authority. The exact bytes and the contract can be checked again offline. No new storage migration is needed.