openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts User Attributes 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: User Attributes
  description: Endpoints for setting, updating, and merging user attribute data used to determine audience membership and personalized content targeting.
paths:
  /user-attributes:
    patch:
      operationId: setUserAttributes
      summary: Set and update user attributes
      description: Persists custom user attribute values at the Personalize Edge for use in audience rule evaluation. Attributes set via this endpoint are stored against the user's identifier and used in all subsequent manifest requests. Use this endpoint to update attributes based on user actions or profile data from external systems.
      tags:
      - User Attributes
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      - $ref: '#/components/parameters/PersonalizeUserUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAttributesRequest'
      responses:
        '204':
          description: User attributes added or updated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
  /user-attributes/actions/merge:
    post:
      operationId: mergeUserAttributes
      summary: Merge user attributes
      description: Merges the attributes of a source user identity into a target user identity. This is used in identity resolution scenarios where an anonymous user record needs to be combined with an authenticated user record upon login, preserving all accumulated behavioral and attribute data.
      tags:
      - User Attributes
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeUserAttributesRequest'
      responses:
        '204':
          description: User attributes merged successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    Forbidden:
      description: The request is not authorized for this project.
      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'
  parameters:
    ProjectUid:
      name: x-project-uid
      in: header
      required: true
      description: The UID of the Contentstack Personalize project.
      schema:
        type: string
    PersonalizeUserUid:
      name: x-cs-personalize-user-uid
      in: header
      required: false
      description: The unique identifier for the end user. If not provided, a new anonymous user will be created and the UID returned in the response headers.
      schema:
        type: string
  schemas:
    UserAttributesRequest:
      type: object
      description: Key-value pairs of user attribute values to set or update. Keys must correspond to attribute keys defined in the Personalize Management API.
      additionalProperties:
        description: Attribute value. Type must match the attribute's defined data type.
    MergeUserAttributesRequest:
      type: object
      description: Parameters for merging two user identity records.
      required:
      - sourceUserUid
      - targetUserUid
      properties:
        sourceUserUid:
          type: string
          description: The UID of the source user whose attributes will be merged into the target. Typically the anonymous user UID.
        targetUserUid:
          type: string
          description: The UID of the target user who will receive the merged attributes. Typically the authenticated user UID.
    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.
  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