Reclaim.ai Focus Planner Actions API

openapi: 3.2.0
info:
  title: Reclaim Focus Planner Actions API
  description: Reclaim's awesome API
  contact:
    name: Reclaim.ai Inc.
    url: http://reclaim.ai
    email: info@reclaim.ai
  license:
    name: Reclaim 9.9
    url: http://reclaim.ai
  version: '0.1'
tags:
- name: focus-planner-actions
paths:
  /api/focus/planner/{calendarId}/{eventId}/lock:
    post:
      tags:
      - focus-planner-actions
      operationId: lockFocusInstance
      parameters:
      - name: calendarId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: eventId
        in: path
        required: true
        schema:
          type: string
      - name: notificationKey
        in: query
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: lockFocusInstance 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FocusPlannerActionResult'
      security:
      - Authorization: []
      summary: Lock focus instance
      x-summary-source: derived
  /api/focus/planner/{calendarId}/{eventId}/move:
    post:
      tags:
      - focus-planner-actions
      operationId: moveFocusInstance
      parameters:
      - name: calendarId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: eventId
        in: path
        required: true
        schema:
          type: string
      - name: start
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: notificationKey
        in: query
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: moveFocusInstance 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FocusPlannerActionResult'
      security:
      - Authorization: []
      summary: Move focus instance
      x-summary-source: derived
  /api/focus/planner/{calendarId}/{eventId}/reschedule:
    post:
      tags:
      - focus-planner-actions
      operationId: rescheduleFocusInstance
      parameters:
      - name: calendarId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: eventId
        in: path
        required: true
        schema:
          type: string
      - name: snoozeOption
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/SnoozeOption'
      - name: notificationKey
        in: query
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: rescheduleFocusInstance 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FocusPlannerActionResult'
      security:
      - Authorization: []
      summary: Reschedule focus instance
      x-summary-source: derived
  /api/focus/planner/{calendarId}/{eventId}/unlock:
    post:
      tags:
      - focus-planner-actions
      operationId: unlockFocusInstance
      parameters:
      - name: calendarId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: eventId
        in: path
        required: true
        schema:
          type: string
      - name: notificationKey
        in: query
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: unlockFocusInstance 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FocusPlannerActionResult'
      security:
      - Authorization: []
      summary: Unlock focus instance
      x-summary-source: derived
components:
  schemas:
    SnoozeOption:
      type: string
      enum:
      - FROM_NOW_15M
      - FROM_NOW_30M
      - FROM_NOW_1H
      - FROM_NOW_2H
      - FROM_NOW_4H
      - TOMORROW
      - IN_TWO_DAYS
      - NEXT_WEEK
    AssistStatus:
      type: string
      enum:
      - CONTROLLED
      - RELEASED
      - ARCHIVED
    Colorized:
      type: object
      properties:
        color:
          $ref: '#/components/schemas/EventColor'
    PlatformEventType:
      type: string
      enum:
      - DEFAULT
      - OUT_OF_OFFICE
      - FROM_MAIL
      - WORKING_LOCATION
      - FOCUS_TIME
      - BIRTHDAY
    EventAttendee:
      required:
      - email
      type: object
      properties:
        email:
          type: string
        self:
          type:
          - boolean
          - 'null'
        displayName:
          type:
          - string
          - 'null'
        responseStatus:
          allOf:
          - $ref: '#/components/schemas/ResponseStatus'
        comment:
          type:
          - string
          - 'null'
        optional:
          type:
          - boolean
          - 'null'
        additionalGuests:
          type:
          - integer
          - 'null'
          format: int32
        organizer:
          type:
          - boolean
          - 'null'
        resource:
          type:
          - boolean
          - 'null'
    GoogleCalendarEventMetadata:
      required:
      - guestsCanInviteOthers
      - guestsCanModify
      - guestsCanSeeOtherGuests
      type: object
      properties:
        guestsCanModify:
          type: boolean
        guestsCanInviteOthers:
          type: boolean
        guestsCanSeeOtherGuests:
          type: boolean
    FocusType:
      type: string
      enum:
      - FOCUS_TIME
    AssistPolicyOverride:
      required:
      - durationMax
      - durationMin
      - forceDefend
      - idealTime
      - windowEnd
      - windowStart
      type: object
      properties:
        windowStart:
          type: string
          format: partial-time
        idealTime:
          type: string
          format: partial-time
        windowEnd:
          type: string
          format: partial-time
        durationMin:
          type: integer
          format: int32
        durationMax:
          type: integer
          format: int32
        forceDefend:
          type: boolean
    EventStatus:
      type: string
      enum:
      - PUBLISHED
      - CANCELLED
    ResponseStatus:
      type: string
      enum:
      - DECLINED
      - NEEDS_ACTION
      - TENTATIVE
      - ACCEPTED
      - UNKNOWN
    FocusTimeBalloonFillType:
      type: string
      enum:
      - BALLOON_FILL_NORMAL
      - BALLOON_FILL_MAXIMIZE_DURATIONS
    MeetingType:
      type: string
      enum:
      - DIRECT_11
      - PEER_11
      - SKIP_11
      - XFUNC_11
      - OTHER_11
      - TEAM
      - XFUNC_TEAM
      - EXEC
      - SKIP_TEAM
      - ALL_HANDS
      - ONBOARDING_TRAINING
      - COMPANY_EVENT
      - BOARD_MEETING
      - OTHER_STAFF
      - DEAL_REVIEW
      - EXECUTION_REVIEW
      - DEMO
      - PLANNING_MEETING
      - RETRO
      - EMERGENCY
      - PEOPLE_REVIEW
      - OTHER_OP
      - ROADMAP
      - CUST_MEETING
      - CUST_RESEARCH
      - CUST_URGENT
      - RECRUIT_SCREEN
      - OTHER_EXTERNAL
      - DESIGN_BRAIN
      - TECH_REVIEW
      - KICKOFF
      - REQ_BRAIN
      - OTHER_IDEATION
      - UNKNOWN
    FocusTimeSchedulingTypeV2:
      type: string
      enum:
      - BALLOON_FILL
      - CIRCUIT_BREAKER
    EventType:
      type: string
      enum:
      - MEETING
      - WORK
      - LOGISTICS
      - PERSONAL
    CircuitBreakerView:
      required:
      - availableChunksInDayThreshold
      - availableChunksInWeekThreshold
      - type
      type: object
      properties:
        availableChunksInWeekThreshold:
          type: integer
          format: int32
        availableChunksInDayThreshold:
          type: integer
          format: int32
        type:
          $ref: '#/components/schemas/FocusTimeCircuitBreakerType'
        minDurationChunks:
          type:
          - integer
          - 'null'
          format: int32
    UserFocusSettingsStatus:
      type: string
      enum:
      - ACTIVE
      - DISABLED
      - CALENDAR_NOT_FOUND
      - CALENDAR_NOT_VALID
      - CALENDAR_NOT_CONNECTED
      - CALENDAR_NOT_WRITABLE
      - INACTIVE_MULTI_CONNECTED_CALENDAR
    MergeDetails.EventType:
      type: string
      enum:
      - ORGANIZER_EVENT
      - ATTENDEE_EVENT
      - SYNC_EVENT
    LockState:
      type: string
      enum:
      - MANUALLY_LOCKED
      - ADJUSTED
      - UPCOMING_WINDOW
      - MANUALLY_UNLOCKED
      - DELETED
      - DECLINED
      - IN_THE_PAST
    FocusTimeSettingsView:
      required:
      - schedulingType
      - schedulingTypeV2
      type: object
      properties:
        schedulingType:
          $ref: '#/components/schemas/FocusTimeSchedulingType'
        schedulingTypeV2:
          $ref: '#/components/schemas/FocusTimeSchedulingTypeV2'
        balloonFill:
          allOf:
          - $ref: '#/components/schemas/BalloonFillView'
        circuitBreaker:
          allOf:
          - $ref: '#/components/schemas/CircuitBreakerView'
    FocusTimeSchedulingType:
      type: string
      deprecated: true
      enum:
      - BALLOON_FILL
      - BALLOON_FILL_MAXIMIZE_DURATIONS
      - CIRCUIT_BREAKER_WEEK_LEVEL
      - CIRCUIT_BREAKER_DAY_LEVEL
      - CIRCUIT_BREAKER_WEEK_AND_DAY_LEVEL
    MergeDetails:
      required:
      - key
      - sourceCalendarId
      - sourceReclaimCalendarId
      - type
      type: object
      properties:
        key:
          type: string
        type:
          $ref: '#/components/schemas/MergeDetails.EventType'
        sourceCalendarId:
          type:
          - string
          - 'null'
        sourceReclaimCalendarId:
          type:
          - integer
          - 'null'
          format: int64
    FocusTimeCircuitBreakerType:
      type: string
      enum:
      - WEEK
      - DAY
      - WEEK_AND_DAY
    Event:
      required:
      - allocatedTimeChunks
      - assist
      - calendarId
      - categoryOverride
      - description
      - etag
      - eventEnd
      - eventId
      - eventStart
      - key
      - location
      - meetingType
      - organizer
      - priority
      - recurrence
      - recurrenceMax
      - recurringEventId
      - requiresTravel
      - rsvpStatus
      - sourceDetails
      - status
      - subType
      - timeChunks
      - title
      - titleSeenByOthers
      - type
      - updated
      type: object
      properties:
        googleMetadata:
          description: Returns Google Calendar-specific metadata that doesn't fit into a common event model, but that services and UI might be interested in introspecting. If the event isn't a Google Calendar event, this method will return an empty value.
          allOf:
          - $ref: '#/components/schemas/GoogleCalendarEventMetadata'
        schedulingLinkId:
          type:
          - string
          - 'null'
        schedulingLinkMeetingId:
          type:
          - string
          - 'null'
        underAssistControl:
          type: boolean
        assist:
          $ref: '#/components/schemas/AssistDetails'
        reclaimEventType:
          $ref: '#/components/schemas/ReclaimEventType'
        personalSync:
          type: boolean
        reclaimManaged:
          type: boolean
          description: Reclaim likely created and manages this event but important to note that this event might not be organized by this user so very important to check also [isReclaimManagedAndSelfOrganized](#isReclaimManagedAndSelfOrganized) if the calling class would do something different for a Reclaim managed event if the person attached to this event is an attendee, rather than the organizer.
        reclaimManagedAndSelfOrganized:
          type: boolean
          description: Important to note that there are Reclaim "managed" events like smart meetings and scheduling link events where the user associated with the event is *not* the organizer, and as a result, we may need to do things like color coding or scoring.
        eventId:
          type: string
        calendarId:
          type: integer
          format: int64
        key:
          $ref: '#/components/schemas/EventKey'
        priority:
          $ref: '#/components/schemas/PriorityLevel'
        prioritySource:
          allOf:
          - $ref: '#/components/schemas/PrioritySource'
        title:
          type: string
        titleSeenByOthers:
          type: string
        location:
          type: string
        onlineMeetingUrlRaw:
          type: string
        onlineMeetingUrl:
          type: string
        description:
          type: string
        descriptionOmitted:
          type: boolean
        titleTruncated:
          type: boolean
        sourceDetails:
          $ref: '#/components/schemas/EventSourceDetails'
        mergeDetails:
          $ref: '#/components/schemas/MergeDetails'
        status:
          $ref: '#/components/schemas/EventStatus'
        published:
          type: boolean
        type:
          $ref: '#/components/schemas/EventType'
        subType:
          $ref: '#/components/schemas/EventSubType'
        meetingType:
          $ref: '#/components/schemas/MeetingType'
        categoryOverride:
          $ref: '#/components/schemas/EventCategory'
        eventStart:
          type: string
          format: date-time
        eventEnd:
          type: string
          format: date-time
        timeChunks:
          type: integer
          format: int32
        allocatedTimeChunks:
          type: integer
          format: int32
        recurringEventId:
          type: string
        updated:
          type: string
          format: date-time
        recurringException:
          type: boolean
        recurrence:
          type: string
        recurrenceMax:
          type: string
          format: date-time
        recurring:
          type: boolean
        recurringInstance:
          type: boolean
        private:
          type: boolean
        public:
          type: boolean
        color:
          $ref: '#/components/schemas/EventColor'
        organizer:
          type: string
        numAttendees:
          type: integer
          format: int32
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/EventAttendee'
        free:
          type: boolean
        category:
          $ref: '#/components/schemas/EventCategory'
        rsvpStatus:
          $ref: '#/components/schemas/EventResponseStatus'
        requiresTravel:
          type: boolean
        conferenceCall:
          type: boolean
        etag:
          type:
          - string
          - 'null'
        smartSeriesId:
          type:
          - integer
          - 'null'
          format: int64
        sourceEventType:
          $ref: '#/components/schemas/PlatformEventType'
        version:
          type: string
        manuallyStarted:
          type: boolean
        inheritedExternalId:
          type:
          - string
          - 'null'
          description: 'Retrieves the inherited external ID for the event. The inherited external ID is used in scenarios where a non-pipeline user is invited to an event created by Reclaim on a pipeline user''s Microsoft calendar.


            In such cases, the inherited external ID represents the "external-id" of the organizer''s event,

            which is crucial for supporting event ID parsing. This mechanism ensures compatibility with Reclaim''s

            existing logic for detecting and parsing event information, even when the event ID cannot be directly

            relied upon (e.g., in Microsoft calendars).'
    PrioritySource:
      type: string
      enum:
      - MANUAL
      - AI
      - RULES
    FocusPlannerActionResult:
      required:
      - events
      - focusSettings
      - userInfoMessage
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        focusSettings:
          $ref: '#/components/schemas/UserFocusSettingsView'
        userInfoMessage:
          type: string
    AssistType:
      type: string
      enum:
      - TASK
      - CUSTOM_DAILY
      - CATCHUP_AM
      - CATCHUP_PM
      - LUNCH
      - FOCUS
      - TRAVEL_PRE
      - TRAVEL_POST
      - CONBUF
      - SMART_HABIT
      - SMART_MEETING
      - RECLAIM_FOCUS
    FocusVisibility:
      type: string
      enum:
      - DEFAULT
      - PRIVATE
      - PUBLIC
    EventCategory:
      $ref: '#/components/schemas/Colorized'
    EventColor:
      type: string
      enum:
      - NONE
      - LAVENDER
      - SAGE
      - GRAPE
      - FLAMINGO
      - BANANA
      - TANGERINE
      - PEACOCK
      - GRAPHITE
      - BLUEBERRY
      - BASIL
      - TOMATO
    EventSubType:
      type: string
      enum:
      - ONE_ON_ONE
      - STAFF_MEETING
      - OP_REVIEW
      - EXTERNAL
      - IDEATION
      - FOCUS
      - PRODUCTIVITY
      - TRAVEL
      - FLIGHT
      - TRAIN
      - RECLAIM
      - VACATION
      - HEALTH
      - ERRAND
      - OTHER_PERSONAL
      - UNKNOWN
    UserFocusSettingsView:
      required:
      - autoDecline
      - description
      - enabled
      - focusType
      - id
      - status
      - timeSchemeId
      - title
      - visibility
      type: object
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        description:
          type: string
        focusType:
          $ref: '#/components/schemas/FocusType'
        focusTimeSettings:
          allOf:
          - $ref: '#/components/schemas/FocusTimeSettingsView'
        enabled:
          type: boolean
        timeSchemeId:
          type: string
        status:
          $ref: '#/components/schemas/UserFocusSettingsStatus'
        autoDecline:
          type: boolean
        autoDeclineText:
          type:
          - string
          - 'null'
        calendarId:
          type:
          - integer
          - 'null'
          format: int64
        visibility:
          $ref: '#/components/schemas/FocusVisibility'
    EventKey:
      required:
      - calendarId
      - eventId
      type: object
      properties:
        eventId:
          type: string
        calendarId:
          type: integer
          format: int64
    ReclaimEventType:
      type: string
      enum:
      - USER
      - SYNC
      - HABIT_ASSIGNMENT
      - SMART_HABIT
      - ONE_ON_ONE_ASSIGNMENT
      - SMART_MEETING
      - TASK_ASSIGNMENT
      - CONF_BUFFER
      - TRAVEL_BUFFER
      - SCHEDULING_LINK_MEETING
      - UNKNOWN
      - FOCUS
    BalloonFillView:
      required:
      - targetChunksPerWeek
      - type
      type: object
      properties:
        targetChunksPerWeek:
          type: integer
          format: int32
        idealChunksPerDay:
          type:
          - integer
          - 'null'
          format: int32
        maxChunksPerDay:
          type:
          - integer
          - 'null'
          format: int32
        minDurationChunks:
          type:
          - integer
          - 'null'
          format: int32
        maxDurationChunks:
          type:
          - integer
          - 'null'
          format: int32
        type:
          $ref: '#/components/schemas/FocusTimeBalloonFillType'
    PriorityLevel:
      type: string
      enum:
      - P1
      - P2
      - P3
      - P4
      - PRIORITIZE
      - DEFAULT
      x-deprecated:
      - PRIORITIZE
      - DEFAULT
    EventResponseStatus:
      type: string
      enum:
      - None
      - Organizer
      - Accepted
      - Declined
      - TentativelyAccepted
      - NotResponded
      x-enum-varnames:
      - None
      - Organizer
      - Accepted
      - Declined
      - TentativelyAccepted
      - NotResponded
    AssistDetails:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AssistType'
        customHabit:
          type: boolean
        smartSeries:
          type: boolean
        focus:
          type: boolean
        habitOrTask:
          type: boolean
        task:
          type: boolean
        conferenceBuffer:
          type: boolean
        travelBuffer:
          type: boolean
        status:
          $ref: '#/components/schemas/AssistStatus'
        travelNewEventId:
          type:
          - string
          - 'null'
          description: The source event id for a travel assist event.
        conferenceEventId:
          type:
          - string
          - 'null'
          description: The source event id for a conference (decompression time) event.
        lastControlledUpdate:
          type: string
          format: date-time
        lastControlledHash:
          type: integer
          format: int32
        defended:
          type: boolean
        pinned:
          type: boolean
        lockState:
          allOf:
          - $ref: '#/components/schemas/LockState'
        dailyHabitId:
          type:
          - integer
          - 'null'
          format: int64
        seriesLineageId:
          type:
          - integer
          - 'null'
          format: int64
        seriesId:
          type:
          - integer
          - 'null'
          format: int64
        taskId:
          type:
          - integer
          - 'null'
          format: int64
        taskIndex:
          type:
          - integer
          - 'null'
          format: int32
        policyOverride:
          allOf:
          - $ref: '#/components/schemas/AssistPolicyOverride'
        lastManualAdjustment:
          type: string
          format: date-time
        recurringAssignmentType:
          $ref: '#/components/schemas/RecurringAssignmentType'
        eventType:
          $ref: '#/components/schemas/ReclaimEventType'
        manuallyStarted:
          type: boolean
        focusId:
          type:
          - integer
          - 'null'
          format: int64
        assistReferenceValid:
          type: boolean
      description: This entity maps to the assist_events table.
    EventSourceDetails:
      required:
      - base64Id
      - calendarId
      - description
      - etag
      - eventId
      - eventKey
      - title
      - url
      - writable
      type: object
      properties:
        writable:
          type: boolean
        calendarId:
          type: integer
          format: int64
        eventId:
          type: string
        etag:
          type: string
        eventKey:
          $ref: '#/components/schemas/EventKey'
        base64Id:
          type: string
        url:
          type: string
        title:
          type: string
        description:
          type: string
    RecurringAssignmentType:
      type: string
      enum:
      - ONE_ON_ONE
      - DAILY_HABIT
      - TASK
  securitySchemes:
    Authorization:
      type: oauth2