Export Label Artifact
Generate (or return cached) label artifact(s) for one serving.
On the first request for a given (recipe version, serving, format, resolution) combination the label HTML is assembled, rendered by the label-renderer Lambda, and the result is permanently cached in S3. Subsequent requests return the cached artifact without re-rendering.
Concurrent first-download requests are safe — only one PUT lands; all others receive a pre-signed URL for the same artifact.
Organizations in their trial period or on the Free plan always receive a
DRAFT-watermarked artifact, whatever the draft_watermark parameter
says, and so do organizations whose billing status cannot currently be
confirmed.
Organizations on a paid plan receive the final, watermark-free artifact
unless they pass draft_watermark=true.
Each file carries a proof footer unless proof_footer is false. Each artifact reports download_url
(saves the file under file_name), rendered_at and the footer state.
Organizations on a non-subscription plan (past_due/expired/
cancelled) may still re-fetch an already-cached artifact, but a
request that would require a fresh render (bm-be#2296) is denied with a
402.
When label readiness is on, a mandatory nutrient that no ingredient's source
reports prints as a stated zero, and the maker must confirm each one before
the label is issued. A label with an unconfirmed stated zero is refused with
428 label_review_required, listing each nutrient and the fills_hash
to confirm it with (save the confirmation through the label settings, then
retry). A finding that blocks the label, such as a missing calorie value, is
refused with 422 label_not_ready.
A label can also carry findings nobody has addressed, such as an Added Sugars
determination that is not confirmed; each names its nutrients. Exporting it
needs them acknowledged on every channel: without acknowledged_findings_hash
the export is refused with 428 label_acknowledgement_required, listing the
findings and the findings_hash to send back. An organization whose policy
is to block refuses the export with 422 label_blocked_by_findings instead,
and acknowledging does not help.
Available only on API versions declaring the recipe_versioning capability.
serving_id*Serving IdServing identifier
recipe_id*Recipe Idformats?array<string>|Output file formats, a list of pdf, png and jpeg, for example ["pdf", "png"]. Defaults to ["pdf"].
resolution?LabelResolutionOutput resolution tier.
"print""print""digital"label_format?"standard_vertical"Panel layout.
"standard_vertical""standard_vertical"version_id?|Leave out for the current recipe. To read an earlier version, pass a version_id from the recipe's version list.
draft_watermark?|Whether to overlay a DRAFT watermark on every output format. Leave it out to let the account's plan decide. true asks for a DRAFT proof. false has no effect when the account's plan requires the watermark.
acknowledged_findings_hash?|Acknowledges the findings a label export listed, by the findings_hash that listing gave. Send it only after the person who owns the label has seen the findings. It holds only while the findings are unchanged; if they change, the export asks again. Not needed when the label has no findings.
Successful Response
application/json- response
Response body for GET /recipes/{id}/servings/{sid}/label-export.
Contains one :class:ArtifactResult per requested output format.
All artifacts share the same label_format, resolution, and
version_id — they differ only in file format (PDF / PNG / JPEG).
version_id reflects the recipe snapshot rendered. When the
request did not supply a ?version_id= query parameter, this is
the HEAD version at the time the request was processed.
label_format*"standard_vertical"Panel layout used for all artifacts in this response.
"standard_vertical"resolution*LabelResolutionOutput resolution tier shared by all artifacts.
"print""digital"version_id*Version IdRecipe version snapshot rendered. Clients should store this alongside label_format and resolution to reconstruct the cache key without a round-trip.
version_number?|Sequential number of the recipe version rendered (for example 15 for "v15"). Null for versions sealed before numbering existed.
provenance?|Versions of the rules and software behind these files.
artifacts*array<>One entry per requested output format.
meta*Standard API response envelope with version, request_id, and timestamp.
curl -X GET 'https://api.bettermenu.live/studio/recipes/string/servings/string/label-export'{ "label_format": "standard_vertical", "resolution": "print", "version_id": "string", "version_number": 0, "provenance": { "rules_bundle_version": "string", "label_package_version": "string", "added_sugars_state": "string", "added_sugars": { "state": "no_report", "is_finding": true, "message": "string", "report_hash": "string", "total_rows": 0, "answered_rows": 0, "open_rows": 0, "suggested_not_accepted_rows": 0, "confirmed_at": "2019-08-24T14:15:22Z" }, "findings": [ { "code": "added_sugars_not_confirmed", "nutrients": [ { "bmid": "string", "display_name": "string" } ], "message": "string" } ], "findings_acknowledged_hash": "string", "issued_label_id": "string", "zero_filled": [ { "bmid": "string", "display_name": "string", "display_text": "string", "acknowledged_at": "2019-08-24T14:15:22Z", "note": "string" } ] }, "artifacts": [ { "format": "string", "artifact_url": "string", "expires_at": "2019-08-24T14:15:22Z", "download_url": "string", "file_name": "string", "proof_footer": true, "rendered_at": "2019-08-24T14:15:22Z" } ], "meta": { "version": "string", "request_id": "string", "timestamp": "string" }}