This page describes the main entities in Shuffll and how they relate to each other. Understanding this model will help you navigate the API correctly — knowing which ID to use where, and how resources are scoped.
An Organization is the top-level container in Shuffll. It groups one or more workspaces under a single account and holds a shared branding configuration.
- Retrieve your organizations and their workspace IDs with
GET /auth/organization/list. - You need an
organizationIdto manage workspaces and their branding.
A Workspace is the primary working environment. All content — projects, templates, and assets — lives inside a workspace, not directly on the organization. Each workspace also carries its own branding, which takes precedence over the organization's branding when videos are generated.
- List all accessible workspaces via
GET /auth/organization/{organizationId}/workspace/list; organization detail embeds only the first page. - Use
GET /auth/organization/{organizationId}/workspace/{workspaceId}/projects/listto list a workspace's projects. - Read workspace branding from its detail endpoint. Update via
PUT /auth/branding/entitywithworkspace: { id }in the body.
A Template is a reusable video blueprint. It defines the scene structure, visual design, typography, media source pipeline, and default AI settings. Templates are workspace-scoped.
When you create a project from a template, the template configures the project's structure at creation time. It is not stored as a persistent link on the project afterward — the template is consumed once and the project stands on its own.
- Browse templates with
GET /auth/templatesorGET /auth/organization/{organizationId}/workspace/{workspaceId}/templates. - Inspect a template's scene structure with
GET /auth/templates/{templateId}before using it.
An Asset is a media file uploaded to a workspace — image, video, audio, or PDF. Assets are workspace-scoped and can be referenced directly in project creation requests using a resolved public media URL.
- Upload assets with
POST /auth/organization/{organizationId}/workspace/{workspaceId}/assets. - Asset
uploadPathmay be relative; resolve it against the content CDN before passing it as a media URL.
A Project is a single video production. It is created inside a workspace, goes through an AI generation phase, automatic enhancement (post-production), and finally export. A project is the central unit of work in the Shuffll API.
- Create a project with
POST /auth/project/create. - Track status with
GET /auth/project/{projectId}/create/status. - See Workflow Overview for the full lifecycle.
Branding is not a standalone entity — it is an embedded configuration inside both Organization and Workspace. It stores logo URLs, colour palette, company metadata, pronunciations, and the about text used in AI script generation.
Workspace branding takes precedence over organization branding when videos are generated. Manage branding with GET / PUT /auth/branding/entity.
A project is composed of several parts that together define the complete video production:
| Component | Description |
|---|---|
| Creative | The AI-generated script and narrative structure — the content backbone of the video |
| Scenes | Ordered list of scenes. Each scene has its own dynamic content, media, subtitle settings, and optional static text |
| AI Voice settings | Which AI voice to use, the provider (OpenAI or ElevenLabs), and any tone/style instructions |
| AI Avatar settings | Which AI avatar presenter to use, if any |
| Font settings | Typography applied across all scenes |
| Branding snapshot | A copy of the workspace branding captured at creation time |
| Status | The current stage: STRUCTURE → GENERATING_IMAGES → DONE (then enhancement begins) |
| Export jobs | The list of export runs and their output URLs (uploadPath MP4, dashPath DASH manifest) |
| API config | The webhook URL and any additionalParams to echo back in the webhook payload |
A template defines the blueprint used to initialise a project's structure. Its settings are applied (and in some cases overridable) at project creation time:
| Component | Description | Overridable at creation |
|---|---|---|
| Scene blueprints | Defines the number, type, and order of scenes | Partially — flexibilityOverride controls how strictly they are followed |
| Design reference | Points to the visual design that drives colours, animations, and layout | No |
| Flexibility | Default AI adherence level for this template | Yes — customTemplate.flexibilityOverride |
| Font settings | Typography for all scenes | Yes — customTemplate.fontsSettings or toUseTemplateFont |
| Video source pipeline | Default fallback order for scene video media | Yes — customTemplate.videoSourcesByOrder |
| Image source pipeline | Default fallback order for scene image slots | Yes — customTemplate.imageSourcesByOrder |
| Default voice settings | Voice used if none is specified in the project request | Yes — aiVoiceSettings at the project level |
| AI description | System prompt injected into script generation | Yes — customTemplate.description or toUseTemplateDescription |
See Using Templates for a full guide on all overridable options.