Laurel Activities API

openapi: 3.2.0
info:
  title: Time Service Activities API
  description: ''
  version: '1'
  contact: {}
servers: []
security:
- ApiBearerAuth: []
tags:
- name: Activities
paths:
  /api/v1/activities/track-from-service:
    post:
      operationId: ActivityController_trackOneFromService_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackOneUserActivityDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimerActivityDto'
                - $ref: '#/components/schemas/TrackedActivityDto'
                - $ref: '#/components/schemas/UserActivityDto'
      summary: Creates a tracked Activity with customerId and userId returns the new Activity
      tags:
      - Activities
  /api/v1/activities/update-from-service:
    post:
      operationId: ActivityController_updateOneFromService_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOneActivityFromServiceDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimerActivityDto'
                - $ref: '#/components/schemas/TrackedActivityDto'
                - $ref: '#/components/schemas/UserActivityDto'
      summary: Updates an already-tracked Activity located by (customerId, externalId), for…
      tags:
      - Activities
  /api/v1/activities/track-from-agent:
    post:
      operationId: ActivityController_trackOne_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackOneActivityDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimerActivityDto'
                - $ref: '#/components/schemas/TrackedActivityDto'
                - $ref: '#/components/schemas/UserActivityDto'
      summary: Creates a tracked Activity for a given user
      tags:
      - Activities
  /api/v1/activities:
    post:
      operationId: ActivityController_create_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserActivityDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimerActivityDto'
                - $ref: '#/components/schemas/TrackedActivityDto'
                - $ref: '#/components/schemas/UserActivityDto'
      summary: Creates a new Activity for a given user
      tags:
      - Activities
    get:
      operationId: ActivityController_findMany_v1
      parameters:
      - name: startedBefore
        required: true
        in: query
        description: the date to get activities that their started at time is less than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: stoppedAfter
        required: true
        in: query
        description: the date to get activities that their stopped at time is greater than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: includeDeleted
        required: false
        in: query
        description: if true, include soft-deleted activities; defaults to excluding them
        schema:
          type:
          - boolean
          - 'null'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Activity'
                type: array
      summary: Returns activities within a specified time range for a given user
      tags:
      - Activities
  /api/v1/activities/dismiss-open-time:
    post:
      operationId: ActivityController_dismissOpenTime_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DismissOpenTimeRequestDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimerActivityDto'
                - $ref: '#/components/schemas/TrackedActivityDto'
                - $ref: '#/components/schemas/UserActivityDto'
      summary: Dismisses a slice of open time by creating a soft-deleted user activity that…
      tags:
      - Activities
  /api/v1/activities/timer:
    post:
      operationId: ActivityController_createTimerActivity_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTimerActivityDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimerActivityDto'
                - $ref: '#/components/schemas/TrackedActivityDto'
                - $ref: '#/components/schemas/UserActivityDto'
      summary: Creates a new Timer Activity, optionally adding it to an existing entry
      tags:
      - Activities
  /api/v2/activities:
    get:
      operationId: ActivityController_findManyActivityDtos_v2
      parameters:
      - name: userId
        required: true
        in: query
        description: the user whose entries you are searching for
        schema:
          format: objectid
          type: string
      - name: customerId
        required: true
        in: query
        description: the user's customer
        schema:
          format: objectid
          type: string
      - name: startedBefore
        required: true
        in: query
        description: the date to get activities that their started at time is less than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: stoppedAfter
        required: true
        in: query
        description: the date to get activities that their stopped at time is greater than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  oneOf:
                  - $ref: '#/components/schemas/TimerActivityDto'
                  - $ref: '#/components/schemas/TrackedActivityDto'
                  - $ref: '#/components/schemas/UserActivityDto'
                type: array
      summary: Returns activities within a specified time range for a given user
      tags:
      - Activities
  /api/v3/activities:
    get:
      operationId: ActivityController_findManyActivityDtosWithPagination_v3
      parameters:
      - name: pageSize
        required: false
        in: query
        description: max number of item in each page
        schema:
          minimum: 1
          maximum: 100
          format: int64
          type: number
      - name: cursor
        required: false
        in: query
        description: cursor to start from
        schema:
          format: objectid
          type: string
      - name: userId
        required: true
        in: query
        description: the user whose entries you are searching for
        schema:
          format: objectid
          type: string
      - name: customerId
        required: true
        in: query
        description: the user's customer
        schema:
          format: objectid
          type: string
      - name: startedBefore
        required: true
        in: query
        description: the date to get activities that their started at time is less than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: stoppedAfter
        required: true
        in: query
        description: the date to get activities that their stopped at time is greater than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: clientId
        required: false
        in: query
        description: optional client filter
        schema:
          format: objectid
          type:
          - string
          - 'null'
      - name: creationMethod
        required: false
        in: query
        description: optional activity creation method filter
        schema:
          type:
          - string
          - 'null'
          enum:
          - timer
          - tracked
          - user
      - name: category
        required: false
        in: query
        description: optional category filter matching activity.category or captureSource.activityCategory
        schema:
          type:
          - string
          - 'null'
          enum:
          - call
          - chat
          - doc
          - email
          - meeting
          - web
          - terminal
          - app
      - name: initiativeId
        required: false
        in: query
        description: optional initiative filter
        schema:
          format: objectid
          type:
          - string
          - 'null'
      - name: billingType
        required: false
        in: query
        description: optional initiative billing type filter
        schema:
          type:
          - string
          - 'null'
          enum:
          - billable
          - non-billable
      - name: isLocked
        required: false
        in: query
        description: optional lock state filter
        schema:
          type:
          - boolean
          - 'null'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/TimerActivityDto'
                      - $ref: '#/components/schemas/TrackedActivityDto'
                      - $ref: '#/components/schemas/UserActivityDto'
                    type: array
                  nextCursor:
                    type: string
                type: object
      summary: Returns paginated activities within a specified time range for a given user…
      tags:
      - Activities
  /api/v1/activities/with-metadata:
    get:
      operationId: ActivityController_findManyWithMetadata_v1
      parameters:
      - name: startedBefore
        required: true
        in: query
        description: the date to get activities that their started at time is less than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: stoppedAfter
        required: true
        in: query
        description: the date to get activities that their stopped at time is greater than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: includeDeleted
        required: false
        in: query
        description: if true, include soft-deleted activities; defaults to excluding them
        schema:
          type:
          - boolean
          - 'null'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActivityWithMetadataResponseDto'
      summary: Returns activities joined with their capture metadata (incl.
      tags:
      - Activities
  /api/v1/activities/{activityId}:
    delete:
      operationId: ActivityController_deleteActivityById_v1
      parameters:
      - name: activityId
        required: true
        in: path
        description: individual activity id
        schema:
          format: objectid
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Deletes an Activity by Id and returns the deleted Activity
      tags:
      - Activities
    patch:
      operationId: ActivityController_updateOneById_v1
      parameters:
      - name: activityId
        required: true
        in: path
        description: individual activity id
        schema:
          format: objectid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOneActivityDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimerActivityDto'
                - $ref: '#/components/schemas/TrackedActivityDto'
                - $ref: '#/components/schemas/UserActivityDto'
      summary: Updates an existing Activity for a given user
      tags:
      - Activities
  /api/v1/activities/archive:
    post:
      operationId: ActivityController_archiveActivities_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveActivitiesRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActivityResultResponseDto'
      summary: Archives (soft-deletes) many Activities by id — sets isDeleted, emits…
      tags:
      - Activities
  /api/v1/activities/unarchive:
    post:
      operationId: ActivityController_unarchiveActivities_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveActivitiesRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActivityResultResponseDto'
      summary: Unarchives (revives) many soft-deleted Activities by id — clears isDeleted…
      tags:
      - Activities
  /api/v1/activities/signal-backfill:
    post:
      operationId: ActivityController_enqueueSignalActivityBackfill_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignalActivityBackfillRequestDto'
      responses:
        '202':
          description: ''
      summary: Enqueues a background job that re-emits ActivityCreatedForSignal events for…
      tags:
      - Activities
  /api/v1/activities/copy-from/customers/{customerId}/users/{userId}:
    post:
      operationId: ActivityController_copyActivities_v1
      parameters:
      - name: customerId
        required: true
        in: path
        description: customer's id
        schema:
          format: objectid
          type: string
      - name: userId
        required: true
        in: path
        description: user's id
        schema:
          format: objectid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyActivitiesRequestDto'
      responses:
        '201':
          description: ''
      tags:
      - Activities
      summary: Activity controller copy activities v1
      x-summary-source: derived
  /api/v1/customers/{customerId}/users/{userId}/activities:
    get:
      operationId: CustomerActivityController_findMany_v1
      parameters:
      - name: customerId
        required: true
        in: path
        description: customer's id
        schema:
          format: objectid
          type: string
      - name: userId
        required: true
        in: path
        description: user's id
        schema:
          format: objectid
          type: string
      - name: startedBefore
        required: true
        in: query
        description: the date to get activities that their started at time is less than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: stoppedAfter
        required: true
        in: query
        description: the date to get activities that their stopped at time is greater than this date
        schema:
          format: iso-date-time
          example: '2022-08-12T20:44:48Z'
          type: string
      - name: includeDeleted
        required: false
        in: query
        description: if true, include soft-deleted activities; defaults to excluding them
        schema:
          type:
          - boolean
          - 'null'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  oneOf:
                  - $ref: '#/components/schemas/TimerActivity'
                  - $ref: '#/components/schemas/TrackedActivity'
                  - $ref: '#/components/schemas/UserActivity'
                type: array
      summary: Allows a requester with TimeServicePermission.CustomerAnyUserAnyActivityRead…
      tags:
      - Activities
  /api/v1/customers/{customerId}/users/{userId}/activities/{activityId}:
    get:
      operationId: CustomerActivityController_getActivity_v1
      parameters:
      - name: activityId
        required: true
        in: path
        description: individual activity id
        schema:
          format: objectid
          type: string
      - name: customerId
        required: true
        in: path
        description: customer's id
        schema:
          format: objectid
          type: string
      - name: userId
        required: true
        in: path
        description: user's id
        schema:
          format: objectid
          type: string
      - name: includeMetadata
        required: false
        in: query
        description: whether to include activity metadata in the response
        schema:
          type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityWithMetadataResponseDto'
      summary: Returns activity by activityId for a given customer and user
      tags:
      - Activities
    patch:
      operationId: CustomerActivityController_updateOne_v1
      parameters:
      - name: activityId
        required: true
        in: path
        description: individual activity id
        schema:
          format: objectid
          type: string
      - name: customerId
        required: true
        in: path
        description: customer's id
        schema:
          format: objectid
          type: string
      - name: userId
        required: true
        in: path
        description: user's id
        schema:
          format: objectid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOneCustomerActivityRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
      tags:
      - Activities
      summary: Customer activity controller update one v1
      x-summary-source: derived
components:
  schemas:
    ImageMetadata:
      type: object
      properties:
        uniqueFileName:
          type: string
          description: the unique file name of the image
        createdAt:
          type: string
          description: the creation date time of the image
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
      required:
      - uniqueFileName
      - createdAt
    UserActivity:
      type: object
      properties:
        _id:
          type: string
          description: activity's id
          format: objectid
        customerId:
          type: string
          description: id of customer who owns this activity
          format: objectid
        userId:
          type: string
          description: id of user who owns this activity
          format: objectid
        creationMethod:
          description: the creation method of the activity
          enum:
          - user
          type: string
        initiativeProps:
          description: if set, is activity's initiative, otherwise activity is unassigned
          oneOf:
          - $ref: '#/components/schemas/PmsInitiativePropsDigest'
          - $ref: '#/components/schemas/UserInitiativePropsDigest'
        isLocked:
          type: boolean
          description: if true, this activity is locked and cannot be updated
        category:
          type:
          - string
          - 'null'
          description: category of this activity, if any
        technology:
          type:
          - string
          - 'null'
          description: technology of this activity, if any
        source:
          type:
          - string
          - 'null'
          description: source of this activity (e.g. 'macos', 'windows'), if any
        mechanism:
          type:
          - string
          - 'null'
          description: mechanism of this activity (e.g. browser used to access web app), if any
        title:
          type: string
          description: activity's title
        detail:
          type: string
          description: activity's detail
        startedAt:
          type: string
          description: date and time this activity started
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        stoppedAt:
          type: string
          description: date and time this activity stopped
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        externalId:
          type:
          - string
          - 'null'
          description: activity's external id
        assignedBy:
          description: how the activity's initiative was assigned
          enum:
          - none
          - user
          - ml
          type: string
        createdAt:
          type: string
          description: date and time activity was created
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        updatedAt:
          type: string
          description: date and time activity was last updated
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        schemaVersion:
          type: string
          description: activities's schemaVersion
        threadId:
          type:
          - string
          - 'null'
          description: activity's thread id
        enhancedByAi:
          type:
          - boolean
          - 'null'
          description: indicates if this activity was enhanced by AI
        isCopiedByAdmin:
          type:
          - boolean
          - 'null'
          description: indicates if this activity was copied by admin
        isSeeded:
          type:
          - boolean
          - 'null'
          description: indicates if this activity was created via seeding
        deletedForRetentionAt:
          type:
          - string
          - 'null'
          description: date and time activity data was deleted for retention
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        isDeleted:
          type:
          - boolean
          - 'null'
          description: 'If true, this activity has been soft-deleted (e.g. it was the source of a

            split). Soft-deleted activities are excluded from the unassigned tray but

            remain restorable, which is what keeps a split reversible (undo/merge).'
        disableThreading:
          type:
          - boolean
          - 'null'
          description: if true, disables threading for this activity
        sessionIds:
          description: The session ids that were used to create this Activity
          type:
          - array
          - 'null'
          items:
            type: string
            format: objectid
        splitFromActivityId:
          type:
          - string
          - 'null'
          description: 'If set, the id of the activity this one was split from. Child activities

            created by a split carry their source''s id here; it is the sibling key and

            the seam for a future undo/merge.'
          format: objectid
      required:
      - _id
      - customerId
      - userId
      - creationMethod
      - isLocked
      - title
      - detail
      - startedAt
      - stoppedAt
      - assignedBy
      - createdAt
      - updatedAt
      - schemaVersion
    CaptureSourceDigest:
      type: object
      properties:
        _id:
          type: string
          description: capture source's id
          format: objectid
        capturingSourceType:
          type:
          - string
          - 'null'
          description: whether this source is an application or website
          enum:
          - application
          - website
        activityCategory:
          type:
          - string
          - 'null'
          description: category of the activity associated with this source
          enum:
          - call
          - chat
          - doc
          - email
          - meeting
          - web
          - terminal
          - app
        name:
          type: string
          description: Name of the app or website visible to the user
          minLength: 2
        iconId:
          type: string
          description: icon representing the capture app or website, shown in the UI
          maxLength: 512
          minLength: 1
      required:
      - _id
      - name
      - iconId
    PmsInitiativePropsDto:
      type: object
      properties:
        _id:
          type: string
          description: identifier of the initiative props
          format: objectid
        colorHex:
          type: string
          description: the hex color code for the initiative props
        tags:
          type: array
          description: array of initiative props tags
          items:
            type: string
            enum:
            - pinned
        userId:
          type: string
          description: identifier of the user who owns the initiative props
          format: objectid
        nickname:
          type:
          - string
          - 'null'
          description: the nickname assigned to this initiative by the user
      required:
      - _id
      - colorHex
      - tags
      - userId
    PmsInitiativeDto:
      type: object
      properties:
        _id:
          type: string
          description: initiative's id
          format: objectid
        billingType:
          description: initiative's billing type
          enum:
          - billable
          - non-billable
          type: string
        callSign:
          type: string
          description: a short name or abbreviation that identifies this initiative
        createdAt:
          type: string
          description: date and time this initiative was created
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        locale:
          type:
          - string
          - 'null'
          description: BCP-47 locale for this initiative (e.g. en-US, fr-CA)
          enum:
          - da-DK
          - de-DE
          - en-CA
          - en-GB
          - en-US
          - es-ES
          - es-MX
          - fi-FI
          - fr-CA
          - fr-FR
          - is-IS
          - it-IT
          - ko-KR
          - nl-NL
          - no-NO
          - pt-PT
          - sv-SE
        status:
          description: initiative's status
          enum:
          - active
          - inactive
          type: string
        unitIncrements:
          type: number
          description: unit of billing increments for this initiative
          format: double
        updatedAt:
          type: string
          description: date and time this initiative was last updated
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        description:
          type: string
          description: the full long name of the initiative
        externalId:
          type: string
          description: initiative's external id
        name:
          type: string
          description: a short name or code that identifies this initiative
        allowFrom:
          type:
          - string
          - 'null'
          description: earliest calendar date on which this initiative is valid for use (date-only, midnight UTC, inclusive)
          example: '2022-08-12'
          format: iso-date
        allowTo:
          type:
          - string
          - 'null'
          description: latest calendar date on which this initiative is valid for use (date-only, midnight UTC, inclusive)
          example: '2022-08-12'
          format: iso-date
        client:
          description: the client this initiative belongs to
          allOf:
          - $ref: '#/components/schemas/ClientDigest'
        type:
          type: string
          enum:
          - pms
        props:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/PmsInitiativePropsDto'
      required:
      - _id
      - billingType
      - callSign
      - createdAt
      - status
      - unitIncrements
      - updatedAt
      - description
      - externalId
      - name
      - client
      - type
    ActivityMetadataResponseDto:
      type: object
      properties:
        _id:
          type: string
          description: activity metadata's id
          format: objectid
        activityId:
          type: string
          description: id of activity
          format: objectid
        userId:
          type: string
          description: id of user
          format: objectid
        customerId:
          type: string
          description: id of customer
          format: objectid
        trackingSourceType:
          description: Type of tracking source
          enum:
          - website
          - application
          - system
          type: string
        operatingSystem:
          description: Operating system information
          enum:
          - windows
          - macos
          - unknown
          type: string
        operatingSystemVersion:
          type:
          - string
          - 'null'
          description: Version of the operating system
        trackedAppName:
          type:
          - string
          - 'null'
          description: Name of the process that was tracked.
        trackedAppTitle:
          type:
          - string
          - 'null'
          description: Human readable name of the tracked app
        trackedAppDisplayName:
          type:
          - string
          - 'null'
          description: Display name of the tracked app (e.g. "Microsoft Word")
        trackedAppVersion:
          type:
          - string
          - 'null'
          description: Version of the tracked application
        trackedAppCommandline:
          type:
          - string
          - 'null'
          description: Commandline of the process being tracked.
        bodyFirst1000Characters:
          type:
          - string
          - 'null'
          description: The first 1000 characters of the body of the document/email. Will be null if encrypted.
        bodyFirst1000CharactersEncrypted:
          type:
          - string
          - 'null'
          description: The encrypted first 1000 characters of the body of the document/email.
        website:
          description: Metadat

# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/laurel/refs/heads/main/openapi/laurel-activities-api-openapi.yml