- Pack
- A paid, versioned set of published sticker assets available to the workspace.
- Collection
- Free application configuration that controls which activated packs one app can discover.
- Sticker
- A stable metadata record selected through search and rendered through an approved variant.
Collections do not purchase packs
A collection is free application configuration over Hosted Packs already activated for the workspace. Disabling a pack removes it from new search and typeahead while the retained binding can preserve exact historical message rendering.
- 01
Activate a Hosted Pack
The paid activation belongs to the workspace.
- 02
Create a collection
Use one collection for each application or sticker policy boundary.
- 03
Enable the pack
The collection can now expose that pack through runtime reads.
Typeahead is the beginning of search—not sticker retrieval
Typeahead returns suggestion text such as beach. Search the selected suggestion to receive sticker records. Persist and pass stickerId to metadata and resolve calls; semanticId describes meaning and is not accepted as the sticker path identifier.
Test the complete flow with the CLI
# The API key stays in trusted server-side environment configuration.
export MEDIARUNTIME_API_KEY="sk_..."
collection_id='stc_11111111111111111111111111111111'
# Typeahead returns suggestion text, not stickers or delivery URLs.
mediaruntime stickers typeahead "be" --collection "$collection_id" --locale en --limit 10 --json
# Search the selected suggestion to obtain complete sticker records.
mediaruntime stickers search "beach" --collection "$collection_id" --limit 10 --json
# Use stickerId—not semanticId—for metadata and asset routes.
sticker_id='sage-the-owl-summer-season-vacation-v1-beach-day'
mediaruntime stickers get "$sticker_id" --collection "$collection_id" --json
# Resolve only when the UI needs an approved representation.
mediaruntime stickers resolve "$sticker_id" --variant small_160 --collection "$collection_id" --jsonBuild the same collection-bound flow in application code.
// npm install @mediaruntime/node
import { MediaRuntime } from "@mediaruntime/node";
// Never expose the workspace API key in browser or mobile code.
const media = new MediaRuntime({ apiKey: process.env.MEDIARUNTIME_API_KEY });
const stickers = media.stickers.collection("stc_11111111111111111111111111111111");
// Show these suggestion texts while the user types.
const typeahead = await stickers.typeahead("be", { locale: "en", limit: 10 });
const selectedTerm = typeahead.suggestions[0]?.text;
if (!selectedTerm) throw new Error("No sticker suggestion matched");
// Search turns the selected term into stable sticker records.
const matches = await stickers.search(selectedTerm, { limit: 10 });
const selectedSticker = matches.items[0];
if (!selectedSticker) throw new Error("No sticker matched the selected suggestion");
// Persist stickerId in the message; signed delivery URLs expire.
const asset = await stickers.resolve(selectedSticker.stickerId, "small_160");
console.log(selectedSticker.stickerId, asset.url);Server key or scoped client token
Trusted servers can use MEDIARUNTIME_API_KEY directly. Browser and mobile applications should receive an optional short-lived token minted by the trusted server and restricted to one collection plus explicit runtime scopes.
Persist references, not URLs
Store stickerId, packId, and packVersion with the message. Resolve an approved variant when rendering because its generation-pinned delivery URL is intentionally short-lived.
Sticker collections and runtime endpoints.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/sticker-collections | List application collections owned by the workspace. |
| PUT | /v1/sticker-collections/{collection_id}/packs/{pack_id} | Enable an already-activated Hosted Pack in one collection. |
| GET | /v1/stickers/packs | List enabled packs for an explicit collection_id. |
| GET | /v1/stickers/typeahead | Return locale-aware suggestion text; it does not return sticker IDs. |
| GET | /v1/stickers/search | Search enabled sticker metadata and return stable stickerId values. |
| GET | /v1/stickers/{sticker_id} | Retrieve one sticker by stickerId, not semanticId. |
| GET | /v1/stickers/{sticker_id}/assets/{variant} | Return a short-lived generation-pinned delivery URL. |
| POST | /v1/sticker-runtime/client-tokens | Mint an optional short-lived collection-scoped client token. |
| GET | /v1/sticker-runtime/usage/current | Inspect current pooled operations and authorized delivery. |