openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Experiences API
  description: The Contentstack Analytics API provides access to usage and performance metrics for CMS, Launch, and Automate products within a Contentstack organization. Developers can retrieve analytics data programmatically to build custom dashboards, monitor content delivery performance, and track platform usage against plan limits. The API returns structured data suitable for aggregation with external analytics and business intelligence tools. Access is restricted to organization Owners and Admins. Requests use async job-based processing where initial POST calls queue the job and a subsequent GET call retrieves the results.
  version: v2
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://api.contentstack.io
  description: AWS North America Production Server
- url: https://eu-api.contentstack.com
  description: AWS Europe Production Server
- url: https://au-api.contentstack.com
  description: AWS Australia Production Server
security:
- bearerAuth: []
- authtokenAuth: []
tags:
- name: Experiences
  description: Experiences define personalized content variations delivered to specific audience segments, supporting both segmented and A/B test configurations.
paths:
  /experiences:
    get:
      operationId: getAllExperiences
      summary: Get all experiences
      description: Retrieves all experience configurations in the Personalize project, including their variant definitions and audience assignments.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      responses:
        '200':
          description: A list of all experiences in the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperienceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createExperience
      summary: Create an experience
      description: Creates a new experience in the Personalize project. Experiences can be of type SEGMENTED (rule-based audience targeting) or AB_TEST (split testing with traffic distribution).
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExperienceRequest'
      responses:
        '201':
          description: The newly created experience.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /experiences/{id}:
    get:
      operationId: getExperience
      summary: Get an experience
      description: Retrieves details for a specific experience including its variants, audience assignments, status, and configuration.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/ExperienceId'
      - $ref: '#/components/parameters/ProjectUid'
      responses:
        '200':
          description: The requested experience.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateExperience
      summary: Update an experience
      description: Updates the configuration of an existing experience including its name, variants, and audience targeting rules.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/ExperienceId'
      - $ref: '#/components/parameters/ProjectUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExperienceRequest'
      responses:
        '200':
          description: The updated experience.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteExperience
      summary: Delete an experience
      description: Permanently deletes an experience from the Personalize project. Only experiences in draft or inactive status can be deleted.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/ExperienceId'
      - $ref: '#/components/parameters/ProjectUid'
      responses:
        '200':
          description: Experience deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /experiences/priority:
    get:
      operationId: getExperiencePriority
      summary: Get experience priority order
      description: Retrieves the priority ordering of all active experiences, which determines which experience takes precedence when a user qualifies for multiple experiences.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      responses:
        '200':
          description: The current experience priority ordering.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperiencePriority'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateExperiencePriority
      summary: Update experience priority order
      description: Updates the priority ordering of experiences to control which experience is applied first when a user qualifies for multiple active experiences.
      tags:
      - Experiences
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperiencePriority'
      responses:
        '200':
          description: Updated experience priority ordering.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperiencePriority'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Experience:
      type: object
      description: A personalization experience with variant and audience configuration.
      properties:
        uid:
          type: string
          description: Unique identifier of the experience.
        name:
          type: string
          description: Display name of the experience.
        type:
          type: string
          description: Type of experience — SEGMENTED for rule-based or AB_TEST for split testing.
          enum:
          - SEGMENTED
          - AB_TEST
        status:
          type: string
          description: Current status of the experience.
          enum:
          - DRAFT
          - ACTIVE
          - INACTIVE
          - ENDED
        variants:
          type: array
          description: List of content variants included in the experience.
          items:
            $ref: '#/components/schemas/ExperienceVariant'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the experience was created.
    ExperienceList:
      type: object
      description: A list of personalization experiences.
      properties:
        data:
          type: array
          description: Array of experience objects.
          items:
            $ref: '#/components/schemas/Experience'
    CreateExperienceRequest:
      type: object
      description: Parameters for creating or updating an experience.
      required:
      - name
      - type
      properties:
        name:
          type: string
          description: Display name for the experience.
        type:
          type: string
          description: Experience type.
          enum:
          - SEGMENTED
          - AB_TEST
        variants:
          type: array
          description: Variant definitions for the experience.
          items:
            $ref: '#/components/schemas/ExperienceVariant'
    ExperiencePriority:
      type: object
      description: Priority ordering of experiences for conflict resolution.
      properties:
        priority:
          type: array
          description: Ordered list of experience UIDs from highest to lowest priority.
          items:
            type: string
    ExperienceVariant:
      type: object
      description: A content variant within a personalization experience.
      properties:
        uid:
          type: string
          description: Unique identifier of the variant.
        name:
          type: string
          description: Display name of the variant.
        audience_uid:
          type: string
          description: UID of the audience this variant targets (for SEGMENTED experiences).
        traffic_percentage:
          type: number
          description: Percentage of traffic assigned to this variant (for AB_TEST experiences).
          minimum: 0
          maximum: 100
    Error:
      type: object
      description: Standard error response.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
        status:
          type: integer
          description: HTTP status code.
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ProjectUid:
      name: x-project-uid
      in: header
      required: true
      description: The UID of the Contentstack Personalize project.
      schema:
        type: string
    ExperienceId:
      name: id
      in: path
      required: true
      description: The unique identifier of the experience.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (M2M) with analytics access.
    authtokenAuth:
      type: apiKey
      in: header
      name: authtoken
      description: Contentstack user authtoken. Only organization Owners and Admins can access analytics.
externalDocs:
  description: Contentstack Analytics API Documentation
  url: https://www.contentstack.com/docs/developers/apis/analytics-api