Creavily Provider Tools API

openapi: 3.2.0
info:
  title: Creavily Public Provider Tools 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: Provider Tools
paths:
  /v1/provider-capabilities:
    get:
      tags:
      - Provider Tools
      operationId: listProviderCapabilities
      summary: List public provider capability, tool, and plug metadata for platform-aware…
      responses:
        '200':
          description: Public provider capability catalog for rendering provider settings, tools, and plugs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderCapabilitiesResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /v1/provider-tools/execute:
    post:
      tags:
      - Provider Tools
      operationId: executeProviderTool
      summary: Dry-run or execute a dashboard provider account/composer lookup tool
      security:
      - dashboardSession: []
      x-env-gates:
      - CREAVILY_ALLOW_PROVIDER_TOOL_EXECUTION=true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  minLength: 1
                brandId:
                  type: string
                  minLength: 1
                platform:
                  type: string
                  enum:
                  - instagram_business
                  - instagram_standalone
                  - facebook_page
                  - threads
                  - youtube
                  - pinterest
                  - tiktok
                  - x
                channelAccountId:
                  type: string
                  minLength: 1
                name:
                  type: string
                  enum:
                  - mentionSearch
                  - pageProfile
                  - channelCategories
                  - boardList
                  - privacyOptions
                  - communitySearch
                settings:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                dryRun:
                  default: true
                  type: boolean
              required:
              - organizationId
              - brandId
              - platform
              - channelAccountId
              - name
      responses:
        '200':
          description: Dry-run plan, or executed provider tool result with redacted provider output.
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  properties:
                    mode:
                      type: string
                      const: dry_run
                    dryRun:
                      type: boolean
                      const: true
                    target:
                      type: object
                      properties:
                        organizationId:
                          type: string
                        brandId:
                          type: string
                        platform:
                          type: string
                          enum:
                          - instagram_business
                          - instagram_standalone
                          - facebook_page
                          - threads
                          - youtube
                          - pinterest
                          - tiktok
                          - x
                        channelAccountId:
                          type: string
                        toolName:
                          type: string
                          enum:
                          - mentionSearch
                          - pageProfile
                          - channelCategories
                          - boardList
                          - privacyOptions
                          - communitySearch
                      required:
                      - organizationId
                      - brandId
                      - platform
                      - channelAccountId
                      - toolName
                      additionalProperties: false
                    wouldLoadChannelTokenRef:
                      type: boolean
                      const: true
                    wouldFetchProvider:
                      type: boolean
                      const: true
                    requiredEnv:
                      type: array
                      items:
                        type: string
                  required:
                  - mode
                  - dryRun
                  - target
                  - wouldLoadChannelTokenRef
                  - wouldFetchProvider
                  - requiredEnv
                  additionalProperties: false
                - type: object
                  properties:
                    mode:
                      type: string
                      const: executed
                    dryRun:
                      type: boolean
                      const: false
                    target:
                      type: object
                      properties:
                        organizationId:
                          type: string
                        brandId:
                          type: string
                        platform:
                          type: string
                          enum:
                          - instagram_business
                          - instagram_standalone
                          - facebook_page
                          - threads
                          - youtube
                          - pinterest
                          - tiktok
                          - x
                        channelAccountId:
                          type: string
                        toolName:
                          type: string
                          enum:
                          - mentionSearch
                          - pageProfile
                          - channelCategories
                          - boardList
                          - privacyOptions
                          - communitySearch
                      required:
                      - organizationId
                      - brandId
                      - platform
                      - channelAccountId
                      - toolName
                      additionalProperties: false
                    result:
                      type: object
                      properties:
                        name:
                          type: string
                          enum:
                          - mentionSearch
                          - pageProfile
                          - channelCategories
                          - boardList
                          - privacyOptions
                          - communitySearch
                        outputKind:
                          type: string
                          enum:
                          - account_reference
                          - profile
                          - category
                          - board
                          - privacy_option
                          - community
                        items:
                          type: array
                          items:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                        profile:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties: {}
                        pagination:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties: {}
                      required:
                      - name
                      - outputKind
                      - items
                  required:
                  - mode
                  - dryRun
                  - target
                  - result
                  additionalProperties: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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'
    NotFound:
      description: Requested public API resource was not found.
      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'
    UnprocessableEntity:
      description: The request is valid JSON but violates publish validation rules.
      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:
    ProviderCapabilitiesResponse:
      type: object
      properties:
        providers:
          type: array
          items:
            type: object
            properties:
              platform:
                type: string
                enum:
                - instagram_business
                - instagram_standalone
                - facebook_page
                - threads
                - youtube
                - pinterest
                - tiktok
                - x
              displayName:
                type: string
              requiredScopes:
                type: array
                items:
                  type: string
              maxTextLength:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              mediaRule:
                type: object
                properties:
                  allowedKinds:
                    type: array
                    items:
                      type: string
                      enum:
                      - image
                      - video
                      - gif
                  minItems:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  maxItems:
                    type: integer
                    minimum: 1
                    maximum: 9007199254740991
                  maxImageBytes:
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  maxVideoBytes:
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  maxGifBytes:
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  minVideoDurationSeconds:
                    type: number
                    minimum: 0
                  maxVideoDurationSeconds:
                    type: number
                    minimum: 0
                  dynamicMaxVideoDurationSetting:
                    type: string
                  requiresVideoThumbnail:
                    type: boolean
                  notes:
                    type: array
                    items:
                      type: string
                required:
                - allowedKinds
                - minItems
                - maxItems
                - notes
                additionalProperties: false
              supportsScheduling:
                type: boolean
              supportsComments:
                type: boolean
              supportsAnalytics:
                type: boolean
              supportsDelete:
                type: boolean
              supportsUpdate:
                type: boolean
              settingsFields:
                type: array
                items:
                  type: string
              settingRules:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    label:
                      type: string
                    valueType:
                      type: string
                      enum:
                      - string
                      - boolean
                      - number
                    required:
                      type: boolean
                    allowedValues:
                      type: array
                      items:
                        type: string
                  required:
                  - field
                  - label
                  - valueType
                  - required
                  additionalProperties: false
              toolNames:
                type: array
                items:
                  type: string
                  enum:
                  - mentionSearch
                  - pageProfile
                  - channelCategories
                  - boardList
                  - privacyOptions
                  - communitySearch
              plugNames:
                type: array
                items:
                  type: string
                  enum:
                  - firstComment
                  - reply
              rateLimitPolicy:
                type: string
                enum:
                - low_concurrency
                - standard
                - strict
            required:
            - platform
            - displayName
            - requiredScopes
            - mediaRule
            - supportsScheduling
            - supportsComments
            - supportsAnalytics
            - supportsDelete
            - supportsUpdate
            - settingsFields
            - toolNames
            - plugNames
            - rateLimitPolicy
            additionalProperties: false
        tools:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                enum:
                - mentionSearch
                - pageProfile
                - channelCategories
                - boardList
                - privacyOptions
                - communitySearch
              label:
                type: string
              category:
                type: string
                enum:
                - account_lookup
                - composer_lookup
                - publishing_option
              description:
                type: string
              platforms:
                type: array
                items:
                  type: string
                  enum:
                  - instagram_business
                  - instagram_standalone
                  - facebook_page
                  - threads
                  - youtube
                  - pinterest
                  - tiktok
                  - x
              inputFields:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    label:
                      type: string
                    valueType:
                      type: string
                      enum:
                      - string
                      - boolean
                      - number
                    required:
                      type: boolean
                    allowedValues:
                      type: array
                      items:
                        type: string
                  required:
                  - field
                  - label
                  - valueType
                  - required
                  additionalProperties: false
              outputKind:
                type: string
                enum:
                - account_reference
                - profile
                - category
                - board
                - privacy_option
                - community
            required:
            - name
            - label
            - category
            - description
            - platforms
            - inputFields
            - outputKind
            additionalProperties: false
        plugs:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                enum:
                - firstComment
                - reply
              label:
                type: string
              phase:
                type: string
                enum:
                - post_publish
                - threading
              description:
                type: string
              platforms:
                type: array
                items:
                  type: string
                  enum:
                  - instagram_business
                  - instagram_standalone
                  - facebook_page
                  - threads
                  - youtube
                  - pinterest
                  - tiktok
                  - x
              settingRules:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    label:
                      type: string
                    valueType:
                      type: string
                      enum:
                      - string
                      - boolean
                      - number
                    required:
                      type: boolean
                    allowedValues:
                      type: array
                      items:
                        type: string
                  required:
                  - field
                  - label
                  - valueType
                  - required
                  additionalProperties: false
            required:
            - name
            - label
            - phase
            - description
            - platforms
            - settingRules
            additionalProperties: false
      required:
      - providers
      - tools
      - plugs
      additionalProperties: false
    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.


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