openapi: 3.0.3
info:
  title: OpenReplay 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: Projects
    description: Create and retrieve projects.
  - name: Sessions
    description: Retrieve recorded sessions for a given user.
  - name: Events
    description: Retrieve events captured within a recorded session.
  - name: Users
    description: Search, retrieve, and delete users and their associated data.
  - name: Jobs
    description: Manage background jobs such as user-deletion tasks.
  - name: Assist
    description: Retrieve live Assist sessions (Enterprise Edition only).
paths:
  /public/projects:
    get:
      tags: [Projects]
      summary: List projects
      description: Retrieve all projects belonging to the authenticated tenant.
      operationId: listProjects
      responses:
        '200':
          description: Array of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListResponse'
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Projects]
      summary: Create project
      description: Create a new project for the authenticated tenant.
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreateRequest'
      responses:
        '200':
          description: Created project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /public/projects/{projectKey}:
    get:
      tags: [Projects]
      summary: Get project
      description: Retrieve a single project by its `projectKey`.
      operationId: getProject
      parameters:
        - $ref: '#/components/parameters/ProjectKey'
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '404': { $ref: '#/components/responses/NotFound' }
  /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' }
  /public/{projectKey}/users/{userId}/sessions:
    post:
      tags: [Sessions]
      summary: List user sessions
      description: Return sessions for a particular user (identified via `tracker.setUserID`). Paginated.
      operationId: listUserSessions
      parameters:
        - $ref: '#/components/parameters/ProjectKey'
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionsRequest'
      responses:
        '200':
          description: Matching sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
        '400': { $ref: '#/components/responses/BadRequest' }
  /public/{projectKey}/sessions/{sessionId}/events:
    post:
      tags: [Events]
      summary: List session events
      description: Returns events (clicks, page visits, inputs, custom events, etc.) captured in a specific session.
      operationId: listSessionEvents
      parameters:
        - $ref: '#/components/parameters/ProjectKey'
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            maxLength: 256
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsRequest'
      responses:
        '200':
          description: Session events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
        '400': { $ref: '#/components/responses/BadRequest' }
  /public/{projectKey}/jobs:
    get:
      tags: [Jobs]
      summary: List jobs
      description: Retrieve all jobs for a project, including completed and cancelled ones. Paginated.
      operationId: listJobs
      parameters:
        - $ref: '#/components/parameters/ProjectKey'
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
      responses:
        '200':
          description: Jobs list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
  /public/{projectKey}/jobs/{jobId}:
    parameters:
      - $ref: '#/components/parameters/ProjectKey'
      - name: jobId
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Jobs]
      summary: Get job
      description: Return a job's status and metadata.
      operationId: getJob
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Jobs]
      summary: Cancel job
      description: Cancel a job that hasn't started yet or is still in progress.
      operationId: cancelJob
      responses:
        '200':
          description: Job cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '404': { $ref: '#/components/responses/NotFound' }
  /public/{projectKey}/assist/sessions:
    parameters:
      - $ref: '#/components/parameters/ProjectKey'
    get:
      tags: [Assist]
      summary: List live sessions
      description: Return live sessions for the project. Optionally filter by `userId`. Enterprise Edition only.
      operationId: listLiveSessions
      parameters:
        - name: userId
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Live sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
    post:
      tags: [Assist]
      summary: Search live sessions
      description: Search live sessions using filtering, sorting, and pagination options. Enterprise Edition only.
      operationId: searchLiveSessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionsRequest'
      responses:
        '200':
          description: Matching live sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization API key from Preferences > Account > Organization API Key.
  parameters:
    ProjectKey:
      name: projectKey
      in: path
      required: true
      description: Unique project key.
      schema: { type: string }
    UserId:
      name: userId
      in: path
      required: true
      description: User identifier set via `tracker.setUserID`.
      schema:
        type: string
        maxLength: 256
  responses:
    BadRequest:
      description: Invalid input
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      properties:
        error: { type: string }
    Project:
      type: object
      properties:
        projectId: { type: integer }
        projectKey: { type: string }
        name: { type: string }
        platform:
          type: string
          enum: [web, ios]
    ProjectCreateRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          maxLength: 200
        platform:
          type: string
          enum: [web, ios]
    ProjectResponse:
      type: object
      properties:
        data: { $ref: '#/components/schemas/Project' }
    ProjectListResponse:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Project' }
    SessionsRequest:
      type: object
      required: [startTimestamp, endTimestamp]
      properties:
        startTimestamp:
          type: integer
          format: int64
          minimum: 946684800000
          description: Start of time window (epoch ms).
        endTimestamp:
          type: integer
          format: int64
          description: End of time window (epoch ms); must exceed `startTimestamp`.
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        page:
          type: integer
          minimum: 1
          default: 1
        sortOrder:
          type: string
          enum: [asc, desc]
        filters:
          type: array
          items: { type: object, additionalProperties: true }
    Session:
      type: object
      properties:
        sessionId: { type: string }
        eventsCount: { type: integer }
        startTs: { type: integer, format: int64 }
        endTs: { type: integer, format: int64 }
    SessionListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            total: { type: integer }
            sessions:
              type: array
              items: { $ref: '#/components/schemas/Session' }
    EventsRequest:
      type: object
      required: [startTimestamp, endTimestamp]
      properties:
        startTimestamp: { type: integer, format: int64 }
        endTimestamp: { type: integer, format: int64 }
        limit: { type: integer, minimum: 1, maximum: 200, default: 50 }
        page: { type: integer, minimum: 1, default: 1 }
        sortBy: { type: string }
        sortOrder: { type: string, enum: [asc, desc] }
        filters:
          type: array
          items: { type: object, additionalProperties: true }
        columns:
          type: array
          items: { type: string }
    Event:
      type: object
      additionalProperties: true
      properties:
        type: { type: string }
        timestamp: { type: integer, format: int64 }
    EventListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            total: { type: integer }
            events:
              type: array
              items: { $ref: '#/components/schemas/Event' }
    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 }
    User:
      type: object
      additionalProperties: true
      properties:
        userId: { type: string }
        email: { type: string }
        country: { type: string }
        sessionsCount: { type: integer }
    UserResponse:
      type: object
      properties:
        data: { $ref: '#/components/schemas/User' }
    UserListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            total: { type: integer }
            users:
              type: array
              items: { $ref: '#/components/schemas/User' }
    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' }
    JobListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            total: { type: integer }
            jobs:
              type: array
              items: { $ref: '#/components/schemas/Job' }