Storylinez LogoStorylinez
Documentation

Brands API

/brands
21 endpoints

Endpoints for managing brand settings within an organization, including creating, retrieving, updating, deleting, duplicating brands as well as managing logos and fonts.

Endpoint Base

https://api.storylinezads.com/brands

All endpoints in this section are relative to this base path. Use this prefix for all requests to the Brands API.

Brand Management

Endpoints to create, retrieve, update, delete, duplicate, and set default brand profiles. Use these in combination to fully manage brand settings across your organization.

POST

Create Brand Settings

/brands/create

Create Brand Settings - POST /brands/create

Creates a new brand profile with detailed styling and configuration parameters. Colors (provided as lists) are internally converted to tuples and fonts are validated.

Parameters:

  • org_id: Unique organization identifier. This determines which organization the brand belongs to.
  • name: The display name for the brand. This is mandatory.
  • is_default: Flag to mark this brand as the default for the organization. If true, any previously default brand will be unset automatically.
  • is_public: When true, the brand is visible to users outside the organization for duplication or discovery.
  • logo_key: S3 key of the logo file. Must begin with 'userdata/'. It is recommended to use the logo upload workflow instead.
  • upload_id: The secure upload identifier returned by GET /logo-upload-url. When provided, the logo_key from that upload is used automatically and validated before the brand is created.
  • outro_bg_color: RGB array representing the outro background color.
  • outro_logo_size: Dimensions of the logo in the outro given as [width, height].
  • outro_logo_mode: Mode for displaying logo in outro: 0 for text only, 1 for logo only, 2 for both logo and text.
  • company_font: Font used for the primary company name text. Must be one from the available fonts list.
  • company_font_size: Font size for the primary company name text.
  • subtext_font: Font used for secondary text (taglines, etc.). Must be available in the fonts list.
  • subtext_font_size: Font size for subtext.
  • text_spacing: Vertical spacing between text elements in the outro.
  • logo_text_spacing: Spacing between the logo and text in the outro.
  • outro_transition: Transition effect for the outro appearance (e.g., fade, crossfade, cut).
  • outro_transition_duration: Duration of the outro transition effect in seconds.
  • transition_duration: Default duration for other transitions applied in video generation.
  • text_transition: Transition effect when text elements appear (fade, cut, or null for no animation).
  • text_transition_delay: Delay before text transition begins, in seconds.
  • text_transition_duration: Duration of the text transition effect in seconds.
  • main_text_color: RGB color array for main text elements.
  • sub_text_color: RGB color array for secondary text elements.
  • cta_text_color: RGB color array for call-to-action text elements.
  • cta_subtext_color: RGB color array for call-to-action subtext elements.
  • cta_company_font_size: Font size for company name within call-to-action elements.
  • cta_subtext_font_size: Font size for subtext within call-to-action elements.
  • cta_bg_color: RGB background color for call-to-action elements.
  • subtitle_font_size: Font size for subtitle text.
  • subtitle_font: Font used for subtitles. Must match one available from GET /fonts.
  • subtitle_color: RGB color array for subtitle text.
  • subtitle_bg_color: RGB background color for subtitle display.
  • subtitle_bg_opacity: Opacity level for subtitle background (from 0.0 to 1.0).
  • subtitle_bg_padding: Padding (in pixels) around subtitle background.
  • subtitle_bg_rounded: Whether the subtitle background has rounded corners.
  • subtitle_bg_corner_radius: Radius (in pixels) for rounded subtitle background corners.
  • subtitle_position: Position of subtitles on the video (0: top edge, 1: below top edge, 2: vertically centered, 3: above bottom edge, 4: bottom edge).
  • subtitle_squeeze_xp: Width threshold in pixels for applying subtitle squeezing to prevent overflow.
  • subtitle_max_group_size: Maximum number of consecutive subtitle lines to group together; set to 0 or null for grouping based on timing.
  • template_heading_font_size: Font size for the heading in template slides.
  • template_heading_color: RGB color for the template heading text.
  • template_description_font_size: Font size for the description in template slides.
  • template_description_color: RGB color for the template description text.
  • template_bg_color: RGB background color for template slides.
  • template_bg_opacity: Opacity of the template background (0.0 to 1.0).
  • template_heading_font: Font for the template heading.
  • template_description_font: Font for the template description.
  • template_text_spacing: Spacing between text elements in the template slide.
  • template_xp: X-coordinate for template text positioning in pixels.
  • template_yp: Y-coordinate for template text positioning in pixels.
  • template_text_align: Alignment of text in the template slide (left, center, right).
  • template_text_transition: Transition effect for text in template slides (fade, cut, or null for no animation).
  • template_text_transition_delay: Delay before the template text transition starts, in seconds.
  • template_text_transition_duration: Duration of the template text transition, in seconds.
  • template_bg_rounded: Whether the template background has rounded corners.
  • template_bg_corner_radius: Corner radius for the template background, in pixels.
  • image_slideshow: When true, images in templates are displayed with motion effects (panning/zooming) as a slideshow.
GET

Get All Brands

/brands/get_all

Get All Brands - GET /brands/get_all

Retrieves a paginated list of brand profiles for a given organization. Optionally returns temporary download URLs for logos.

Parameters:

  • org_id: Unique identifier for the organization whose brands are being retrieved.
  • page: Pagination page number, starting at 1.
  • limit: Maximum number of brands to return per page (max 50).
  • include_urls: If true, returns presigned URLs for logos in each brand record.
GET

Get Brand Settings

/brands/get

Get Brand Settings - GET /brands/get

Fetches the full details of a specific brand by brand_id, or retrieves the default brand for an organization if org_id is provided.

Parameters:

  • brand_id: Unique identifier of the brand. Provide this to fetch a specific brand.
  • org_id: Organization ID to retrieve its default brand if brand_id is omitted.
PUT

Update Brand Settings

/brands/update

Update Brand Settings - PUT /brands/update

Updates specific fields of an existing brand. Only fields included in the request body are modified.

Parameters:

  • brand_id: Unique identifier of the brand to be updated.
  • name: New name for the brand. Must not be empty.
  • is_default: If true, sets this brand as the default, unsetting any current default in the organization.
  • is_public: Updated public visibility of the brand.
  • logo_key: New S3 key for the logo. Must start with 'userdata/' if provided. Use the /add_logo endpoint for a safer workflow.
  • logo_upload_id: The upload ID specifically for a logo file (preferred over upload_id for clarity and future-proofing).
  • upload_id: Legacy parameter: General upload ID for backward compatibility. Will be used if logo_upload_id is not provided.
  • outro_bg_color: New RGB color array for the outro background.
  • outro_logo_size: New dimensions [width, height] for the logo in the outro.
  • outro_logo_mode: New mode for displaying logo in outro: 0 (text only), 1 (logo only), 2 (both).
  • company_font: New font for the primary company name text. Must be a valid font name.
  • company_font_size: New font size for the primary company name text.
  • subtext_font: New font for secondary text. Must be a valid font name.
  • subtext_font_size: New font size for subtext.
  • text_spacing: New vertical spacing between text elements in the outro.
  • logo_text_spacing: New spacing between the logo and text in the outro.
  • outro_transition: New transition effect for the outro appearance (e.g., fade, crossfade, cut).
  • outro_transition_duration: New duration for the outro transition effect in seconds.
  • transition_duration: New default duration for other transitions applied in video generation.
  • text_transition: New transition effect when text elements appear (fade, cut, or null).
  • text_transition_delay: New delay before text transition begins, in seconds.
  • text_transition_duration: New duration of the text transition effect in seconds.
  • main_text_color: New RGB color array for main text elements.
  • sub_text_color: New RGB color array for secondary text elements.
  • cta_text_color: New RGB color array for call-to-action text elements.
  • cta_subtext_color: New RGB color array for call-to-action subtext elements.
  • cta_company_font_size: New font size for company name within call-to-action elements.
  • cta_subtext_font_size: New font size for subtext within call-to-action elements.
  • cta_bg_color: New RGB background color for call-to-action elements.
  • subtitle_font_size: New font size for subtitle text.
  • subtitle_font: New font used for subtitles. Must be a valid font name.
  • subtitle_color: New RGB color array for subtitle text.
  • subtitle_bg_color: New RGB background color for subtitle display.
  • subtitle_bg_opacity: New opacity level for subtitle background (0.0 to 1.0).
  • subtitle_bg_padding: New padding (in pixels) around subtitle background.
  • subtitle_bg_rounded: Update whether the subtitle background has rounded corners.
  • subtitle_bg_corner_radius: New radius (in pixels) for rounded subtitle background corners.
  • subtitle_position: Position of subtitles on the video (0: top edge, 1: below top edge, 2: vertically centered, 3: above bottom edge, 4: bottom edge).
  • subtitle_squeeze_xp: New width threshold in pixels for applying subtitle squeezing.
  • subtitle_max_group_size: New maximum number of consecutive subtitle lines to group; set to 0 or null for timing-based grouping.
  • template_heading_font_size: New font size for the heading in template slides.
  • template_heading_color: New RGB color for the template heading text.
  • template_description_font_size: New font size for the description in template slides.
  • template_description_color: New RGB color for the template description text.
  • template_bg_color: New RGB background color for template slides.
  • template_bg_opacity: New opacity of the template background (0.0 to 1.0).
  • template_heading_font: New font for the template heading. Must be a valid font name.
  • template_description_font: New font for the template description. Must be a valid font name.
  • template_text_spacing: New spacing between text elements in the template slide.
  • template_xp: New X-coordinate for template text positioning in pixels.
  • template_yp: New Y-coordinate for template text positioning in pixels.
  • template_text_align: New alignment of text in the template slide (left, center, right).
  • template_text_transition: New transition effect for text in template slides (fade, cut, or null).
  • template_text_transition_delay: New delay before the template text transition starts, in seconds.
  • template_text_transition_duration: New duration of the template text transition, in seconds.
  • template_bg_rounded: Update whether the template background has rounded corners.
  • template_bg_corner_radius: New corner radius for the template background, in pixels.
  • image_slideshow: Enable or disable the image slideshow effect on templates.
DELETE

Delete Brand Settings

/brands/delete

Delete Brand Settings - DELETE /brands/delete

Deletes a brand profile and its associated logo from S3. If the deleted brand was default, a replacement default will be selected.

Parameters:

  • brand_id: Unique identifier of the brand to be deleted.
PUT

Set Default Brand

/brands/set_default

Set Default Brand - PUT /brands/set_default

Sets a specified brand as the organization's default. This causes any other default brand to be unset automatically.

Parameters:

  • brand_id: Unique identifier of the brand to mark as default.
POST

Duplicate Brand

/brands/duplicate

Duplicate Brand - POST /brands/duplicate

Creates a copy of an existing brand, with a new brand_id. Styling, fonts, and most configuration values are cloned. The service also attempts to duplicate the logo asset; if S3 copy fails, the new brand is created without a logo.

Parameters:

  • brand_id: ID of the source brand to duplicate. This can be from your organization or a public brand.
  • org_id: ID of the target organization where the new duplicated brand will be created.
  • name: Optional custom name for the new brand. Otherwise, '(Copy)' will be appended to the source brand's name.
GET

Get Default Brand

/brands/get_default

Get Default Brand - GET /brands/get_default

Retrieves the default brand for a specific organization with a simpler interface than the general-purpose `/get` endpoint.

Parameters:

  • org_id: The ID of the organization to get the default brand for.

Logo Management

Endpoints for managing brand logos, including generating upload URLs and linking uploaded logos to brands.

GET

Get Logo Upload URL

/brands/logo-upload-url

Get Logo Upload URL - GET /brands/logo-upload-url

Generates a pre-signed URL for secure uploading of a logo directly to S3. Use the provided upload_id in the subsequent update logo endpoint.

Parameters:

  • org_id: ID of the organization. Ensures the logo is associated with the proper organization.
  • filename: Desired filename for the logo. Must include an allowed extension such as jpg, jpeg, or png.
POST

Download Logo From URL

/brands/logo-from-url

Download Logo From URL - POST /brands/logo-from-url

Downloads an external logo asset over HTTPS, validates it, and uploads it into the secure Storylinez storage in a single step. Returns the same upload_id flow used by the upload URL endpoint.

Parameters:

  • org_id: Organization that will own the downloaded logo.
  • logo_url: Public HTTP(S) URL pointing to the image asset. Non-HTTPS URLs or redirects to non-image content are rejected.

Add Logo to Brand - PUT /brands/add_logo

Associates a previously uploaded logo (using upload_id or direct logo_key) with an existing brand. Also removes any pre-existing logo if necessary.

Parameters:

  • brand_id: ID of the brand to which the logo is being added or updated.
  • upload_id: Secure upload identifier returned from GET /logo-upload-url or POST /logo-from-url. Preferred because it validates ownership and freshness.
  • logo_key: Direct S3 key fallback. Must begin with 'userdata/' and is only accepted for legacy integrations. Either upload_id or logo_key must be supplied.

Font Management

Endpoint to retrieve the list of available fonts that can be used in brand settings.

GET

Get Available Fonts

/brands/fonts

Get Available Fonts - GET /brands/fonts

Retrieves a cached list of available font names from the renderer service. Use this list to ensure all font names used in brand creation or update are valid.

Brand Discovery

Endpoints for searching and discovering brand profiles. These endpoints facilitate cross-organization brand discovery and duplication.

GET

Search Brands

/brands/search

Search Brands - GET /brands/search

Searches for brand profiles based on name and filters. Supports pagination and optional inclusion of public brands and logo URLs.

Parameters:

  • q: Search term to match against brand names (case-insensitive search).
  • include_public: If true, includes public brands from other organizations in the results.
  • org_id: If provided, limits the search to brands within this organization. Overrides include_public.
  • page: Page number for pagination.
  • limit: Maximum number of results per page (max 50).
  • include_logos: If true, returns presigned URLs for brand logos.
GET

List Public Brands

/brands/public

List Public Brands - GET /brands/public

Returns public brands across Storylinez with optional smart sorting based on user interactions. Supports excluding your own organization, pagination, and on-demand logo URLs.

Parameters:

  • exclude_org_id: If supplied, public brands from this organization are omitted.
  • page: Pagination page number (minimum 1).
  • limit: Page size (max 50).
  • include_logos: When true, each record includes a temporary logo_url.
  • sort_by: Sort field: updated_at, net_score, likes, or dislikes.
  • sort_order: Sort direction: asc or desc.
  • smart_sort: Enables interaction-aware ordering. Likes are bubbled to the top, dislikes to the bottom, with remaining results ordered by sort_by.

User Interactions

Endpoints for managing user interactions with brands including likes, dislikes, and interaction removal. These interactions affect content ordering with smart rearrangement.

POST

Like Brand

/brands/like

Like Brand - POST /brands/like

Like a specific brand. This interaction affects content ordering in future API responses, with liked brands appearing first.

Parameters:

  • brand_id: ID of the brand to like.
POST

Dislike Brand

/brands/dislike

Dislike Brand - POST /brands/dislike

Dislike a specific brand. This interaction affects content ordering in future API responses, with disliked brands appearing last.

Parameters:

  • brand_id: ID of the brand to dislike.
POST

Remove Brand Interaction

/brands/remove_interaction

Remove Brand Interaction - POST /brands/remove_interaction

Remove any existing interaction (like or dislike) with a specific brand, resetting it to neutral status.

Parameters:

  • brand_id: ID of the brand to remove interaction from.

Brand Comments

Comprehensive commenting system for brands including creating, retrieving, updating, and deleting comments with support for replies and pagination.

POST

Add Brand Comment

/brands/comment

Add Brand Comment - POST /brands/comment

Add a new comment to a brand. Supports both top-level comments and replies to existing comments with automatic thread management.

Parameters:

  • brand_id: ID of the brand to comment on.
  • text: The comment body. Trimmed automatically and limited to 1000 characters.
  • parent_comment_id: ID of parent comment if this is a reply. Null for top-level comments.
GET

Get Brand Comments

/brands/comments

Get Brand Comments - GET /brands/comments

Retrieve comments for a specific brand with pagination support and hierarchical organization of replies.

Parameters:

  • brand_id: ID of the brand to get comments for.
  • parent_comment_id: Set to a comment_id to fetch replies for that comment. Pass the string 'null' to fetch only top-level comments.
  • page: Page number for pagination.
  • limit: Number of comments per page (max 50).
PUT

Update Brand Comment

/brands/comment

Update Brand Comment - PUT /brands/comment

Update the content of an existing comment. Only the comment author can edit their own comments.

Parameters:

  • comment_id: ID of the comment to update.
  • text: The new comment body. Trimmed and capped at 1000 characters.
DELETE

Delete Brand Comment

/brands/comment

Delete Brand Comment - DELETE /brands/comment

Delete an existing comment. Only the comment author can delete their own comments. Deleting a parent comment also removes all replies.

Parameters:

  • comment_id: ID of the comment to delete.