{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Shuffll Engage API quickstart","projectTitle":"Shuffll Developers","lang":"en","image":"/assets/icon-light.cf77c9f50f367b5652a57cbdbd6d9a5881b87349c1b0643a9f667e0d2e220f90.42541b0d.png","description":"Connect to Shuffll Engage, authenticate with your workspace key, and read capabilities before choosing campaign operations.","siteUrl":"https://api-docs.shuffll.com","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://shuffll.com/#organization","name":"Shuffll","url":"https://shuffll.com"},{"@type":"WebSite","@id":"https://api-docs.shuffll.com/#website","name":"Shuffll Developers","url":"https://api-docs.shuffll.com","inLanguage":"en","publisher":{"@id":"https://shuffll.com/#organization"}},{"@type":"WebAPI","@id":"https://api-docs.shuffll.com/engage#api","name":"Shuffll Engage API and MCP","url":"https://engage.shuffll.com","documentation":["https://api-docs.shuffll.com/engage","https://api-docs.shuffll.com/openapi/engage.json"],"serviceType":"Video campaign API and MCP","provider":{"@id":"https://shuffll.com/#organization"}},{"@type":"WebAPI","@id":"https://api-docs.shuffll.com/guides#api","name":"Shuffll Video Production API","url":"https://api.shuffll.com/api/v1","documentation":["https://api-docs.shuffll.com/apis","https://api-docs.shuffll.com/openapi/video-production.yaml"],"serviceType":"Video production REST API","provider":{"@id":"https://shuffll.com/#organization"}},{"@type":["WebPage","TechArticle"],"@id":"https://api-docs.shuffll.com/engage/quickstart#page","url":"https://api-docs.shuffll.com/engage/quickstart","name":"Shuffll Engage API quickstart","inLanguage":"en","isPartOf":{"@id":"https://api-docs.shuffll.com/#website"},"publisher":{"@id":"https://shuffll.com/#organization"},"about":{"@id":"https://api-docs.shuffll.com/engage#api"},"breadcrumb":{"@id":"https://api-docs.shuffll.com/engage/quickstart#breadcrumbs"}},{"@type":"BreadcrumbList","@id":"https://api-docs.shuffll.com/engage/quickstart#breadcrumbs","itemListElement":[{"@type":"ListItem","position":1,"name":"Shuffll Developers","item":"https://api-docs.shuffll.com/"},{"@type":"ListItem","position":2,"name":"Shuffll Engage API and MCP","item":"https://api-docs.shuffll.com/engage"},{"@type":"ListItem","position":3,"name":"Shuffll Engage API quickstart","item":"https://api-docs.shuffll.com/engage/quickstart"}]}]},"llmstxt":{"hide":false,"title":"Shuffll Engage API and MCP — Shuffll Developers","description":"Shuffll Engage connects agentic creation, catalog-driven campaigns, overlays and multilingual video through API and MCP. Video Production covers individual video projects.","details":{"content":"Start with [Shuffll Engage](https://api-docs.shuffll.com/engage). Read [which API to use](https://api-docs.shuffll.com/choose-api) and the [FAQ](https://api-docs.shuffll.com/faq) for scope, endpoints, and authentication. REST references are separate: [Engage](https://api-docs.shuffll.com/engage/openapi) and [Video Production](https://api-docs.shuffll.com/apis). Machine-readable OpenAPI downloads: [Engage JSON](https://api-docs.shuffll.com/openapi/engage.json) and [Video Production YAML](https://api-docs.shuffll.com/openapi/video-production.yaml). Legacy flat-video-v1 restrictions apply to that rendering workflow. Check live workspace access and operation-specific environment requirements.\n"},"sections":[{"title":"Shuffll Engage API and MCP","includeFiles":["engage/**/*.md"]},{"title":"Choose an API and get answers","includeFiles":["choose-api.md","faq.md"]},{"title":"Shuffll Video Production API","includeFiles":["guides/*.md","integrations/*.md"]},{"title":"Support","includeFiles":["contact.md"]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"shuffll-engage-api-quickstart","__idx":0},"children":["Shuffll Engage API quickstart"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Obtain authorized access to your workspace before calling the API."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rest-server","__idx":1},"children":["REST server"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"https://engage.shuffll.com/api\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this base URL with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/..."]}," operation paths in the reference. The documentation site's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/engage"]}," route is not an API endpoint. For the separate MCP URL, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage#servers-and-endpoints"},"children":["servers and endpoints"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-enable-workspace-access","__idx":2},"children":["1. Enable workspace access"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ask an entitled workspace administrator to confirm API access and issue a scoped key for the exact partner or child workspace. Where key management is available, store the returned secret immediately in a server-side secret manager; it is shown once. If your workspace cannot verify access or issue a key, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/contact"},"children":["contact Shuffll"]}," rather than repeatedly retrying generation. A parent administrator's authority remains limited by the parent's policy and active status."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-read-capabilities","__idx":3},"children":["2. Read capabilities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENGAGE_API_KEY"]}," securely in your local environment. The example uses shell environment-variable syntax; never paste a live key into documentation or commit it to source control."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl --fail-with-body \\\n  'https://engage.shuffll.com/api/v1/capabilities' \\\n  -H \"Authorization: Bearer $ENGAGE_API_KEY\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response describes the operations available to that principal. Availability can change when policy, permissions or key status changes. Consult the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/openapi"},"children":["reference"]}," for the exact response schema."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"read-capabilities-from-javascript","__idx":4},"children":["Read capabilities from JavaScript"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run this example in server-side JavaScript with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENGAGE_API_KEY"]}," set in the environment. Keep the key out of browser bundles and shared logs."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const apiKey = process.env.ENGAGE_API_KEY;\nif (!apiKey) throw new Error('Set ENGAGE_API_KEY before making a request');\n\nconst response = await fetch('https://engage.shuffll.com/api/v1/capabilities', {\n  headers: { Authorization: `Bearer ${apiKey}` },\n});\nif (!response.ok) throw new Error(`Engage capabilities request failed: ${response.status}`);\n\nconst capabilities = await response.json();\nconsole.log(capabilities);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This read checks access for the current credential. It does not generate videos or prove that a rendering workflow has completed. Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/engage.json"},"children":["OpenAPI JSON"]}," when integrating with a client or inspecting the response schema."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-discover-available-templates","__idx":5},"children":["3. Discover available templates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["templates:read"]}," access, list a small page of published templates:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl --fail-with-body \\\n  'https://engage.shuffll.com/api/v1/templates?limit=5' \\\n  -H \"Authorization: Bearer $ENGAGE_API_KEY\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the selected template and its versions before creating a campaign. Use the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextCursor"]}," to request the next page; keep the same workspace and filters. If the list is empty, confirm that a template has been published for your workspace. If access is denied, check that the key has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["templates:read"]}," and the workspace permits that operation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-choose-a-workflow","__idx":6},"children":["4. Choose a workflow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To author a new story and coordinate scene media, start with the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/agentic-workflows"},"children":["agentic journey guide"]},". To connect approved products and audience rules, follow ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/product-catalogs"},"children":["catalog-driven creative"]},". For an existing published template, use the campaign sequence linked below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a new integration, read the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/concepts"},"children":["campaign concepts"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/integration-planning"},"children":["integration planning guide"]}," to map audience data, rendering inputs, and delivery requirements before making changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/workflows"},"children":["campaign workflow"]}," for template discovery and generation, or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/mcp"},"children":["connect an MCP client"]},". A successful capabilities read does not grant every operation; request only the scopes the integration needs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/authentication"},"children":["authentication"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/engage/errors"},"children":["jobs and retries"]}," before adding writes. Generation is an explicit action that may consume the workspace's configured allowance."]}]},"headings":[{"value":"Shuffll Engage API quickstart","id":"shuffll-engage-api-quickstart","depth":1},{"value":"REST server","id":"rest-server","depth":2},{"value":"1. Enable workspace access","id":"1-enable-workspace-access","depth":2},{"value":"2. Read capabilities","id":"2-read-capabilities","depth":2},{"value":"Read capabilities from JavaScript","id":"read-capabilities-from-javascript","depth":3},{"value":"3. Discover available templates","id":"3-discover-available-templates","depth":2},{"value":"4. Choose a workflow","id":"4-choose-a-workflow","depth":2}],"frontmatter":{"seo":{"title":"Shuffll Engage API quickstart","description":"Connect to Shuffll Engage, authenticate with your workspace key, and read capabilities before choosing campaign operations.","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://shuffll.com/#organization","name":"Shuffll","url":"https://shuffll.com"},{"@type":"WebSite","@id":"https://api-docs.shuffll.com/#website","name":"Shuffll Developers","url":"https://api-docs.shuffll.com","inLanguage":"en","publisher":{"@id":"https://shuffll.com/#organization"}},{"@type":"WebAPI","@id":"https://api-docs.shuffll.com/engage#api","name":"Shuffll Engage API and MCP","url":"https://engage.shuffll.com","documentation":["https://api-docs.shuffll.com/engage","https://api-docs.shuffll.com/openapi/engage.json"],"serviceType":"Video campaign API and MCP","provider":{"@id":"https://shuffll.com/#organization"}},{"@type":"WebAPI","@id":"https://api-docs.shuffll.com/guides#api","name":"Shuffll Video Production API","url":"https://api.shuffll.com/api/v1","documentation":["https://api-docs.shuffll.com/apis","https://api-docs.shuffll.com/openapi/video-production.yaml"],"serviceType":"Video production REST API","provider":{"@id":"https://shuffll.com/#organization"}},{"@type":["WebPage","TechArticle"],"@id":"https://api-docs.shuffll.com/engage/quickstart#page","url":"https://api-docs.shuffll.com/engage/quickstart","name":"Shuffll Engage API quickstart","inLanguage":"en","isPartOf":{"@id":"https://api-docs.shuffll.com/#website"},"publisher":{"@id":"https://shuffll.com/#organization"},"about":{"@id":"https://api-docs.shuffll.com/engage#api"},"breadcrumb":{"@id":"https://api-docs.shuffll.com/engage/quickstart#breadcrumbs"}},{"@type":"BreadcrumbList","@id":"https://api-docs.shuffll.com/engage/quickstart#breadcrumbs","itemListElement":[{"@type":"ListItem","position":1,"name":"Shuffll Developers","item":"https://api-docs.shuffll.com/"},{"@type":"ListItem","position":2,"name":"Shuffll Engage API and MCP","item":"https://api-docs.shuffll.com/engage"},{"@type":"ListItem","position":3,"name":"Shuffll Engage API quickstart","item":"https://api-docs.shuffll.com/engage/quickstart"}]}]}}},"lastModified":"2026-11-12T17:50:54.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/engage/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}