Shuffll Engage API quickstart

Obtain authorized access to your workspace before calling the API.

https://engage.shuffll.com/api

Use this base URL with the /v1/... operation paths in the reference. The documentation site's /engage route is not an API endpoint. For the separate MCP URL, see servers and endpoints.

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, contact Shuffll rather than repeatedly retrying generation. A parent administrator's authority remains limited by the parent's policy and active status.

Set 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.

curl --fail-with-body \
  'https://engage.shuffll.com/api/v1/capabilities' \
  -H "Authorization: Bearer $ENGAGE_API_KEY"

The response describes the operations available to that principal. Availability can change when policy, permissions or key status changes. Consult the reference for the exact response schema.

Run this example in server-side JavaScript with ENGAGE_API_KEY set in the environment. Keep the key out of browser bundles and shared logs.

const apiKey = process.env.ENGAGE_API_KEY;
if (!apiKey) throw new Error('Set ENGAGE_API_KEY before making a request');

const response = await fetch('https://engage.shuffll.com/api/v1/capabilities', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
if (!response.ok) throw new Error(`Engage capabilities request failed: ${response.status}`);

const capabilities = await response.json();
console.log(capabilities);

This read checks access for the current credential. It does not generate videos or prove that a rendering workflow has completed. Use the OpenAPI JSON when integrating with a client or inspecting the response schema.

With templates:read access, list a small page of published templates:

curl --fail-with-body \
  'https://engage.shuffll.com/api/v1/templates?limit=5' \
  -H "Authorization: Bearer $ENGAGE_API_KEY"

Inspect the selected template and its versions before creating a campaign. Use the returned 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 templates:read and the workspace permits that operation.

To author a new story and coordinate scene media, start with the agentic journey guide. To connect approved products and audience rules, follow catalog-driven creative. For an existing published template, use the campaign sequence linked below.

For a new integration, read the campaign concepts and integration planning guide to map audience data, rendering inputs, and delivery requirements before making changes.

Follow the campaign workflow for template discovery and generation, or connect an MCP client. A successful capabilities read does not grant every operation; request only the scopes the integration needs.

Read authentication and jobs and retries before adding writes. Generation is an explicit action that may consume the workspace's configured allowance.