# Engage API Current V1 operations. Availability is also checked against live tenant policy and principal authority. Version: 1.0.0 ## Servers ``` https://engage.shuffll.com/api ``` ## Security ### bearerAuth Type: http Scheme: bearer ## Download OpenAPI description - [Engage API](https://api-docs.shuffll.com/_bundle/engage/openapi.yaml) ## Partners - [POST /v1/meta-organizations](https://api-docs.shuffll.com/engage/openapi/partners/partners_provision.md): Provision an inactive partner. Owner email and brand mode are required; invitation and activation are separate. - [GET /v1/meta-organizations](https://api-docs.shuffll.com/engage/openapi/partners/partners_list.md): List safe partner metadata with cursor pagination. - [GET /v1/meta-organizations/{id}](https://api-docs.shuffll.com/engage/openapi/partners/partners_get.md): Read safe partner provisioning and activation status. - [PATCH /v1/meta-organizations/{id}](https://api-docs.shuffll.com/engage/openapi/partners/partners_update.md): Update partner metadata. Custom domain remains metadata only. - [POST /v1/meta-organizations/{id}/activation](https://api-docs.shuffll.com/engage/openapi/partners/partners_activate.md): Explicitly activate or deactivate a partner using existing readiness prerequisites. - [GET /v1/account](https://api-docs.shuffll.com/engage/openapi/partners/account_get.md): Read the current partner account for a partner-level principal. ## Organizations - [POST /v1/organizations](https://api-docs.shuffll.com/engage/openapi/organizations/organizations_create.md): Create a child organization and its brand profile. - [GET /v1/organizations](https://api-docs.shuffll.com/engage/openapi/organizations/organizations_list.md): List only organizations within the current tenant context. - [GET /v1/organizations/{id}](https://api-docs.shuffll.com/engage/openapi/organizations/organizations_get.md): Read safe organization metadata and revision. - [PATCH /v1/organizations/{id}](https://api-docs.shuffll.com/engage/openapi/organizations/organizations_update.md): Update organization name and slug with a current revision. - [POST /v1/organizations/{id}/archive](https://api-docs.shuffll.com/engage/openapi/organizations/organizations_archive.md): Archive a non-default organization. Its history is retained. ## Branding - [GET /v1/organizations/{id}/branding](https://api-docs.shuffll.com/engage/openapi/branding/branding_get.md): Read the organization brand profile. - [PATCH /v1/organizations/{id}/branding](https://api-docs.shuffll.com/engage/openapi/branding/branding_update.md): Update brand colors, font and verified owned image assets. ## Members - [GET /v1/organizations/{id}/members](https://api-docs.shuffll.com/engage/openapi/members/members_list.md): List organization memberships. - [POST /v1/organizations/{id}/members](https://api-docs.shuffll.com/engage/openapi/members/members_add.md): Add an existing account without sending an invitation. - [PATCH /v1/organizations/{id}/members/{member_id}](https://api-docs.shuffll.com/engage/openapi/members/members_update.md): Change a membership role while protecting the last administrator. - [DELETE /v1/organizations/{id}/members/{member_id}](https://api-docs.shuffll.com/engage/openapi/members/members_remove.md): Remove a membership while protecting the last administrator. ## Invitations - [POST /v1/organizations/{id}/invitations](https://api-docs.shuffll.com/engage/openapi/invitations/invitations_create.md): Explicitly invite an account. Membership begins only after acceptance. - [GET /v1/organizations/{id}/invitations](https://api-docs.shuffll.com/engage/openapi/invitations/invitations_list.md): List scoped invitation status. - [GET /v1/organizations/{id}/invitations/{invitation_id}](https://api-docs.shuffll.com/engage/openapi/invitations/invitations_get.md): Read an invitation without sending mail. - [DELETE /v1/organizations/{id}/invitations/{invitation_id}](https://api-docs.shuffll.com/engage/openapi/invitations/invitations_revoke.md): Revoke a pending invitation. - [POST /v1/organizations/{id}/invitations/{invitation_id}/resend](https://api-docs.shuffll.com/engage/openapi/invitations/invitations_resend.md): Explicitly resend an invitation with a known prior delivery outcome. ## Uploads - [POST /v1/uploads](https://api-docs.shuffll.com/engage/openapi/uploads/uploads_create.md): Create a private PNG/JPEG/WebP upload (1–10485760 bytes). Finalize within 15 minutes; signed PUT capability lasts 2 hours and cannot overwrite. No remote URL ingestion. - [GET /v1/uploads/{id}](https://api-docs.shuffll.com/engage/openapi/uploads/uploads_get.md): Read upload status and finalization deadline. Revocation/expiry blocks finalization but does not revoke an already issued 2-hour storage capability. - [DELETE /v1/uploads/{id}](https://api-docs.shuffll.com/engage/openapi/uploads/uploads_revoke.md): Revoke an unfinished upload session. Existing storage PUT capability still lasts up to 2 hours; finalization is denied. - [POST /v1/uploads/{id}/finalize](https://api-docs.shuffll.com/engage/openapi/uploads/uploads_finalize.md): Verify completed owned object size, raster bytes and MIME, then atomically create a private ready asset. ## Assets - [GET /v1/assets/{id}](https://api-docs.shuffll.com/engage/openapi/assets/assets_get.md): Read safe owned asset metadata. Private storage references and upload capabilities are never returned. - [GET /v1/assets](https://api-docs.shuffll.com/engage/openapi/assets/assets_list.md): List owned asset metadata within the current tenant. - [POST /v1/assets/{id}/promote-branding](https://api-docs.shuffll.com/engage/openapi/assets/assets_promote_branding.md): Explicitly publish a verified owned raster image at a durable public branding URL. The original storage object remains private. ## Catalogs - [GET /v1/catalogs/languages](https://api-docs.shuffll.com/engage/openapi/catalogs/catalogs_languages.md): Read configured languages available to this tenant. Catalog entries do not grant generation authority. Stable ID cursor pagination defaults to 50 entries, maximum 100. - [GET /v1/catalogs/voices](https://api-docs.shuffll.com/engage/openapi/catalogs/catalogs_voices.md): Read configured voices available to this tenant. Catalog entries do not grant generation authority. Stable ID cursor pagination defaults to 50 entries, maximum 100. - [GET /v1/catalogs/fonts](https://api-docs.shuffll.com/engage/openapi/catalogs/catalogs_fonts.md): Read configured fonts available to this tenant. Catalog entries do not grant generation authority. Stable ID cursor pagination defaults to 50 entries, maximum 100. - [GET /v1/catalogs/music](https://api-docs.shuffll.com/engage/openapi/catalogs/catalogs_music.md): Read configured music available to this tenant. Catalog entries do not grant generation authority. Stable ID cursor pagination defaults to 50 entries, maximum 100. - [GET /v1/catalogs/models](https://api-docs.shuffll.com/engage/openapi/catalogs/catalogs_models.md): Read configured models available to this tenant. Catalog entries do not grant generation authority. Stable ID cursor pagination defaults to 50 entries, maximum 100. - [GET /v1/catalogs/transitions](https://api-docs.shuffll.com/engage/openapi/catalogs/catalogs_transitions.md): Native transition styles with verified playback/export parity. Currently empty; generated transitions are never offered. Stable ID cursor pagination defaults to 50 entries, maximum 100. ## Templates - [GET /v1/templates](https://api-docs.shuffll.com/engage/openapi/templates/templates_list.md): Discover authorized published template metadata. Safe projection only; Only explicitly frozen flat-video-v1 versions are render-ready. They contain fixed video clips without personalization; legacy an - [GET /v1/templates/{id}](https://api-docs.shuffll.com/engage/openapi/templates/templates_get.md): Discover authorized published template metadata. Safe projection only; Only explicitly frozen flat-video-v1 versions are render-ready. They contain fixed video clips without personalization; legacy an - [GET /v1/templates/{id}/versions](https://api-docs.shuffll.com/engage/openapi/templates/template_versions_list.md): Discover authorized published template metadata. Safe projection only; Only explicitly frozen flat-video-v1 versions are render-ready. They contain fixed video clips without personalization; legacy an - [GET /v1/templates/{id}/versions/{version_id}](https://api-docs.shuffll.com/engage/openapi/templates/template_versions_get.md): Discover authorized published template metadata. Safe projection only; Only explicitly frozen flat-video-v1 versions are render-ready. They contain fixed video clips without personalization; legacy an ## Campaigns - [POST /v1/campaigns](https://api-docs.shuffll.com/engage/openapi/campaigns/campaigns_create.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g - [GET /v1/campaigns](https://api-docs.shuffll.com/engage/openapi/campaigns/campaigns_list.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g - [PATCH /v1/campaigns/{id}](https://api-docs.shuffll.com/engage/openapi/campaigns/campaigns_update.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g - [GET /v1/campaigns/{id}](https://api-docs.shuffll.com/engage/openapi/campaigns/campaigns_get.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g - [POST /v1/campaigns/{id}/clone](https://api-docs.shuffll.com/engage/openapi/campaigns/campaigns_clone.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g - [POST /v1/campaigns/{id}/archive](https://api-docs.shuffll.com/engage/openapi/campaigns/campaigns_archive.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g - [GET /v1/campaigns/{id}/validate](https://api-docs.shuffll.com/engage/openapi/campaigns/campaigns_validate.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g ## Production settings - [PATCH /v1/campaigns/{id}/production](https://api-docs.shuffll.com/engage/openapi/production-settings/campaign_production_update.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g - [GET /v1/campaigns/{id}/production](https://api-docs.shuffll.com/engage/openapi/production-settings/campaign_production_get.md): Canonical child-owned campaign using an explicitly frozen fixed-video version. No personalization or automatic generation, export or sending. Workspace materialization remains pending until explicit g ## Recipients - [POST /v1/campaigns/{id}/recipients](https://api-docs.shuffll.com/engage/openapi/recipients/recipients_upsert.md): Manage canonical campaign recipients without generation, personalization or sending. external_id maps to the existing campaign employee identity. Mutations require the campaign revision. Claimed, rend - [GET /v1/campaigns/{id}/recipients](https://api-docs.shuffll.com/engage/openapi/recipients/recipients_list.md): Manage canonical campaign recipients without generation, personalization or sending. external_id maps to the existing campaign employee identity. Mutations require the campaign revision. Claimed, rend - [DELETE /v1/campaigns/{id}/recipients/{recipient_id}](https://api-docs.shuffll.com/engage/openapi/recipients/recipients_delete.md): Manage canonical campaign recipients without generation, personalization or sending. external_id maps to the existing campaign employee identity. Mutations require the campaign revision. Claimed, rend - [GET /v1/campaigns/{id}/recipients/{recipient_id}](https://api-docs.shuffll.com/engage/openapi/recipients/recipients_get.md): Manage canonical campaign recipients without generation, personalization or sending. external_id maps to the existing campaign employee identity. Mutations require the campaign revision. Claimed, rend ## Generation - [POST /v1/campaigns/{id}/generate](https://api-docs.shuffll.com/engage/openapi/generation/campaigns_generate.md): Render fixed video for 1–100 explicitly selected recipients from the immutable campaign revision. Names are contact metadata, not personalization. Durable idempotency; poll jobs and results. Does not ## Results - [GET /v1/campaigns/{id}/results](https://api-docs.shuffll.com/engage/openapi/results/campaign_results_list.md): Read recipient render attempts, including failures and pending recovery. Media URLs are returned only to authorized readers. - [GET /v1/campaigns/{id}/results/{result_id}](https://api-docs.shuffll.com/engage/openapi/results/campaign_results_get.md): Read one exact recipient render attempt and its playable MP4 and timed thumbnails. - [GET /v1/campaigns/{id}/analytics](https://api-docs.shuffll.com/engage/openapi/results/campaign_analytics_get.md): Campaign-scoped counts of render attempts and recipients. Fixed-video generation does not deliver messages; no engagement or delivery event is inferred from an export. ## API keys - [GET /v1/keys](https://api-docs.shuffll.com/engage/openapi/api-keys/keys_list.md): List managed credential metadata; verified humans may select an exact managed target. - [POST /v1/keys](https://api-docs.shuffll.com/engage/openapi/api-keys/keys_issue.md): Issue a scoped credential. MCP returns an authenticated human claim link; REST returns its secret once. - [GET /v1/keys/{id}](https://api-docs.shuffll.com/engage/openapi/api-keys/keys_get.md): Read managed credential metadata and its current revision. - [DELETE /v1/keys/{id}](https://api-docs.shuffll.com/engage/openapi/api-keys/keys_revoke.md): Revoke a credential and its delegated lineage. - [POST /v1/keys/{id}/rotate](https://api-docs.shuffll.com/engage/openapi/api-keys/keys_rotate.md): Rotate a credential with bounded overlap. MCP returns an authenticated human claim link; REST returns its secret once. ## Access policies - [GET /v1/organizations/{id}/access](https://api-docs.shuffll.com/engage/openapi/access-policies/organization_access_get.md): Read child access settings as a partner administrator. - [PUT /v1/organizations/{id}/access](https://api-docs.shuffll.com/engage/openapi/access-policies/organization_access_set.md): Delegate API access within current partner entitlements. - [PUT /v1/control/access](https://api-docs.shuffll.com/engage/openapi/access-policies/api_access_set.md): Human control-plane policy management, including initial activation. - [GET /v1/control/access](https://api-docs.shuffll.com/engage/openapi/access-policies/api_access_get.md): Read the stored access policy and safe ancestor ceiling for authorized human administrators. ## Capabilities - [GET /v1/capabilities](https://api-docs.shuffll.com/engage/openapi/capabilities/capabilities_get.md): Current safe operations and effective entitlements. ## Jobs - [GET /v1/jobs/{id}](https://api-docs.shuffll.com/engage/openapi/jobs/jobs_get.md): Read an initiated operation after checking its underlying workflow authority.