# Shuffll API FAQ

## What is Shuffll Engage?

**Shuffll Engage — Personalized video at scale.** Create personalized video campaigns based on customer interests, behaviors, and audience segments. Tailor content across customer journeys, including e-commerce and product videos, and integrate it into your existing workflows through a robust API and MCP. For the operations and rendering formats documented here, see [Engage API scope and availability](/engage/release-status).

## Which Shuffll API should I start with?

Start with **Engage** for campaign workflows and AI assistant connections. Choose **Video Production** for creating, enhancing, and exporting individual video projects from content. The [API comparison](/choose-api) lists the resources, endpoints, authentication, and first request for each.

## What is the difference between a campaign and a video project?

An Engage campaign connects a selected template, campaign settings, recipient records, generation jobs, and results. A Video Production project represents a video that moves through creation, enhancement, and export. Use each API's own identifiers and lifecycle.

## Does Shuffll Engage support API and MCP integrations?

Engage exposes a REST API at `https://engage.shuffll.com/api` and a Streamable HTTP MCP endpoint at `https://engage.shuffll.com/mcp`. Use REST from application code and MCP from a compatible AI assistant. Both connections require authorized workspace access. See the [REST quickstart](/engage/quickstart) and [MCP setup](/engage/mcp).

## How do I choose a video workflow for my integration?

Start with the outcome: use [Engage REST](/engage/quickstart) for application-driven campaigns, [Engage MCP](/engage/mcp) for assistant-led orchestration, or [Video Production](/guides/quickstart) to create and export an individual video project. Read your workspace capabilities, inspect the chosen template or journey inputs, and test a representative output. The [V1 campaign workflow](/engage/workflows) documents the legacy `flat-video-v1` format, whose recipient fields do not change the rendered clips. See [workflow scope](/engage/release-status) when selecting a personalization workflow.

## What is the difference between audience segmentation and video personalization?

Segmentation determines which people belong to an audience or campaign. Video personalization changes the media they receive using configured inputs, such as approved content or template variables. Importing recipient records or segment membership alone does not establish that the rendered video changes. Confirm the rendering workflow and data mappings separately.

See [campaign and personalization concepts](/engage/concepts) and the [integration planning guide](/engage/integration-planning) for a worked planning framework.

## Is Engage only for e-commerce and product videos?

No. Engage's positioning covers video campaigns across customer journeys, based on customer interests, behaviors, and audience segments. E-commerce and product videos are examples within that broader focus. Confirm the operations and rendering inputs needed for your particular use case.

## Can I use the same API key for Engage and Video Production?

No. Engage REST requests use `Authorization: Bearer <ENGAGE_API_KEY>`. Video Production requests use `x-api-key: <VIDEO_PRODUCTION_API_KEY>`. Obtain credentials for the API and workspace you intend to use. Keep secrets in server-side storage or private client credential settings.

## Do I append REST routes to the MCP URL?

No. Connect an MCP client to `https://engage.shuffll.com/mcp` exactly. REST requests use the separate base URL `https://engage.shuffll.com/api` followed by the documented `/v1/...` operation path. For example, the capabilities request is `https://engage.shuffll.com/api/v1/capabilities`.

## How do I check which Engage operations I can use?

Read the capabilities response for your authorized workspace and, for MCP, discover the client's live tool catalog. Access depends on workspace policy, scopes, credentials, and resource ownership. A tool listing establishes visibility; test the intended workflow and inspect its results before treating rendering or delivery as complete.

## Does adding recipients generate or send their videos?

No. In the documented legacy campaign workflow, recipient management, generation, and result retrieval are separate actions. Adding a recipient does not render a video. A successful render does not establish that a message was sent. Confirm any delivery workflow and channel configuration separately.

## Does OAuth support mean an app is approved in a marketplace?

No. OAuth authorization, successful client connections, marketplace submissions, and public marketplace approvals are separate states. For OAuth-capable MCP clients, use the discovery metadata advertised by the Engage endpoint. See [MCP setup](/engage/mcp).

## Are all documented operations available in production?

Use the environment and access requirements documented for each operation. The Video Production reference includes explicit development-server overrides, and the Engage reference describes a bounded V1 contract. Neither a documentation page nor a successful capabilities read certifies every workflow in production. [Contact Shuffll](/contact) with the exact operation, workspace, and deployment you intend to use.

## How do I know when a video is ready?

For Engage, poll the returned job location and inspect the terminal job state and video results. For Video Production, follow its creation, enhancement, and export status endpoints or the webhook flow documented for that operation. A returned job or project ID means the request was accepted; it does not mean the video has finished.

## Where can I download the Shuffll OpenAPI specifications?

Download the [Engage OpenAPI JSON](/openapi/engage.json) or the [Video Production OpenAPI YAML](/openapi/video-production.yaml). These machine-readable specifications match the corresponding documentation source. They describe separate APIs; use the selected specification's server, authentication, and environment requirements. For human-readable references, see [Engage](/engage/openapi) and [Video Production](/apis).

## What should I include in a support request?

Include the API name, operation, environment, error code, and request ID when available. Describe the expected result and what happened. Exclude API keys, authorization headers, temporary access URLs, and personal recipient data. [Contact the Shuffll team](/contact).

## What can an AI agent coordinate with Engage?

A compatible connected assistant can develop concepts and storyboards, coordinate available scene-media tools, attach editable artwork, inspect previews and prepare revisions. Journeys retain saved artifacts and review state; generation, export and campaign launch remain separate actions. See the [agentic workflow](/engage/agentic-workflows) for an example brief and tool sequence, and discover the actual tools available to your connection.

## Can we make relevant videos without sharing full customer profiles?

Yes, for a workflow that only needs selected content, your system can keep audience selection and customer matching while supplying approved product/message inputs and a required opaque reference. Names or contact details are not universally required. If a name must appear in speech or artwork, or a delivery service needs a destination, supply those specific values. Opaque references can still be personal data. See [security and privacy](/engage/security-and-privacy).

## Can product catalogs drive audience-specific videos?

Catalog information and approved imagery can inform the creative, with explicit audience and offer rules supplying selected content values. Define the mapping and review a sample; importing product and customer records does not by itself create a recommendation engine or automatic product join. See the [catalog campaign example](/engage/product-catalogs).

## What are smart overlays?

They are editable scene-attached artwork with supported graphics, text bindings and animation controls. Use them for product details, branding and visual calls to action, then inspect the current composition. A visual CTA in an MP4 is not automatically clickable; interactivity and tracking belong to a supported playback or delivery surface. See [overlay workflows](/engage/overlays).

## How can we improve the next campaign?

Start with render health, then use the delivery and viewing measurements your configured surfaces actually provide. Compare consistent audience definitions and time windows, choose a specific creative hypothesis and review the next variation. Render counts do not establish views or conversions, and this improvement loop does not imply automatic experimentation or revenue attribution. See [analytics and campaign improvement](/engage/analytics).

## Which parts of a video can we localize?

Plan language across the script, supported voiceover, visual direction, subtitles and overlay text. Discover the available language/voice/model combinations and review pronunciation, timing, typography and reading direction in the actual output. Choose the supported combination for each creative stage. See [multilingual creation](/engage/multilingual).