Publications, review and usage rights

Goal

Publish the exact media and metadata that were approved while keeping originals private.

Prerequisites

A governed bucket, clean source version, complete required metadata and ready renditions.
Explicit edit, review and publish permissions for the people performing those steps.

Workflow

Create a publication draft from the current asset and ready rendition references.

Set its channel, rights owner, attribution and optional UTC rights window.

Submit the snapshot, review it, and publish only after approval.

Resolve fresh delivery credentials on demand; withdraw when use must stop.

What a publication contains

An asset identifies the library item. A version identifies specific source bytes. A rendition identifies a derived output. A publication pins those identities together with metadata, schema/policy revisions, caption references, channel and usage rights. A public URL is a temporary delivery result, not the publication’s identity. A new source upload or metadata edit does not silently update a reviewed snapshot. Native video validation/review and publication editorial review are separate gates: a playable video is not automatically approved for every channel.

Create the draft in the dashboard

Open the asset’s publication workflow and select New publication draft. Choose a ready main rendition; originals are never selected automatically. Add approved caption tracks and, for models, a supplied poster and optional validated USDZ companion. A rendered spin must include its complete 24-frame set. Enter Channel, Rights owner and Attribution. Rights start and Rights expiry are entered in UTC. Save draft captures the current source and metadata. If no rendition is available, finish processing and refresh instead of pasting an arbitrary delivery URL.

Review and publish

draft → Submit for review → in_review. Editing a draft captures current inputs; it does not preserve approval of superseded content.
in_review → Approve snapshot → approved, or Request changes → draft. A change request needs a nonblank review note.
approved → Publish to the selected channel → published. Approval alone does not make the publication deliverable.
published → Withdraw publication → Confirm withdrawal → withdrawn. Subsequent delivery checks reject this publication, including unexpired credentials.
The reviewer sees source, metadata/schema/policy revisions, rights and the actual preview. If the bucket requires another reviewer, the uploader/editor cannot self-approve.

Permission and revision requirements

The API key needs assets:write for draft edits and submit, assets:admin for approve/request-changes, and assets:publish for publish/withdraw. The acting account must also have the corresponding space/collection actions. Read/resolve requires assets:read and current read authority. Send If-Match with the publication revision for changes and transitions; the SDK does this for you. Use the returned revision after each successful transition. If another editor or a source/policy change invalidates the snapshot, reload and reconcile the draft rather than blindly replaying approval.

Create a snapshot from returned references

Use publicationRenditions to obtain valid, immutable references. Do not construct rendition IDs, output checksums or render_set_id values yourself. The example assumes the user selected the primary and companion references from this response.

const asset = await sdk.assets.get(assetId)
const { renditions } = await sdk.assets.dam.publicationRenditions(assetId)
const primary = renditions.find(ref => ref.rendition_id === selectedRenditionId)
if (!primary) throw new Error('Selected rendition is no longer available')
const draft = await sdk.assets.dam.createPublication({
  asset_id: asset.id, asset_revision: asset.revision, channel: 'web',
  renditions: [primary, ...selectedCompanionReferences],
  rights: { owner: 'Example Studio', attribution: 'Photography: Example Studio' },
})
const submitted = await sdk.assets.dam.transitionPublication(draft.id, draft.revision, 'submit')
// Separate authorized review action after inspecting the exact snapshot:
const approved = await reviewerSdk.assets.dam.transitionPublication(submitted.id, submitted.revision, 'approve')
// Separate authorized publishing action:
const live = await publisherSdk.assets.dam.transitionPublication(approved.id, approved.revision, 'publish')

Rights fields and delivery window

rights.owner is required and at most 240 bytes; attribution is at most 2,000 bytes. Optional starts_at and expires_at are timestamps; use ISO-8601 UTC values in API requests. When both exist, expiry must be later than start. Review notes are limited to 2,000 bytes. A future rights start or expired rights window prevents ordinary delivery even if status is published. Delivery credentials last at most five minutes and can expire earlier with the rights window. Rights metadata is your authorization assertion; entering an owner name does not obtain a license.

Resolve a publication through your backend

Your application stores the allowed publication ID with its product/post. Before resolving, authorize the viewer and verify the publication belongs to that saved product/post. Do not expose a server account credential through an unrestricted resolve-any-ID endpoint. GET /api/v1/assets/publications/{id}/resolve returns publication_id, expires_at, attribution, ar_allowed and renditions containing immutable reference objects and temporary URLs. HLS can include mp4_url/poster_url. Preserve the response’s intended media grouping and captions.

// After checking the viewer and the product's saved publication reference:
const delivery = await sdk.assets.dam.resolvePublication(savedPublicationId)
return Response.json(delivery, {
  headers: { 'Cache-Control': 'private, no-store' },
})

Preview, replace and withdraw

The authorized preview endpoint is /publications/{id}/preview; the SDK uses resolvePublication(id, true). It exists for editorial inspection and must not be used as public delivery to bypass publication or rights checks. When replacing media, create or refresh a draft from current source/metadata, review it and update the consuming product/gallery to the approved publication revision. A gallery’s saved references do not automatically follow asset edits. Withdrawal, quarantine, asset deletion, policy changes or access revocation can invalidate subsequent delivery. Buffered/downloaded bytes cannot be recalled. Consumers must display an unavailable state or a separately authorized fallback instead of retrying the original public upload URL.

Troubleshoot a blocked publication

No ready renditions: inspect source scanning and processing. Proof renders are preview-only and cannot be published.
Validation failure: complete required metadata, use the allowed channel, inspect the rights window and include the required model poster/valid companions.
Revision conflict or stale approval: read current asset/publication/policy, compare changes and resubmit the corrected snapshot for review.
Review denied: check assets:admin, review authority and the different-reviewer rule.
Published but unavailable: check current rights, source/quarantine state, permissions, selected publication revision and any gallery withdrawal. Do not bypass the resolver.

Go, Python and PHP: create the editorial snapshot and submit it

Read publication-renditions for the primary asset and each selected companion. Pass the selected immutable reference objects, unchanged, as references below. Exactly one reference must have role=media and belong to the primary asset’s current version. Use owner and attribution values that describe your actual license; the example strings are not a license grant. The metadata editor supplies the current asset revision in the selected space. A concurrent source or metadata update causes a revision failure instead of creating a snapshot from stale data. These functions stop at in_review. An authorized reviewer inspects the snapshot and calls the transition method with approve; the publisher then uses the returned revision with publish. Never approve automatically as part of upload. Persist the draft ID as soon as creation succeeds. If submit fails, fix the existing draft or retry its transition with a freshly read revision; do not create a duplicate publication. List publications with asset_id to recover saved drafts.

func submitPublication(ctx context.Context, dam *stackshift.AssetDAMClient, assetID string, references []map[string]any) (*stackshift.AssetPublication, error) {
	editor, err := dam.MetadataEditor(ctx, assetID)
	if err != nil {
		return nil, err
	}
	draft, err := dam.CreatePublication(ctx, map[string]any{
		"asset_id": assetID, "asset_revision": editor["revision"], "channel": "web",
		"renditions": references,
		"rights":     map[string]any{"owner": "Example Studio", "attribution": "Photography: Example Studio"},
	})
	if err != nil {
		return nil, err
	}
	submitted, err := dam.TransitionPublication(ctx, draft.ID, draft.Revision, "submit", "Ready for editorial review")
	if err != nil {
		return draft, err
	}
	return submitted, nil
}

def submit_publication(dam, asset_id, references):
    editor = dam.metadata_editor(asset_id)
    draft = dam.create_publication({
        "asset_id": asset_id, "asset_revision": editor["revision"], "channel": "web",
        "renditions": references,
        "rights": {"owner": "Example Studio", "attribution": "Photography: Example Studio"},
    })
    # Persist draft["id"] in your editorial record before submitting.
    return dam.transition_publication(draft["id"], draft["revision"], "submit", "Ready for editorial review")

function submitPublication(\StackShift\AssetDAMClient $dam, string $assetId, array $references): array {
    $editor = $dam->metadataEditor($assetId);
    $draft = $dam->createPublication([
        'asset_id' => $assetId, 'asset_revision' => $editor['revision'], 'channel' => 'web',
        'renditions' => $references,
        'rights' => ['owner' => 'Example Studio', 'attribution' => 'Photography: Example Studio'],
    ]);
    // Persist $draft['id'] in your editorial record before submitting.
    return $dam->transitionPublication($draft['id'], $draft['revision'], 'submit', 'Ready for editorial review');
}

HTTP operations for this workflow

Management requests use Authorization: Bearer with your server-side Assets credential and X-Asset-Space-ID for the selected space. API-key scopes and space/collection permissions both apply. Successful JSON responses use {success: true, data: …}; the SDK methods return the unwrapped data. Paths shown outside /api/v1 use their dedicated short-lived credential.

Operation	Authorization	Concurrency	Success
`GET /api/v1/assets/publications`	assets:read	—	200
`POST /api/v1/assets/publications`	assets:write	—	201
`PUT /api/v1/assets/publications/{publicationID}`	assets:write	Quoted If-Match	200
`POST /api/v1/assets/publications/{publicationID}/{action}`	assets:write submit; assets:admin review; assets:publish publish/withdraw	Quoted If-Match	200
`GET /api/v1/assets/publications/{publicationID}/resolve`	assets:read	—	200
`GET /api/v1/assets/{assetID}/publication-renditions`	assets:read	—	200
`GET /api/v1/assets/publications/{publicationID}/preview`	assets:read	—	200

For If-Match, quote the revision number, for example If-Match: “7”. On 412 assets.revision_conflict, reload the relevant resource and reconcile the edit before retrying. Use the revision of the resource being changed: asset, collaborator, schema, publication or gallery. A bucket-policy save instead places its current revision in the JSON body.

Snapshot fields and resolver response

POST creates a draft; PUT edits an existing draft using the publication revision in If-Match and the current asset_revision in the body. The service captures version_id, metadata, metadata_revision, schema and policy revisions. Do not send a made-up output URL in place of a rendition reference. The returned publication includes id, asset_id, version_id, channel, status, revision, metadata, metadata_revision, schema_id/schema_revision when bound, policy_revision, renditions, rights, created_by, reviewed_by/reviewed_at when reviewed, review_note, published_at/withdrawn_at when applicable and creation/update timestamps. Resolve and preview return publication_id, channel, expires_at, attribution, ar_allowed and renditions. Each delivery rendition contains reference and url. Native video also contains mp4_url and poster_url; a rendered turntable contains mp4_url. Standard resolution omits USDZ. The explicit AR request returns authorized AR resources when policy and companions allow it. Refresh through your backend when expires_at approaches; do not persist the short-lived URLs in CMS content. List publications with asset_id, status and cursor. Consume publications and next_cursor; continue with the returned cursor until it is empty. Keep the same filters on every page.

Field	Meaning and constraints
`asset_id / asset_revision`	Primary asset UUID and its current revision. A source replacement requires a new current snapshot.
`channel`	One channel allowed by bucket governance, for example web.
`renditions`	1–30 immutable references returned by publication-renditions; unique rendition IDs and exactly one primary role=media. Companion roles: poster, fallback, caption, usdz and spin_frame.
`rights.owner`	Required, trimmed, nonblank owner/license-holder name, at most 240 bytes.
`rights.attribution`	Attribution text, at most 2,000 bytes; resolver passes it to the embedding application.
`rights.starts_at / rights.expires_at`	Optional RFC 3339 timestamps; expiry must follow start. Normal delivery is available only within this window.
`note`	Transition body field, at most 2,000 bytes. request-changes requires a nonblank explanation; submit/approve/publish/withdraw may use an empty note.

Expected result

Consumers receive short-lived delivery for the exact reviewed publication, with rights and revocation checked on subsequent requests.

Common failures

Treating approval as publication.
Reusing an old revision after editing the source or policy.
Saving delivery URLs as permanent CMS content.
Publishing a proof or incomplete spin.

Typed metadata and bucket governance

Create and publish metadata schemas, bind exact revisions to buckets, validate asset fields, and migrate existing delivery into governance.

Embed the headless asset picker

Add JavaScript or React media selection using expiring capabilities, save stable references, and resolve approved media from your backend.

Create and embed media galleries

Arrange published images, video, spins and models with locale, alternate text, approved fallbacks and stable published revisions.

Upload, validate and publish 3D models

Prepare supported GLB and supplied USDZ files, inspect validation reports, add posters, review the model and launch authorized device AR.

Assets SDKs: JavaScript, Go, Python and PHP

Configure space-scoped clients and use native video, governed DAM, model rendering, galleries and CMS capabilities in all four SDKs.

​Goal

​Prerequisites

​Workflow

​What a publication contains

​Create the draft in the dashboard

​Review and publish

​Permission and revision requirements

​Create a snapshot from returned references

​Rights fields and delivery window

​Resolve a publication through your backend

​Preview, replace and withdraw

​Troubleshoot a blocked publication

​Go, Python and PHP: create the editorial snapshot and submit it

​HTTP operations for this workflow

​Snapshot fields and resolver response

​Expected result

​Common failures

​Related guides

Typed metadata and bucket governance

Embed the headless asset picker

Create and embed media galleries

Upload, validate and publish 3D models

Assets SDKs: JavaScript, Go, Python and PHP

Goal

Prerequisites

Workflow

What a publication contains

Create the draft in the dashboard

Review and publish

Permission and revision requirements

Create a snapshot from returned references

Rights fields and delivery window

Resolve a publication through your backend

Preview, replace and withdraw

Troubleshoot a blocked publication

Go, Python and PHP: create the editorial snapshot and submit it

HTTP operations for this workflow

Snapshot fields and resolver response

Expected result

Common failures

Related guides