contentstack User Attributes API

openapi: 3.2.0
info:
  title: Contentstack Personalize Edge User Attributes API
  description: The Contentstack Personalize Edge API enables real-time, dynamic personalization interactions using edge computing to deliver targeted content experiences. It allows applications to retrieve personalized manifests of active experiences, set and update user attributes for audience matching, merge user identity records, and track behavioral events. The Edge API does not require user authentication since it operates on public-facing digital properties and uses project and user identifier headers for context.
  version: v1
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://personalize-edge.contentstack.com
  description: AWS North America Production Server
- url: https://eu-personalize-edge.contentstack.com
  description: AWS Europe Production Server
- url: https://au-personalize-edge.contentstack.com
  description: AWS Australia Production Server
- url: https://azure-na-personalize-edge.contentstack.com
  description: Azure North America Production Server
- url: https://azure-eu-personalize-edge.contentstack.com
  description: Azure Europe Production Server
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:
  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.
  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'
externalDocs:
  description: Contentstack Personalize Edge API Documentation
  url: https://www.contentstack.com/docs/developers/apis/personalize-edge-api