Laurel Timesheets API

openapi: 3.2.0
info:
  title: Identity Service Ably Timesheets API
  description: ''
  version: '1'
  contact: {}
servers: []
security:
- ApiBearerAuth: []
tags:
- name: Timesheets
paths:
  /api/v1/timesheets:
    patch:
      operationId: TimesheetController_updateTimesheet_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTimesheetRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TimesheetInitialDto'
                - $ref: '#/components/schemas/TimesheetProcessingSuggestedInitiativesDto'
                - $ref: '#/components/schemas/TimesheetSuccessfulSuggestedInitiativesDto'
                - $ref: '#/components/schemas/TimesheetFailedSuggestedInitiativesDto'
                - $ref: '#/components/schemas/TimesheetProcessingInitiativeCategorizationDto'
                - $ref: '#/components/schemas/TimesheetSuccessfulInitiativeCategorizationDto'
                - $ref: '#/components/schemas/TimesheetFailedInitiativeCategorizationDto'
      tags:
      - Timesheets
    delete:
      operationId: TimesheetController_deleteTimesheet_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteTimesheetRequestDto'
      responses:
        '200':
          description: ''
      tags:
      - Timesheets
  /api/v1/timesheets/initiatives/suggest:
    post:
      operationId: TimesheetController_suggestInitiatives_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestInitiativesRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimesheetProcessingSuggestedInitiativesDto'
      tags:
      - Timesheets
  /api/v1/timesheets/initiatives/predict:
    post:
      operationId: TimesheetController_predictInitiatives_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PredictInitiativesRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimesheetProcessingInitiativeCategorizationDto'
      tags:
      - Timesheets
  /api/v1/timesheets/initiatives/dismiss:
    post:
      operationId: TimesheetController_dismissInitiatives_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DismissInitiativesRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimesheetSuccessfulSuggestedInitiativesDto'
      tags:
      - Timesheets
  /api/v1/timesheets/predictions/dismiss:
    post:
      operationId: TimesheetController_dismissPredictions_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DismissPredictionRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimesheetInitialDto'
      tags:
      - Timesheets
components:
  schemas:
    SharedFromResponseDto:
      type: object
      properties:
        entryId:
          type: string
          description: id of the source entry that was shared
          format: objectid
        entryUserId:
          type: string
          description: id of the user who owns the source entry
          format: objectid
        sharerId:
          type: string
          description: id of the principal who performed the share action
          format: objectid
        sharerType:
          description: capacity in which the sharer acted
          enum:
          - user
          - admin
          - delegate
          type: string
        sharedAt:
          type: string
          description: date and time the share was initiated
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        entryUserName:
          type:
          - string
          - 'null'
          description: display name of the entry owner; resolved at read-time, absent on failure
        sharerName:
          type:
          - string
          - 'null'
          description: display name of the principal who performed the share; resolved at read-time, absent on failure
      required:
      - entryId
      - entryUserId
      - sharerId
      - sharerType
      - sharedAt
    NestedActivitySource:
      type: object
      properties:
        _id:
          type: string
          description: source's id
          format: objectid
        type:
          description: type of entry source
          enum:
          - activity
          type: string
          default: activity
        creationMethod:
          description: the creation method of the activity
          enum:
          - timer
          - tracked
          - user
          type: string
        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
        clusterId:
          type:
          - string
          - 'null'
          description: activity's clusterId
        fromSuggestions:
          type:
          - boolean
          - 'null'
          description: whether this activity source was added from suggestions
        fromThemes:
          type:
          - boolean
          - 'null'
          description: whether this activity source was added from themes
        hasOverlap:
          type:
          - boolean
          - 'null'
          description: activity's overlap state
        overlapTimeInSeconds:
          type:
          - number
          - 'null'
          description: activity's overlap time in seconds
          format: int64
        threadId:
          type:
          - string
          - 'null'
          description: activity's thread id
        disableThreading:
          type:
          - boolean
          - 'null'
          description: if true, disables threading for this activity
        assignedAt:
          type:
          - string
          - 'null'
          description: 'Datetime this activity was assigned to the entry it currently belongs to.

            Unset on entries that predate the field; never back-filled.'
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
      required:
      - _id
      - type
      - creationMethod
      - title
      - detail
      - startedAt
      - stoppedAt
    TimesheetSuccessfulInitiativeCategorizationDto:
      type: object
      properties:
        date:
          type: string
          description: Target date for the timesheet
          example: '2022-08-12'
          format: iso-date
        userId:
          type: string
          description: Owner user identifier
          format: objectid
        customerId:
          type: string
          description: Owning customer identifier
          format: objectid
        status:
          description: Current workflow status
          enum:
          - successful-initiative-categorization
          type: string
        statusCreatedAt:
          type: string
          description: Timestamp the status was created
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        predictions:
          type: object
          description: Prediction results
          additionalProperties:
            additionalProperties: true
            type: object
        entries:
          type: array
          description: Entries created from categorized activities
          items:
            $ref: '#/components/schemas/EntryDto'
        dismissedPredictions:
          type:
          - object
          - 'null'
          description: Map of activity IDs to dismissed initiative IDs
          additionalProperties:
            items:
              type: string
            type: array
      required:
      - date
      - userId
      - customerId
      - status
      - statusCreatedAt
      - predictions
      - entries
    ValidationSuccessInfo:
      type: object
      properties:
        status:
          enum:
          - validation-success
          type: string
      required:
      - status
    EntryDto:
      type: object
      properties:
        _id:
          type: string
          description: entry's id
          format: objectid
        schemaVersion:
          type: string
          description: entry's schemaVersion
        customerId:
          type: string
          description: id of customer who the owner belongs to
          format: objectid
        userId:
          type: string
          description: if of user who owns the entry
          format: objectid
        enrichmentCorrelationId:
          type:
          - string
          - 'null'
          description: entry's enrichmentCorrelationId to be used by enrichment service
        statusInfo:
          description: entry's status info
          oneOf:
          - $ref: '#/components/schemas/ReleaseFailedInfo'
          - $ref: '#/components/schemas/ReleaseValidationPendingInfo'
          - $ref: '#/components/schemas/ReleasePendingInfo'
          - $ref: '#/components/schemas/ReleaseSuccessInfo'
          - $ref: '#/components/schemas/ReleaseSuccessLockedInfo'
          - $ref: '#/components/schemas/ValidationFailedInfo'
          - $ref: '#/components/schemas/ValidationPendingInfo'
          - $ref: '#/components/schemas/ValidationSuccessInfo'
        creationMethod:
          description: the creation method of the entry
          enum:
          - async
          - user
          - pms
          - shared
          type: string
        createdAsTimer:
          type:
          - boolean
          - 'null'
          description: if true, this entry was created by a user for use as a timer
        workDate:
          type: string
          description: the date the entry's work was done, this is required for released entries
          example: '2022-08-12'
          format: iso-date
        isLocked:
          type: boolean
          description: if true, this entry is locked and cannot be updated
        summary:
          type: string
          description: entry's summary
        unitIncrementCountFromSources:
          type: number
          description: sum of unit increments from this entry's sources
          format: double
        unitIncrementCountAdjustments:
          type: number
          description: user modified overrides to entry unit increment total
          format: double
        sources:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/NestedActivitySource'
            - $ref: '#/components/schemas/NestedEntrySource'
            - $ref: '#/components/schemas/NestedTimerSource'
        externalId:
          type:
          - string
          - 'null'
          description: entry's external id
        createdAt:
          type: string
          description: date and time this entry was created
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        updatedAt:
          type: string
          description: date and time this entry was updated last
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        overlapTimeInSeconds:
          type:
          - number
          - 'null'
          description: entry's duration in seconds with overlap
          format: int64
        isDeleted:
          type:
          - boolean
          - 'null'
          description: set to true if entry is soft deleted
        notes:
          type:
          - string
          - 'null'
          description: entry's notes
        splitFromActivityId:
          type:
          - string
          - 'null'
          description: 'If set, the id of the captured activity this entry was split from.

            Shared across all entries/activities produced by one split (sibling key),

            and the seam for a future undo/merge. The source activity is soft-deleted,

            so its id uniquely identifies the split.'
          format: objectid
        supersededByEntryId:
          type:
          - string
          - 'null'
          description: 'Surviving entry this one was merged into. Set so PMS sync-in leaves the

            superseded entry deleted instead of resurrecting it as a duplicate.'
          format: objectid
        releaseCount:
          type:
          - number
          - 'null'
          description: entry's release count
          format: int64
          minimum: 0
        lastSyncedAt:
          type:
          - string
          - 'null'
          description: date and time when the entry was last synced with the PMS
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        timerDurationAdjustmentInSeconds:
          type:
          - number
          - 'null'
          description: adjustment in seconds to be applied to timer duration
          format: int64
        releasedFrom:
          type:
          - string
          - 'null'
          description: source of the release request
          enum:
          - time-control
          - timesheet
        complianceRules:
          description: entry's compliance rules
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ComplianceRule'
        deletedForRetentionAt:
          type:
          - string
          - 'null'
          description: date and time entry data was deleted for retention
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        timerCarryover:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/EntryTimerCarryover'
        autoStoppedReason:
          type:
          - string
          - 'null'
          description: 'Indicates the reason this entry''s timer was automatically stopped by the

            system (as opposed to being stopped by the user). `null`/undefined for

            entries whose timers were stopped manually or by the overnight job.'
          enum:
          - twelve_hour_limit
        autostopDismissedAt:
          type:
          - string
          - 'null'
          description: 'Set when the user explicitly dismisses the auto-stop strip via the × button.

            Once set, the strip is never re-shown for this entry.'
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        timezoneAtCreation:
          type:
          - string
          - 'null'
          description: 'The user''s IANA timezone at the time this entry was created.

            Immutable after creation. Null when the user had no timezone configured.'
        isShared:
          type:
          - boolean
          - 'null'
          description: 'Set to `true` when the entry has been shared with at least one recipient.

            Written synchronously by the share endpoint; never reset.

            Absent on entries that pre-date the sharing feature or have never been shared.'
        externalSources:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExternalSource'
        workCodes:
          description: all of the codes assigned to the entry
          type: array
          items:
            $ref: '#/components/schemas/CodeAssignment'
        initiative:
          description: entry's initiative information
          oneOf:
          - $ref: '#/components/schemas/UserInitiativeDto'
          - $ref: '#/components/schemas/PmsInitiativeDto'
        sharedFrom:
          description: 'Present only on recipient-side copies. Contains the source entry context

            and display names resolved at read-time via identity-service.'
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/SharedFromResponseDto'
      required:
      - _id
      - schemaVersion
      - customerId
      - userId
      - statusInfo
      - creationMethod
      - workDate
      - isLocked
      - summary
      - unitIncrementCountFromSources
      - unitIncrementCountAdjustments
      - sources
      - createdAt
      - updatedAt
      - workCodes
      - initiative
    UserInitiativePropsDto:
      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
      required:
      - _id
      - colorHex
      - tags
      - userId
    ReleaseValidationPendingInfo:
      type: object
      properties:
        status:
          enum:
          - release-validation-pending
          type: string
        releasePendedAt:
          type: string
          description: date and time entry was changed to release pending
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        releasePendedBy:
          type: string
          description: the identifier of the user who change the entry to release pending
          format: objectid
      required:
      - status
      - releasePendedAt
      - releasePendedBy
    EntryValidationError:
      type: object
      properties:
        errorCode:
          description: the entry validation error code
          enum:
          - cannot-have-running-timer
          - cannot-release-zero-increment
          - cannot-release-negative-increment
          - cannot-release-billable-future-work
          - cannot-release-non-billable-future-work
          - cannot-release-with-user-initiative
          - cannot-release-with-inactive-initiative
          - code-type-is-required
          - summary-is-required
          - cannot-have-blocked-compliance-rule
          - cannot-exceed-twenty-four-hours
          - entry-date-restricted-no-release
          - entry-date-restricted-no-create
          - timekeeper-not-in-working-list
          - exceeds-twenty-four-hours-daily-limit
          type: string
      required:
      - errorCode
    DismissPredictionRequestDto:
      type: object
      properties:
        userId:
          type: string
          description: Owner user identifier
          format: objectid
        customerId:
          type: string
          description: Owning customer identifier
          format: objectid
        date:
          type: string
          description: Target date for the timesheet
          example: '2022-08-12'
          format: iso-date
        activityId:
          type: string
          description: Activity identifier
          format: objectid
        initiativeId:
          type: string
          description: Initiative identifier to dismiss for this activity
          format: objectid
      required:
      - userId
      - customerId
      - date
      - activityId
      - initiativeId
    ComplianceRule:
      type: object
      properties:
        ruleKey:
          type: string
          description: rule key
        description:
          type:
          - string
          - 'null'
          description: rule description
        enforcementLevel:
          description: enforcement level
          enum:
          - block
          - acknowledge
          - warn
          - 'off'
          type: string
      required:
      - ruleKey
      - enforcementLevel
    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
    CodeTypeDigest:
      type: object
      properties:
        _id:
          type: string
          description: code type's id
          format: objectid
        externalId:
          type: string
          description: code type's external id
        name:
          type: string
          description: code type's name
        semanticType:
          type:
          - string
          - 'null'
          description: code type's semantic type
          enum:
          - action
          - activity
          - location
          - phase
          - task
        orderingSequence:
          type:
          - string
          - 'null'
          description: ordering sequence for UI sorting (alphanumeric)
      required:
      - _id
      - externalId
      - name
    TimesheetProcessingInitiativeCategorizationDto:
      type: object
      properties:
        date:
          type: string
          description: Target date for the timesheet
          example: '2022-08-12'
          format: iso-date
        userId:
          type: string
          description: Owner user identifier
          format: objectid
        customerId:
          type: string
          description: Owning customer identifier
          format: objectid
        status:
          description: Current workflow status
          enum:
          - processing-initiative-categorization
          type: string
        statusCreatedAt:
          type: string
          description: Timestamp the status was created
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        activityIds:
          description: Activities included in categorization
          type: array
          items:
            type: string
            format: objectid
        initiativeIds:
          description: Initiatives included in categorization
          type: array
          items:
            type: string
            format: objectid
        model:
          type: string
          description: Prediction model identifier
        parameters:
          type: object
          description: Prediction parameters
          additionalProperties: true
      required:
      - date
      - userId
      - customerId
      - status
      - statusCreatedAt
      - activityIds
      - initiativeIds
      - model
      - parameters
    ValidationFailedInfo:
      type: object
      properties:
        status:
          enum:
          - validation-failed
          type: string
        errors:
          description: list of errors
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/EntryValidationError'
      required:
      - status
      - errors
    EntryTimerCarryover:
      type: object
      properties:
        originId:
          type: string
          format: objectid
      required:
      - originId
    TimesheetProcessingSuggestedInitiativesDto:
      type: object
      properties:
        date:
          type: string
          description: Target date for the timesheet
          example: '2022-08-12'
          format: iso-date
        userId:
          type: string
          description: Owner user identifier
          format: objectid
        customerId:
          type: string
          description: Owning customer identifier
          format: objectid
        status:
          description: Current workflow status
          enum:
          - processing-suggested-initiatives
          type: string
        statusCreatedAt:
          type: string
          description: Timestamp the status was created
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
      required:
      - date
      - userId
      - customerId
      - status
      - statusCreatedAt
    ReleasePendingInfo:
      type: object
      properties:
        status:
          enum:
          - release-pending
          type: string
        releasePendedAt:
          type: string
          description: date and time entry was changed to release pending
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
        releasePendedBy:
          type: string
          description: the identifier of the user who change the entry to release pending
          format: objectid
      required:
      - status
      - releasePendedAt
      - releasePendedBy
    CodeDigest:
      type: object
      properties:
        _id:
          type: string
          description: code's id
          format: objectid
        externalId:
          type: string
          description: code's external id
        name:
          type: string
          description: code's name
        description:
          type: string
          description: code's description, can be empty
        type:
          description: code's type
          allOf:
          - $ref: '#/components/schemas/CodeTypeDigest'
      required:
      - _id
      - externalId
      - name
      - description
      - type
    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
    UserInitiativeDto:
      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
        name:
          type: string
          description: a name that identifies this initiative for the user
        type:
          type: string
          enum:
          - user
        props:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/UserInitiativePropsDto'
      required:
      - _id
      - billingType
      - callSign
      - createdAt
      - status
      - unitIncrements
      - updatedAt
      - name
      - type
    ExternalSource:
      type: object
      properties:
        sourceSystem:
          enum:
          - 3e
          - workday
          type: string
        externalId:
          type: string
        linkedAt:
          type: string
          example: '2022-08-12T20:44:48Z'
          format: iso-date-time
      required:
      - sourceSystem
      - externalId
      - linkedAt
    ClientDigest:
      type: object
      properties:
        _id:
          type: string
          description: client's id
          format: objectid
        externalId:
  

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