Creavily Brands API

openapi: 3.2.0
info:
  title: Creavily Public Brands API
  version: 0.1.0
  description: Public API surface for tenant-scoped brand discovery, asset reads, channel account discovery, analytics, publishing automation, OAuth token exchange, and automation source/run management.
servers:
- url: https://creavily-api.ecomwith.com
  description: Creavily Public API
tags:
- name: Brands
paths:
  /v1/public/principal:
    get:
      tags:
      - Brands
      operationId: getPublicPrincipal
      summary: 'Describe the authenticated bearer (API key or OAuth access token): workspace…'
      security:
      - publicBearer: []
      x-required-scopes: []
      responses:
        '200':
          description: Authenticated principal summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  principal:
                    oneOf:
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: api_key
                        organizationId:
                          type: string
                        subjectId:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                      required:
                      - kind
                      - organizationId
                      - subjectId
                      - scopes
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: oauth_access_token
                        organizationId:
                          type: string
                        subjectId:
                          type: string
                        authorizationId:
                          type: string
                        oauthAppId:
                          type: string
                        userId:
                          type: string
                        clientId:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                      required:
                      - kind
                      - organizationId
                      - subjectId
                      - authorizationId
                      - oauthAppId
                      - userId
                      - clientId
                      - scopes
                      additionalProperties: false
                required:
                - principal
                additionalProperties: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/public/brands:
    get:
      tags:
      - Brands
      operationId: listPublicBrands
      summary: List brands and optional product IDs scoped to the bearer principal organization
      security:
      - publicBearer: []
      x-required-scopes:
      - brands:read
      parameters:
      - name: brandSlug
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: includeProducts
        in: query
        required: false
        schema:
          default: false
          type: boolean
      - name: limit
        in: query
        required: false
        schema:
          default: 100
          type: integer
          minimum: 1
          maximum: 500
      - name: offset
        in: query
        required: false
        schema:
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
      responses:
        '200':
          description: Brands.
          content:
            application/json:
              schema:
                type: object
                properties:
                  principal:
                    oneOf:
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: api_key
                        organizationId:
                          type: string
                        subjectId:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                      required:
                      - kind
                      - organizationId
                      - subjectId
                      - scopes
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: oauth_access_token
                        organizationId:
                          type: string
                        subjectId:
                          type: string
                        authorizationId:
                          type: string
                        oauthAppId:
                          type: string
                        userId:
                          type: string
                        clientId:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                      required:
                      - kind
                      - organizationId
                      - subjectId
                      - authorizationId
                      - oauthAppId
                      - userId
                      - clientId
                      - scopes
                      additionalProperties: false
                  brands:
                    type: array
                    items:
                      type: object
                      properties:
                        brandId:
                          type: string
                        organizationId:
                          type: string
                        name:
                          type: string
                        slug:
                          type: string
                        timezone:
                          type: string
                        productCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        createdAt:
                          type: string
                        updatedAt:
                          type: string
                        products:
                          type: array
                          items:
                            type: object
                            properties:
                              productId:
                                type: string
                              brandId:
                                type: string
                              name:
                                type: string
                              slug:
                                type: string
                              productUrl:
                                type:
                                - string
                                - 'null'
                              shopifyProductId:
                                type:
                                - string
                                - 'null'
                              createdAt:
                                type: string
                              updatedAt:
                                type: string
                            required:
                            - productId
                            - brandId
                            - name
                            - slug
                            - productUrl
                            - shopifyProductId
                            - createdAt
                            - updatedAt
                            additionalProperties: false
                      required:
                      - brandId
                      - organizationId
                      - name
                      - slug
                      - timezone
                      - productCount
                      - createdAt
                      - updatedAt
                      additionalProperties: false
                required:
                - principal
                - brands
                additionalProperties: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    BadRequest:
      description: Invalid request or missing runtime configuration.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid bearer credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Public API rate limit exceeded.
      headers:
        RateLimit-Limit:
          description: Configured request limit for the current window.
          schema:
            type: integer
        RateLimit-Remaining:
          description: Requests remaining in the current window.
          schema:
            type: integer
        RateLimit-Reset:
          description: Seconds until the current window resets.
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Feature gate disabled or token missing required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
        fields:
          type: array
          items:
            type: object
            properties:
              path:
                type: array
                items:
                  type: string
              source:
                type: string
                enum:
                - body
                - query
                - params
            required:
            - path
            additionalProperties: false
        requestId:
          type: string
          minLength: 1
      required:
      - error
      - message
      additionalProperties: {}
  securitySchemes:
    publicBearer:
      type: http
      scheme: bearer
      description: Use a Creavily API key or OAuth access token. Public endpoints are scoped to the authenticated principal organization.
    dashboardSession:
      type: http
      scheme: bearer
      description: Temporary legacy Dashboard session Bearer compatibility. New first-party browser clients use the HttpOnly dashboardSessionCookie and must never send a Dashboard bearer through a URL.
    dashboardSessionCookie:
      type: apiKey
      in: cookie
      name: creavily_dashboard_session
      description: Host-only HttpOnly Dashboard session cookie issued after the one-time browser-session exchange. Browser clients rely on credentialed requests and an approved Origin; JavaScript does not read this value.
    internalServiceToken:
      type: apiKey
      in: header
      name: x-creavily-internal-token
      description: Internal service credential for non-public operational routes. It is never exposed to browser or third-party clients.
    servicePrincipalToken:
      type: apiKey
      in: header
      name: x-creavily-service-principal-token
      description: Server-side service-principal credential accepted by policy-gated admin routes. It is never exposed to browser or third-party clients.
    browserSessionExchangeCookie:
      type: apiKey
      in: cookie
      name: creavily_browser_session_exchange
      description: Short-lived HttpOnly temporary cookie used only with POST /v1/auth/browser-session/exchange. It is cleared after a successful exchange or logout.
x-creavily-error-catalog:
  version: '2026-07-26'
  errors:
  - code: public_api_disabled
    status: 403
    category: feature_gate
    summary: Public API access is disabled by environment configuration.
  - code: request_origin_not_allowed
    status: 421
    category: authorization
    summary: The effective request origin is not permitted by the configured public API origin.
  - code: public_api_token_required
    status: 401
    category: authentication
    summary: A bearer token is required for the protected public route.
  - code: public_api_token_forbidden
    status: 401
    category: authentication
    summary: The supplied bearer credential is not authorized for the protected route.
  - code: public_api_rate_limited
    status: 429
    category: rate_limit
    summary: The public API or public OAuth token exchange rate limit was exceeded.
  - code: invalid_public_api_rate_limit_store
    status: 400
    category: configuration
    summary: The configured public API rate-limit store is unsupported.
  - code: database_url_required
    status: 400
    category: configuration
    summary: The route needs DATABASE_URL but it is not configured.
  - code: redis_url_required
    status: 400
    category: configuration
    summary: The route needs REDIS_URL but it is not configured.
  - code: invalid_request
    status: 400
    category: validation
    summary: A request did not satisfy the route validation contract.
  - code: internal_server_error
    status: 500
    category: server
    summary: The server could not process the request.
  - code: invalid_oauth_token_request
    status: 400
    category: validation
    summary: The OAuth token exchange request body is invalid.
  - code: invalid_public_oauth_authorize_request
    status: 400
    category: validation
    summary: The OAuth authorization request is invalid.
  - code: public_oauth_disabled
    status: 403
    category: feature_gate
    summary: Public OAuth authorize/token exchange is disabled.
  - code: invalid_client
    status: 401
    category: authentication
    summary: OAuth client credentials are invalid.
  - code: oauth_client_secret_unavailable
    status: 400
    category: configuration
    summary: The configured OAuth client secret reference cannot be resolved.
  - code: oauth_app_not_found
    status: 404
    category: not_found
    summary: The OAuth app was not found for the requested client or organization.
  - code: oauth_redirect_uri_not_registered
    status: 400
    category: validation
    summary: The OAuth redirect URI is not registered for the app.
  - code: oauth_authorization_write_failed
    status: 500
    category: server
    summary: The server could not persist an OAuth authorization grant.
  - code: oauth_authorization_code_write_failed
    status: 500
    category: server
    summary: The server could not persist an OAuth authorization code.
  - code: oauth_authorization_code_invalid
    status: 400
    category: validation
    summary: The OAuth authorization code is invalid, expired, consumed, or not valid for the client.
  - code: oauth_authorization_code_consumed
    status: 400
    category: conflict
    summary: The OAuth authorization code was already consumed.
  - code: oauth_refresh_token_invalid
    status: 400
    category: validation
    summary: The OAuth refresh token is invalid, expired, consumed, or not valid for the client.
  - code: oauth_refresh_token_consumed
    status: 400
    category: conflict
    summary: The OAuth refresh token was already consumed.
  - code: oauth_access_token_write_failed
    status: 500
    category: server
    summary: The server could not persist a newly issued OAuth access token.
  - code: oauth_refresh_token_write_failed
    status: 500
    category: server
    summary: The server could not persist a newly issued OAuth refresh token.
  - code: invalid_public_publish_plan_request
    status: 400
    category: validation
    summary: The public publish-plan preview request body is invalid.
  - code: invalid_public_publish_job_request
    status: 400
    category: validation
    summary: The public publish-job creation request body is invalid.
  - code: invalid_public_publish_job_query
    status: 400
    category: validation
    summary: The public publish-job query parameters are invalid.
  - code: public_publish_job_not_found
    status: 404
    category: not_found
    summary: The publish job was not found in the principal organization.
  - code: publish_plan_validation_failed
    status: 422
    category: validation
    summary: The publish plan has blocking platform validation issues.
  - code: publish_job_write_disabled
    status: 403
    category: feature_gate
    summary: Publish job persistence is disabled.
  - code: invalid_public_publish_enqueue_request
    status: 400
    category: validation
    summary: The public publish enqueue request is invalid.
  - code: invalid_public_analytics_snapshot_query
    status: 400
    category: validation
    summary: The public analytics snapshot query parameters are invalid.
  - code: invalid_public_brand_query
    status: 400
    category: validation
    summary: The public brand query parameters are invalid.
  - code: invalid_public_channel_account_query
    status: 400
    category: validation
    summary: The public channel account query parameters are invalid.
  - code: invalid_public_channel_connect_url_request
    status: 400
    category: validation
    summary: The public channel OAuth connect URL request is invalid.
  - code: channel_oauth_config_missing
    status: 400
    category: configuration
    summary: The server-side OAuth configuration for the platform is missing.
  - code: channel_oauth_redirect_uri_forbidden
    status: 400
    category: validation
    summary: The requested redirect URI does not match server configuration.
  - code: channel_oauth_config_invalid
    status: 400
    category: configuration
    summary: The server-side OAuth URL configuration is invalid.
  - code: invalid_public_media_upload_request
    status: 400
    category: validation
    summary: The public media upload request body or multipart fields are invalid.
  - code: invalid_multipart_media_upload
    status: 400
    category: validation
    summary: The media upload request is not multipart/form-data.
  - code: multipart_media_file_required
    status: 400
    category: validation
    summary: The multipart media upload did not include a non-empty file.
  - code: media_file_too_large
    status: 400
    category: validation
    summary: The uploaded media exceeds the configured maximum size.
  - code: media_upload_write_disabled
    status: 403
    category: feature_gate
    summary: Media upload persistence is disabled.
  - code: publish_enqueue_disabled
    status: 403
    category: feature_gate
    summary: Publish queue enqueueing is disabled.
  - code: invalid_public_publish_slot_query
    status: 400
    category: validation
    summary: The public publish slot query parameters are invalid.
  - code: invalid_public_publish_schedule_request
    status: 400
    category: validation
    summary: The public publish schedule request is invalid.
  - code: publish_schedule_write_disabled
    status: 403
    category: feature_gate
    summary: Publish schedule writes are disabled.
  - code: invalid_public_publish_cancel_request
    status: 400
    category: validation
    summary: The public publish cancel request is invalid.
  - code: publish_cancel_write_disabled
    status: 403
    category: feature_gate
    summary: Publish cancellation is disabled.
  - code: invalid_public_publish_url_reconciliation_request
    status: 400
    category: validation
    summary: The public publish URL reconciliation request is invalid.
  - code: invalid_public_comment_reply_draft_request
    status: 400
    category: validation
    summary: The public social comment reply draft request is invalid.
  - code: invalid_public_social_comment_reply_request
    status: 400
    category: validation
    summary: The public social comment reply request is invalid.
  - code: invalid_public_social_comment_reply_query
    status: 400
    category: validation
    summary: The public social comment reply query parameters are invalid.
  - code: provider_comment_reply_disabled
    status: 403
    category: feature_gate
    summary: Live provider comment replies are disabled.
  - code: social_comment_write_disabled
    status: 403
    category: feature_gate
    summary: Social comment persistence or external writes are disabled.
  - code: social_comment_not_found
    status: 404
    category: not_found
    summary: The social comment was not found in the principal organization.
  - code: provider_comment_reply_unsupported
    status: 422
    category: validation
    summary: The provider does not support replying to this social comment.
  - code: publish_url_reconciliation_disabled
    status: 403
    category: feature_gate
    summary: Live publish URL reconciliation writes are disabled.
  - code: invalid_public_webhook_endpoint_query
    status: 400
    category: validation
    summary: The public webhook endpoint query parameters are invalid.
  - code: invalid_public_webhook_endpoint_create_request
    status: 400
    category: validation
    summary: The public webhook endpoint creation request body is invalid.
  - code: invalid_public_webhook_endpoint_update_request
    status: 400
    category: validation
    summary: The public webhook endpoint update request body is invalid.
  - code: invalid_public_webhook_endpoint_delete_request
    status: 400
    category: validation
    summary: The public webhook endpoint delete request is invalid.
  - code: webhook_url_invalid
    status: 400
    category: validation
    summary: The webhook endpoint URL is not safe for outbound delivery.
  - code: webhook_write_disabled
    status: 403
    category: feature_gate
    summary: Webhook endpoint persistence is disabled.
  - code: webhook_endpoint_not_found
    status: 404
    category: not_found
    summary: The webhook endpoint was not found in the principal organization.
  - code: webhook_endpoint_create_failed
    status: 500
    category: server
    summary: The server could not persist a created webhook endpoint.
  - code: invalid_public_automation_source_query
    status: 400
    category: validation
    summary: The public automation source query parameters are invalid.
  - code: invalid_public_automation_source_create_request
    status: 400
    category: validation
    summary: The public automation source creation request body is invalid.
  - code: invalid_public_automation_source_update_request
    status: 400
    category: validation
    summary: The public automation source update request is invalid.
  - code: invalid_public_automation_source_delete_request
    status: 400
    category: validation
    summary: The public automation source delete request is invalid.
  - code: automation_write_disabled
    status: 403
    category: feature_gate
    summary: Automation write operations are disabled.
  - code: automation_source_create_failed
    status: 500
    category: server
    summary: The server could not persist a created automation source.
  - code: automation_source_not_found
    status: 404
    category: not_found
    summary: The automation source was not found in the principal organization.
  - code: invalid_public_automation_run_query
    status: 400
    category: validation
    summary: The public automation run query parameters are invalid.
  - code: invalid_public_automation_run_create_request
    status: 400
    category: validation
    summary: The public automation run creation request is invalid.
  - code: invalid_public_automation_run_record_request
    status: 400
    category: validation
    summary: The public automation run status update request is invalid.
  - code: automation_source_not_runnable
    status: 404
    category: not_found
    summary: The automation source was not found, disabled, or deleted in the principal organization.
  - code: automation_run_not_found
    status: 404
    category: not_found
    summary: The automation run was not found in the principal organization.
  - code: automation_run_invalid_transition
    status: 409
    category: conflict
    summary: The automation run cannot move from its current state to the requested state.
x-creavily-dashboard-permission-policies:
- id: workspace.brands.initialize
  label: Initialize the first workspace brand
  description: Create the first brand in an authorized workspace without changing existing brands or enabling provider actions.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: workspace.brands.create
  label: Create workspace brands
  description: Create additional brand context in a workspace without changing existing brands or enabling provider actions.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: publishing.drafts.manage
  label: Manage private Create drafts
  description: Read, save, and delete the signed-in member's private brand-scoped Create draft.
  minimumRole: member
  servicePrincipalAllowed: false
- id: billing.subscription.read
  label: Read workspace billing
  description: Read the workspace plan, subscription status, plan limits, and current usage.
  minimumRole: member
  servicePrincipalAllowed: false
- id: billing.subscription.manage
  label: Manage workspace billing
  description: Start Stripe Checkout for a plan, open the Stripe Customer Portal and redeem a plan code for the workspace.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: developer.api_keys.manage
  label: Manage developer API keys
  description: Create, list, and revoke organization-scoped public API keys.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: developer.oauth_apps.manage
  label: Manage OAuth apps
  description: Create, list, update, and revoke organization-scoped OAuth developer apps.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: developer.oauth_grants.manage
  label: Manage OAuth grants
  description: Create, list, exchange, and revoke organization-scoped OAuth authorization grants.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: developer.oauth_tokens.exchange
  label: Exchange developer OAuth tokens
  description: Use the dashboard-only OAuth token exchange helper for development and support.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: publishing.jobs.read
  label: Read publish jobs
  description: List organization-scoped publish jobs, queue status, and target status for the dashboard queue view.
  minimumRole: member
  servicePrincipalAllowed: false
- id: publishing.attention.manage
  label: Clear publishing attention
  description: Clear publish jobs from Needs attention with an optional reason, and restore them. Changes no publish state.
  minimumRole: member
  servicePrincipalAllowed: false
- id: publishing.batches.manage
  label: Manage publish batches
  description: Preview and apply product-diversified batch rebalance operations for dashboard scheduling.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: publishing.queue.reconcile
  label: Reconcile publish queue
  description: Inspect and optionally remove non-active queued publish jobs for an organization.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: publishing.urls.reconcile
  label: Reconcile publish URLs
  description: Write provider release URLs back into publish targets after external execution.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: publishing.results.manage
  label: Manage publish results
  description: Record provider publish attempts and update aggregate publish execution state.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: analytics.provider_sync.manage
  label: Sync provider analytics
  description: Fetch post status and analytics from connected provider accounts and persist analytics snapshots.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: engagement.comments.manage
  label: Manage social comments
  description: Fetch provider comments, persist the comment inbox, and publish comment replies from connected provider accounts.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: webhooks.endpoints.manage
  label: Manage webhook endpoints
  description: Create, list, update, and delete organization-scoped webhook endpoints.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: webhooks.deliveries.manage
  label: Manage webhook deliveries
  description: Enqueue, inspect, dispatch, and record attempts for webhook deliveries.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: automations.sources.manage
  label: Manage automation sources
  description: Create, update, delete, and manually run organization-scoped automation sources.
  minimumRole: admin
  servicePrincipalAllowed: false
- id: automations.scheduler.enqueue
  label: Enqueue automation scheduler
  description: Find due automation sources, create poll runs, and enqueue scheduler work.
  minimumRole: admin
  servicePrincipalAllowed: true
- id: platform.billing.read
  label: Read platform billing
  description: Read every workspace's plan, subscription, usage, promotion codes and redeem codes in the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.billing.manage
  label: Manage platform billing
  description: Grant or end manual plans, generate or disable promotion codes, and manage redeem codes from the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.blog.read
  label: Read the platform blog
  description: List posts of every status, open revisions and render previews in the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.blog.manage
  label: Edit the platform blog
  description: Create and edit draft posts for creavily.com/blog from the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.blog.publish
  label: Publish the platform blog
  description: Publish, schedule, unpublish and archive posts on creavily.com/blog from the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.admins.read
  label: Read platform admins
  description: List the people who can open the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.admins.manage
  label: Manage platform admins
  description: Grant platform admin to a verified user or remove it, from the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.users.read
  label: Read platform users
  description: List every user with sign-in methods, workspaces, sessions and recent activity in the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.switches.read
  label: Read operator switches
  description: See the operator switches, every gate's current value and the history of switch changes in the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.users.manage
  label: Manage platform users
  description: Suspend or reactivate a user, sign them out everywhere, resend or override email verification, from the platform admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true
- id: platform.activity.read
  label: Read platform activity
  description: Read the unified audit feed, sign-in log and activity metrics across the platform in the admin console.
  minimumRole: admin
  servicePrincipalAllowed: false
  internalOnly: true


# --- truncated at 32 KB (34 KB total) ---
# Full source: https://artifacts.apis.io/creavily/openapi/creavily-brands-api-openapi.yml