AB Tasty Campaigns API

openapi: 3.2.0
info:
  title: AB Tasty Decision Campaigns API
  version: 2.0.0
  description: The AB Tasty Decision API is a server-side service that evaluates a visitors context against your active experiments, personalizations, and feature flags, then returns a deterministic decision which campaigns the user qualifies for, the selected variation, and any variables or content to render.
  contact:
    name: Flagship Support
    url: https://www.flagship.io
servers:
- url: https://decision.flagship.io/v2
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Campaigns
  description: Campaign assignment operations
paths:
  /{environmentId}/campaigns:
    post:
      tags:
      - Campaigns
      summary: AB Tasty Post Environment Campaigns
      description: 'Retrieves all the campaigns that correspond to the specified user and context attributes.

        By default, the API will send a CAMPAIGN hit to Flagship for each campaign in the response.'
      operationId: postEnvironmentidCampaigns
      parameters:
      - $ref: '#/components/parameters/EnvironmentId'
      - $ref: '#/components/parameters/Mode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignRequest'
            examples:
              basic:
                summary: Basic campaign request
                value:
                  visitor_id: user123
                  context:
                    device: mobile
                    platform: ios
                  visitor_consent: true
              withDecisionGroup:
                summary: Request with decision group
                value:
                  visitor_id: user456
                  context:
                    subscription: premium
                  visitor_consent: true
                  decision_group: VIP_users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CampaignResponseNormal'
                - $ref: '#/components/schemas/CampaignResponseSimple'
                - $ref: '#/components/schemas/CampaignResponseFull'
              examples:
                normalMode:
                  summary: Normal mode response
                  value:
                    visitorId: user123
                    campaigns:
                    - id: campaign_abc
                      variationGroupId: vg_123
                      variation:
                        id: var_456
                        modifications:
                          type: JSON
                          value:
                            button_color: blue
                            feature_enabled: true
                simpleMode:
                  summary: Simple mode response
                  value:
                    campaignsVariation:
                    - campaignId: campaign_abc
                      variationId: var_456
                    mergedModifications:
                      button_color: blue
                      feature_enabled: true
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{environmentId}/campaigns/{campaignId}:
    post:
      tags:
      - Campaigns
      summary: AB Tasty Post Environment Campaigns
      description: 'Retrieves the assignment of your visitor ID with a specific context to the specified campaign ID.

        By default, the API will send a CAMPAIGN hit to Flagship.'
      operationId: postEnvironmentidCampaignsCampaignid
      parameters:
      - $ref: '#/components/parameters/EnvironmentId'
      - $ref: '#/components/parameters/CampaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleCampaignRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
              example:
                id: campaign_abc
                variationGroupId: vg_123
                variation:
                  id: var_456
                  modifications:
                    type: JSON
                    value:
                      button_color: blue
        '302':
          description: Redirect response (when default_redirect_url is specified)
          headers:
            Location:
              schema:
                type: string
              description: Redirect URL
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CampaignVariation:
      type: object
      properties:
        campaignId:
          type: string
          example: campaign_abc
        variationId:
          type: string
          example: var_456
    CampaignRequest:
      type: object
      required:
      - visitor_id
      properties:
        visitor_id:
          type: string
          description: Unique identifier for the application user or website visitor
          example: user123
        anonymous_id:
          type: string
          description: Identifier for anonymous visitors (e.g., session ID)
          example: session_xyz
        context:
          type: object
          description: JSON object of key-value pairs describing the user and device context
          additionalProperties: true
          example:
            device: mobile
            platform: ios
            subscription_level: premium
        visitor_consent:
          type: boolean
          description: Determines if visitor has consented to GDPR rules
          default: true
        trigger_hit:
          type: boolean
          description: Determines whether a CAMPAIGN hit should be automatically sent
          default: true
        decision_group:
          type: string
          nullable: true
          description: Groups visitors to receive the same variation assignment
          example: VIP_users
    CampaignResponseFull:
      type: object
      properties:
        visitorId:
          type: string
          example: user123
        campaigns:
          type: array
          items:
            $ref: '#/components/schemas/Campaign'
        campaignsVariation:
          type: array
          items:
            $ref: '#/components/schemas/CampaignVariation'
        mergedModifications:
          type: object
          additionalProperties: true
    Campaign:
      type: object
      properties:
        id:
          type: string
          description: Campaign ID
          example: campaign_abc
        variationGroupId:
          type: string
          description: Variation group ID (corresponds to a scenario in Flagship)
          example: vg_123
        variation:
          type: object
          properties:
            id:
              type: string
              description: Variation ID
              example: var_456
            modifications:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - 'NULL'
                  - JSON
                  - TEXT
                  - IMAGE
                  - HTML
                  - FLAG
                  - REDIRECT
                  description: The modification type
                value:
                  oneOf:
                  - type: object
                  - type: string
                  description: The value of the modification (structure depends on type)
                  example:
                    button_color: blue
                    feature_enabled: true
    CampaignResponseSimple:
      type: object
      properties:
        campaignsVariation:
          type: array
          items:
            $ref: '#/components/schemas/CampaignVariation'
        mergedModifications:
          type: object
          additionalProperties: true
          description: All remote values merged into a single object
          example:
            button_color: blue
            feature_enabled: true
            welcome_text: Hello!
    CampaignResponseNormal:
      type: object
      properties:
        visitorId:
          type: string
          example: user123
        campaigns:
          type: array
          items:
            $ref: '#/components/schemas/Campaign'
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    SingleCampaignRequest:
      allOf:
      - $ref: '#/components/schemas/CampaignRequest'
      - type: object
        properties:
          format_response:
            type: boolean
            description: If true, response will be formatted according to modification type
            default: false
          default_redirect_url:
            type: string
            description: Default URL for 302 redirect if no modification redirection is defined
            example: https://example.com/default
  parameters:
    Mode:
      name: mode
      in: query
      required: false
      description: Specifies the format of the response body
      schema:
        type: string
        enum:
        - normal
        - simple
        - full
        default: normal
    CampaignId:
      name: campaignId
      in: path
      required: true
      description: Campaign ID or slug
      schema:
        type: string
      example: campaign_abc
    EnvironmentId:
      name: environmentId
      in: path
      required: true
      description: Identifies your account and environment (preprod or prod)
      schema:
        type: string
      example: env_abc123
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Invalid API key
            code: UNAUTHORIZED
    RateLimitError:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Rate limit exceeded. Maximum 200 req/s with burst of 600 req/s
            code: RATE_LIMIT_EXCEEDED
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Can be found in Flagship Platform under Parameters / Environment & Security