Creavily Bridges API

openapi: 3.2.0
info:
  title: Creavily Public Bridges 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: Bridges
paths:
  /v1/bridges/postiz/handoff/preview:
    post:
      tags:
      - Bridges
      operationId: previewInternalPostizHandoff
      summary: Preview a Postiz handoff for an internal caller
      security:
      - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan:
                  type: object
                  properties:
                    organizationId:
                      type: string
                      minLength: 1
                    brandId:
                      type: string
                      minLength: 1
                    productId:
                      type: string
                    text:
                      type: string
                    media:
                      type: array
                      items:
                        type: object
                        properties:
                          mediaLibraryItemId:
                            type: string
                            minLength: 1
                          kind:
                            type: string
                            enum:
                            - image
                            - video
                            - gif
                          url:
                            type: string
                            minLength: 1
                          mimeType:
                            type: string
                          bytes:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          width:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          height:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          durationSeconds:
                            type: number
                            exclusiveMinimum: 0
                          altText:
                            type: string
                          thumbnailUrl:
                            type: string
                        required:
                        - kind
                        - url
                    targets:
                      type: array
                      items:
                        type: object
                        properties:
                          platform:
                            type: string
                            enum:
                            - instagram_business
                            - instagram_standalone
                            - facebook_page
                            - threads
                            - youtube
                            - pinterest
                            - tiktok
                            - x
                          channelAccountId:
                            type: string
                            minLength: 1
                          text:
                            type: string
                          settings:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                        required:
                        - platform
                        - channelAccountId
                    scheduleAt:
                      type: string
                  required:
                  - organizationId
                  - brandId
                  - text
                  - media
                  - targets
                uploadedMedia:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                      path:
                        type: string
                        minLength: 1
                      name:
                        type: string
                    required:
                    - id
                    - path
                integrationMappings:
                  type: array
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        enum:
                        - instagram_business
                        - instagram_standalone
                        - facebook_page
                        - threads
                        - youtube
                        - pinterest
                        - tiktok
                        - x
                      channelAccountId:
                        type: string
                        minLength: 1
                      postizIntegrationId:
                        type: string
                        minLength: 1
                    required:
                    - platform
                    - channelAccountId
                    - postizIntegrationId
                mode:
                  type: string
                  enum:
                  - draft
                  - now
                  - schedule
                shortLink:
                  type: boolean
                date:
                  type: string
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      value:
                        type: string
                        minLength: 1
                      label:
                        type: string
                        minLength: 1
                    required:
                    - value
                    - label
              required:
              - plan
              - uploadedMedia
              - integrationMappings
      responses:
        '200':
          description: Postiz handoff preview.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - draft
                        - now
                        - schedule
                      shortLink:
                        type: boolean
                      date:
                        type: string
                      tags:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                            label:
                              type: string
                          required:
                          - value
                          - label
                          additionalProperties: false
                      posts:
                        type: array
                        items:
                          type: object
                          properties:
                            integration:
                              type: object
                              properties:
                                id:
                                  type: string
                              required:
                              - id
                              additionalProperties: false
                            value:
                              type: array
                              items:
                                type: object
                                properties:
                                  content:
                                    type: string
                                  image:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                        path:
                                          type: string
                                        name:
                                          type: string
                                        size:
                                          type: integer
                                          minimum: 0
                                          maximum: 9007199254740991
                                      required:
                                      - id
                                      - path
                                      additionalProperties: false
                                required:
                                - content
                                - image
                                additionalProperties: false
                            settings:
                              type: object
                              propertyNames:
                                type: string
                              additionalProperties: {}
                          required:
                          - integration
                          - value
                          - settings
                          additionalProperties: false
                    required:
                    - type
                    - shortLink
                    - date
                    - tags
                    - posts
                    additionalProperties: false
                  readyTargets:
                    type: array
                    items:
                      type: object
                      properties:
                        targetId:
                          type: string
                        platform:
                          type: string
                          enum:
                          - instagram_business
                          - instagram_standalone
                          - facebook_page
                          - threads
                          - youtube
                          - pinterest
                          - tiktok
                          - x
                        channelAccountId:
                          type: string
                        postizIntegrationId:
                          type: string
                      required:
                      - targetId
                      - platform
                      - channelAccountId
                      - postizIntegrationId
                      additionalProperties: false
                  blockedTargets:
                    type: array
                    items:
                      type: object
                      properties:
                        targetId:
                          type: string
                        platform:
                          type: string
                          enum:
                          - instagram_business
                          - instagram_standalone
                          - facebook_page
                          - threads
                          - youtube
                          - pinterest
                          - tiktok
                          - x
                        channelAccountId:
                          type: string
                        reason:
                          type: string
                          enum:
                          - missing_integration_mapping
                          - validation_error
                        message:
                          type: string
                      required:
                      - targetId
                      - platform
                      - channelAccountId
                      - reason
                      - message
                      additionalProperties: false
                required:
                - payload
                - readyTargets
                - blockedTargets
                additionalProperties: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /v1/bridges/postiz/execute:
    post:
      tags:
      - Bridges
      operationId: executeInternalPostizHandoff
      summary: Dry-run a Postiz handoff for an internal caller
      security:
      - internalServiceToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan:
                  type: object
                  properties:
                    organizationId:
                      type: string
                      minLength: 1
                    brandId:
                      type: string
                      minLength: 1
                    productId:
                      type: string
                    text:
                      type: string
                    media:
                      type: array
                      items:
                        type: object
                        properties:
                          mediaLibraryItemId:
                            type: string
                            minLength: 1
                          kind:
                            type: string
                            enum:
                            - image
                            - video
                            - gif
                          url:
                            type: string
                            minLength: 1
                          mimeType:
                            type: string
                          bytes:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          width:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          height:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          durationSeconds:
                            type: number
                            exclusiveMinimum: 0
                          altText:
                            type: string
                          thumbnailUrl:
                            type: string
                        required:
                        - kind
                        - url
                    targets:
                      type: array
                      items:
                        type: object
                        properties:
                          platform:
                            type: string
                            enum:
                            - instagram_business
                            - instagram_standalone
                            - facebook_page
                            - threads
                            - youtube
                            - pinterest
                            - tiktok
                            - x
                          channelAccountId:
                            type: string
                            minLength: 1
                          text:
                            type: string
                          settings:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                        required:
                        - platform
                        - channelAccountId
                    scheduleAt:
                      type: string
                  required:
                  - organizationId
                  - brandId
                  - text
                  - media
                  - targets
                localMedia:
                  type: array
                  items:
                    type: object
                    properties:
                      filePath:
                        type: string
                        minLength: 1
                      mimeType:
                        type: string
                        minLength: 1
                      fileName:
                        type: string
                        minLength: 1
                    required:
                    - filePath
                    - mimeType
                integrationMappings:
                  type: array
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        enum:
                        - instagram_business
                        - instagram_standalone
                        - facebook_page
                        - threads
                        - youtube
                        - pinterest
                        - tiktok
                        - x
                      channelAccountId:
                        type: string
                        minLength: 1
                      postizIntegrationId:
                        type: string
                        minLength: 1
                    required:
                    - platform
                    - channelAccountId
                    - postizIntegrationId
                mode:
                  type: string
                  enum:
                  - draft
                  - now
                  - schedule
                shortLink:
                  type: boolean
                date:
                  type: string
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      value:
                        type: string
                        minLength: 1
                      label:
                        type: string
                        minLength: 1
                    required:
                    - value
                    - label
                dryRun:
                  default: true
                  type: boolean
              required:
              - plan
              - localMedia
              - integrationMappings
      responses:
        '200':
          description: Dry-run Postiz handoff result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mode:
                    type: string
                    const: dry_run
                  uploadedMedia:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        path:
                          type: string
                        name:
                          type: string
                        size:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                      required:
                      - id
                      - path
                      additionalProperties: false
                  preview:
                    type: object
                    properties:
                      payload:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - draft
                            - now
                            - schedule
                          shortLink:
                            type: boolean
                          date:
                            type: string
                          tags:
                            type: array
                            items:
                              type: object
                              properties:
                                value:
                                  type: string
                                label:
                                  type: string
                              required:
                              - value
                              - label
                              additionalProperties: false
                          posts:
                            type: array
                            items:
                              type: object
                              properties:
                                integration:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                  required:
                                  - id
                                  additionalProperties: false
                                value:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      content:
                                        type: string
                                      image:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            id:
                                              type: string
                                            path:
                                              type: string
                                            name:
                                              type: string
                                            size:
                                              type: integer
                                              minimum: 0
                                              maximum: 9007199254740991
                                          required:
                                          - id
                                          - path
                                          additionalProperties: false
                                    required:
                                    - content
                                    - image
                                    additionalProperties: false
                                settings:
                                  type: object
                                  propertyNames:
                                    type: string
                                  additionalProperties: {}
                              required:
                              - integration
                              - value
                              - settings
                              additionalProperties: false
                        required:
                        - type
                        - shortLink
                        - date
                        - tags
                        - posts
                        additionalProperties: false
                      readyTargets:
                        type: array
                        items:
                          type: object
                          properties:
                            targetId:
                              type: string
                            platform:
                              type: string
                              enum:
                              - instagram_business
                              - instagram_standalone
                              - facebook_page
                              - threads
                              - youtube
                              - pinterest
                              - tiktok
                              - x
                            channelAccountId:
                              type: string
                            postizIntegrationId:
                              type: string
                          required:
                          - targetId
                          - platform
                          - channelAccountId
                          - postizIntegrationId
                          additionalProperties: false
                      blockedTargets:
                        type: array
                        items:
                          type: object
                          properties:
                            targetId:
                              type: string
                            platform:
                              type: string
                              enum:
                              - instagram_business
                              - instagram_standalone
                              - facebook_page
                              - threads
                              - youtube
                              - pinterest
                              - tiktok
                              - x
                            channelAccountId:
                              type: string
                            reason:
                              type: string
                              enum:
                              - missing_integration_mapping
                              - validation_error
                            message:
                              type: string
                          required:
                          - targetId
                          - platform
                          - channelAccountId
                          - reason
                          - message
                          additionalProperties: false
                    required:
                    - payload
                    - readyTargets
                    - blockedTargets
                    additionalProperties: false
                  createPostResponse:
                    type: 'null'
                required:
                - mode
                - uploadedMedia
                - preview
                - createPostResponse
                additionalProperties: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
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'
    Forbidden:
      description: Feature gate disabled or token missing required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: The request conflicts with current resource state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: The server failed while handling the request.
      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.


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