Creavily Admin API

openapi: 3.2.0
info:
  title: Creavily Public Admin 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: Admin
paths:
  /v1/admin/db/migrate:
    post:
      tags:
      - Admin
      operationId: runDatabaseMigrations
      summary: Dry-run or apply the database migration inventory
      security:
      - dashboardSession: []
      x-required-policy: admin.db.migrate
      x-env-gates:
      - CREAVILY_ALLOW_DB_MIGRATIONS=true
      - CREAVILY_RELEASE_MIGRATION_APPROVED=true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dryRun:
                  default: true
                  type: boolean
      responses:
        '200':
          description: Dry-run migration inventory or applied migration result.
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  properties:
                    mode:
                      type: string
                      const: dry_run
                    migrations:
                      type: array
                      items:
                        type: object
                        properties:
                          executionMode:
                            type: string
                            enum:
                            - transactional
                            - non_transactional
                            - online
                          lockRisk:
                            type: string
                            enum:
                            - low
                            - medium
                            - high
                          compatibility:
                            type: string
                            enum:
                            - backward-compatible
                            - expand-contract
                          recovery:
                            type: string
                            enum:
                            - transactional-rollback
                            - retry-safe
                            - manual-recovery
                          id:
                            type: string
                          filePath:
                            type: string
                          checksum:
                            type: string
                        required:
                        - executionMode
                        - lockRisk
                        - compatibility
                        - recovery
                        - id
                        - filePath
                        - checksum
                        additionalProperties: false
                  required:
                  - mode
                  - migrations
                  additionalProperties: false
                - type: object
                  properties:
                    mode:
                      type: string
                      const: applied
                    result:
                      type: object
                      properties:
                        migrations:
                          type: array
                          items:
                            type: object
                            properties:
                              executionMode:
                                type: string
                                enum:
                                - transactional
                                - non_transactional
                                - online
                              lockRisk:
                                type: string
                                enum:
                                - low
                                - medium
                                - high
                              compatibility:
                                type: string
                                enum:
                                - backward-compatible
                                - expand-contract
                              recovery:
                                type: string
                                enum:
                                - transactional-rollback
                                - retry-safe
                                - manual-recovery
                              schemaPhase:
                                anyOf:
                                - type: string
                                  enum:
                                  - expand
                                  - contract
                                  - none
                                - type: 'null'
                              minimumAppVersion:
                                type:
                                - string
                                - 'null'
                              previousAppCompatible:
                                type:
                                - boolean
                                - 'null'
                              destructive:
                                type:
                                - boolean
                                - 'null'
                              requiresManualApproval:
                                type:
                                - boolean
                                - 'null'
                              id:
                                type: string
                              checksum:
                                type: string
                              ledgerChecksum:
                                type:
                                - string
                                - 'null'
                              applied:
                                type: boolean
                              durationMs:
                                type:
                                - number
                                - 'null'
                              toolVersion:
                                type:
                                - string
                                - 'null'
                            required:
                            - executionMode
                            - lockRisk
                            - compatibility
                            - recovery
                            - schemaPhase
                            - minimumAppVersion
                            - previousAppCompatible
                            - destructive
                            - requiresManualApproval
                            - id
                            - checksum
                            - ledgerChecksum
                            - applied
                            - durationMs
                            - toolVersion
                            additionalProperties: false
                        appliedCount:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                      required:
                      - migrations
                      - appliedCount
                      additionalProperties: false
                  required:
                  - mode
                  - result
                  additionalProperties: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /v1/admin/provider-comment-webhooks/provision:
    post:
      tags:
      - Admin
      operationId: provisionProviderCommentWebhooks
      summary: Register provider app identities, webhook bindings, and explicit…
      security:
      - dashboardSession: []
      - servicePrincipalToken: []
      x-required-policy: admin.provider.webhook.provision
      x-env-gates:
      - CREAVILY_ALLOW_PROVIDER_WEBHOOK_PROVISIONING=true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationId:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                apps:
                  minItems: 1
                  maxItems: 5
                  type: array
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        enum:
                        - facebook_page
                        - instagram_business
                        - instagram_standalone
                        - threads
                        - x
                      name:
                        type: string
                        minLength: 1
                        maxLength: 200
                      clientId:
                        type: string
                        minLength: 1
                        maxLength: 200
                      secretRef:
                        type: string
                        pattern: ^(?:env|secret-manager|sm):[A-Za-z0-9._:/-]+$
                    required:
                    - platform
                    - name
                    - clientId
                    - secretRef
                    additionalProperties: false
                channelAccountIds:
                  default: []
                  maxItems: 100
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              required:
              - organizationId
              - apps
              additionalProperties: false
      responses:
        '200':
          description: Provisioned provider apps and webhook bindings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      apps:
                        minItems: 1
                        type: array
                        items:
                          type: object
                          properties:
                            platformAppId:
                              type: string
                              format: uuid
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            platform:
                              type: string
                              enum:
                              - facebook_page
                              - instagram_business
                              - instagram_standalone
                              - threads
                              - x
                            name:
                              type: string
                            clientId:
                              type: string
                            bindingId:
                              type: string
                              format: uuid
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          required:
                          - platformAppId
                          - platform
                          - name
                          - clientId
                          - bindingId
                          additionalProperties: false
                      linkedChannelAccountIds:
                        type: array
                        items:
                          type: string
                          format: uuid
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    required:
                    - apps
                    - linkedChannelAccountIds
                    additionalProperties: false
                required:
                - result
                additionalProperties: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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'
    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.
  - 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


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