# Core Entities

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.

## Entity overview


```mermaid
flowchart TD
  Org["Organization"]
  WS["Workspace"]
  Brand["Branding\n(embedded)"]
  Tmpl["Template"]
  Asset["Asset"]
  Proj["Project"]

  Org -->|"1 or more"| WS
  Org -->|"has embedded"| Brand
  WS -->|"has embedded"| Brand
  WS -->|"contains"| Tmpl
  WS -->|"contains"| Asset
  WS -->|"contains"| Proj
  Tmpl -. "blueprint for" .-> Proj
```

## Organization

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 `organizationId` to manage workspaces and their branding.


## Workspace

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 workspaces via `GET /auth/organization/{organizationId}`.
- Use `GET /auth/workspace/{workspaceId}/projects` to list a workspace's projects.
- Workspace branding is managed via `GET` / `PUT /auth/branding/entity?workspaceId=...`.


## Template

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/templates` or `GET /auth/organization/{organizationId}/workspace/{workspaceId}/templates`.
- Inspect a template's scene structure with `GET /auth/templates/{templateId}` before using it.


## Asset

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 via their `uploadPath` CDN URL.

- Upload assets with `POST /auth/workspace/{workspaceId}/assets`.
- The `uploadPath` returned on each asset is the URL to use in `customTemplate.scenes[].videosToAdd[].url`.


## Project

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](/guides) for the full lifecycle.


## Branding

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

## Inside a Project

A project is composed of several parts that together define the complete video production:


```mermaid
flowchart TD
  Proj["Project"]

  Creative["Creative\n(AI-generated script\nand storyline)"]
  Scenes["Scenes"]
  SceneDetail["Per-scene content\n(dynamic values, videos,\nsubtitles, static text)"]
  Voice["AI Voice settings\n(provider, voice ID,\ntone instructions)"]
  Avatar["AI Avatar settings\n(avatar ID)"]
  Fonts["Font settings"]
  Brand["Branding snapshot\n(applied at generation time)"]
  Status["Status\nSTRUCTURE → GENERATING_IMAGES → DONE"]
  Exports["Export jobs\n(render results + output URLs)"]
  APIConfig["API config\n(webhook URL, additionalParams)"]

  Proj --> Creative
  Proj --> Scenes
  Scenes --> SceneDetail
  Proj --> Voice
  Proj --> Avatar
  Proj --> Fonts
  Proj --> Brand
  Proj --> Status
  Proj --> Exports
  Proj --> APIConfig
```

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


## Inside a Template

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:


```mermaid
flowchart TD
  Tmpl["Template"]

  SceneBlueprints["Scene blueprints\n(structure and scene types)"]
  Design["Design reference\n(visual style, colours,\nanimations)"]
  Flexibility["Flexibility\nrigid / minor / flexible"]
  Fonts["Font settings\n+ toUseTemplateFont flag"]
  VideoPipeline["Video source pipeline\n(fallback order for scene media)"]
  ImagePipeline["Image source pipeline\n(fallback order for scene images)"]
  DefaultVoice["Default voice settings"]
  Description["AI description\n(system prompt injected\ninto script generation)"]

  Tmpl --> SceneBlueprints
  Tmpl --> Design
  Tmpl --> Flexibility
  Tmpl --> Fonts
  Tmpl --> VideoPipeline
  Tmpl --> ImagePipeline
  Tmpl --> DefaultVoice
  Tmpl --> Description
```

| 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](/guides/workflow-templates) for a full guide on all overridable options.