openapi: 3.0.3
info:
  title: OpenReplay Assist Users API
  version: '2.0'
  description: 'The OpenReplay Public REST API (v2) provides programmatic access to projects,

    sessions, events, users, background jobs, and live Assist sessions

    (Enterprise Edition). All endpoints accept and return JSON, with successful

    responses wrapped as `{ "data": ... }` and errors as `{ "error": "..." }`.'
  contact:
    name: OpenReplay
    url: https://openreplay.com
  license:
    name: Elastic License 2.0
    url: https://github.com/openreplay/openreplay/blob/dev/LICENSE
servers:
- url: https://api.openreplay.com/v2
  description: OpenReplay Cloud (serverless)
- url: https://{instance}/api/v2
  description: OpenReplay Cloud (dedicated) or self-hosted
  variables:
    instance:
      default: app.openreplay.example.com
      description: Your OpenReplay instance domain
security:
- bearerAuth: []
tags:
- name: Users
  description: Search, retrieve, and delete users and their associated data.
paths:
  /public/{projectKey}/users:
    post:
      tags:
      - Users
      summary: Search users
      description: Filter users by attributes (id, email, country, etc.) and paginate the results.
      operationId: searchUsers
      parameters:
      - $ref: '#/components/parameters/ProjectKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSearchRequest'
      responses:
        '200':
          description: Matching users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /public/{projectKey}/users/{userId}:
    parameters:
    - $ref: '#/components/parameters/ProjectKey'
    - $ref: '#/components/parameters/UserId'
    get:
      tags:
      - Users
      summary: Get user
      description: Retrieve identity attributes and aggregate statistics for a single user.
      operationId: getUser
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Users
      summary: Delete user
      description: Schedule a background job to delete a user and all of their associated data.
      operationId: deleteUser
      responses:
        '200':
          description: Deletion job scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    User:
      type: object
      additionalProperties: true
      properties:
        userId:
          type: string
        email:
          type: string
        country:
          type: string
        sessionsCount:
          type: integer
    UserSearchRequest:
      type: object
      properties:
        query:
          type: string
        filters:
          type: array
          items:
            type: object
            additionalProperties: true
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        page:
          type: integer
          minimum: 1
          default: 1
    Job:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
          - scheduled
          - running
          - completed
          - failed
          - cancelled
        createdAt:
          type: integer
          format: int64
    JobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Job'
    Error:
      type: object
      properties:
        error:
          type: string
    UserListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            total:
              type: integer
            users:
              type: array
              items:
                $ref: '#/components/schemas/User'
    UserResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/User'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      description: User identifier set via `tracker.setUserID`.
      schema:
        type: string
        maxLength: 256
    ProjectKey:
      name: projectKey
      in: path
      required: true
      description: Unique project key.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization API key from Preferences > Account > Organization API Key.