> ## Documentation Index
> Fetch the complete documentation index at: https://synapse-docs.apart.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Participant Observation



## OpenAPI

````yaml /openapi.json post /v1/participant/observation/start
openapi: 3.1.0
info:
  description: Are we on the same page?
  title: Synapse
  version: 0.1.0
servers: []
security: []
paths:
  /v1/participant/observation/start:
    post:
      tags:
        - v1-observation
      summary: Start Participant Observation
      operationId: start_participant_observation_v1_participant_observation_start_post
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantObservationState'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Authentication required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: State or idempotency conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: API error
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Internal server error
      security:
        - ParticipantToken: []
components:
  schemas:
    ParticipantObservationState:
      description: Whether the camera session is offered, and where it stands.
      properties:
        available:
          title: Available
          type: boolean
        consent:
          $ref: '#/components/schemas/ConsentRequirement'
        consented:
          title: Consented
          type: boolean
        min_seconds:
          title: Min Seconds
          type: integer
        prompt_text:
          title: Prompt Text
          type: string
        show_participant_results:
          title: Show Participant Results
          type: boolean
        status:
          enum:
            - not_started
            - active
            - completed
          title: Status
          type: string
        summary:
          anyOf:
            - $ref: '#/components/schemas/ObservationSummaryPayload'
            - type: 'null'
        target_seconds:
          title: Target Seconds
          type: integer
        timeline:
          anyOf:
            - items:
                $ref: '#/components/schemas/ObservationTimelineRow'
              type: array
            - type: 'null'
          title: Timeline
        unavailable_reason:
          anyOf:
            - enum:
                - embedded
                - closed
              type: string
            - type: 'null'
          title: Unavailable Reason
      required:
        - available
        - status
        - consent
        - consented
        - target_seconds
        - min_seconds
        - prompt_text
        - show_participant_results
      title: ParticipantObservationState
      type: object
    ApiErrorResponse:
      additionalProperties: false
      properties:
        detail:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetail'
            - type: string
            - items: {}
              type: array
            - additionalProperties: true
              type: object
          title: Detail
      required:
        - detail
      title: ApiErrorResponse
      type: object
    ConsentRequirement:
      properties:
        notice_text:
          maxLength: 4000
          minLength: 1
          title: Notice Text
          type: string
        notice_version:
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,62}[A-Za-z0-9])?$
          title: Notice Version
          type: string
        purpose:
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,62}[A-Za-z0-9])?$
          title: Purpose
          type: string
      required:
        - purpose
        - notice_version
        - notice_text
      title: ConsentRequirement
      type: object
    ObservationSummaryPayload:
      additionalProperties: false
      properties:
        activity:
          $ref: '#/components/schemas/ActivityMetrics'
        analysed_s:
          maximum: 3600
          minimum: 0
          title: Analysed S
          type: number
        body:
          $ref: '#/components/schemas/BodyMetrics'
        calibration_s:
          maximum: 3600
          minimum: 0
          title: Calibration S
          type: number
        duration_s:
          maximum: 3600
          minimum: 0
          title: Duration S
          type: number
        eyes:
          $ref: '#/components/schemas/EyeMetrics'
        face:
          $ref: '#/components/schemas/FaceMetrics'
        fps:
          maximum: 240
          minimum: 0
          title: Fps
          type: number
        frames:
          maximum: 1000000
          minimum: 0
          title: Frames
          type: integer
        gaze:
          $ref: '#/components/schemas/GazeMetrics'
        hands:
          $ref: '#/components/schemas/HandMetrics'
        head:
          $ref: '#/components/schemas/HeadMetrics'
        lighting:
          $ref: '#/components/schemas/LightingMetrics'
        metrics_version:
          const: 1
          title: Metrics Version
          type: integer
        presence:
          $ref: '#/components/schemas/PresenceMetrics'
        quality:
          enum:
            - good
            - limited
            - insufficient
          title: Quality
          type: string
        quality_reasons:
          items:
            maxLength: 200
            type: string
          maxItems: 10
          title: Quality Reasons
          type: array
      required:
        - metrics_version
        - duration_s
        - analysed_s
        - calibration_s
        - frames
        - fps
        - quality
        - quality_reasons
        - presence
        - eyes
        - gaze
        - head
        - face
        - body
        - hands
        - activity
        - lighting
      title: ObservationSummaryPayload
      type: object
    ObservationTimelineRow:
      additionalProperties: false
      properties:
        blinks:
          maximum: 20
          minimum: 0
          title: Blinks
          type: integer
        face_pct:
          maximum: 100
          minimum: 0
          title: Face Pct
          type: number
        head_speed:
          maximum: 10000
          minimum: 0
          title: Head Speed
          type: number
        keys:
          maximum: 1000
          minimum: 0
          title: Keys
          type: integer
        motion:
          maximum: 1
          minimum: 0
          title: Motion
          type: number
        mouth_open_pct:
          maximum: 100
          minimum: 0
          title: Mouth Open Pct
          type: number
        on_screen_pct:
          maximum: 100
          minimum: 0
          title: On Screen Pct
          type: number
        pointer:
          maximum: 10000
          minimum: 0
          title: Pointer
          type: integer
        s:
          maximum: 3600
          minimum: 0
          title: S
          type: integer
        smile_pct:
          maximum: 100
          minimum: 0
          title: Smile Pct
          type: number
        state:
          enum:
            - active
            - still
            - away
            - hidden
          title: State
          type: string
      required:
        - s
        - state
        - face_pct
        - on_screen_pct
        - blinks
        - mouth_open_pct
        - smile_pct
        - motion
        - head_speed
        - keys
        - pointer
      title: ObservationTimelineRow
      type: object
    ErrorDetail:
      additionalProperties: false
      description: Stable structured detail returned by versioned API errors.
      properties:
        code:
          title: Code
          type: string
        context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Context
        message:
          title: Message
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
      required:
        - code
        - message
      title: ErrorDetail
      type: object
    ActivityMetrics:
      additionalProperties: false
      properties:
        active_pct:
          maximum: 100
          minimum: 0
          title: Active Pct
          type: number
        away_pct:
          maximum: 100
          minimum: 0
          title: Away Pct
          type: number
        hidden_pct:
          maximum: 100
          minimum: 0
          title: Hidden Pct
          type: number
        keys_per_min:
          maximum: 10000
          minimum: 0
          title: Keys Per Min
          type: number
        mean_motion:
          maximum: 1
          minimum: 0
          title: Mean Motion
          type: number
        pointer_per_min:
          maximum: 10000
          minimum: 0
          title: Pointer Per Min
          type: number
        still_pct:
          maximum: 100
          minimum: 0
          title: Still Pct
          type: number
      required:
        - active_pct
        - still_pct
        - away_pct
        - hidden_pct
        - mean_motion
        - keys_per_min
        - pointer_per_min
      title: ActivityMetrics
      type: object
    BodyMetrics:
      additionalProperties: false
      properties:
        available:
          title: Available
          type: boolean
        fidget_energy:
          anyOf:
            - maximum: 10000
              minimum: 0
              type: number
            - type: 'null'
          title: Fidget Energy
        posture_shifts:
          maximum: 100000
          minimum: 0
          title: Posture Shifts
          type: integer
        shoulder_tilt_deg:
          anyOf:
            - maximum: 360
              minimum: -360
              type: number
            - type: 'null'
          title: Shoulder Tilt Deg
        uprightness_change_pct:
          anyOf:
            - maximum: 1000
              minimum: -1000
              type: number
            - type: 'null'
          title: Uprightness Change Pct
      required:
        - available
        - posture_shifts
      title: BodyMetrics
      type: object
    EyeMetrics:
      additionalProperties: false
      properties:
        blinks:
          maximum: 100000
          minimum: 0
          title: Blinks
          type: integer
        blinks_per_min:
          anyOf:
            - maximum: 10000
              minimum: 0
              type: number
            - type: 'null'
          title: Blinks Per Min
        blinks_per_min_by_third:
          items:
            anyOf:
              - maximum: 10000
                minimum: 0
                type: number
              - type: 'null'
          maxItems: 3
          minItems: 3
          title: Blinks Per Min By Third
          type: array
        long_closures:
          maximum: 100000
          minimum: 0
          title: Long Closures
          type: integer
        mean_blink_ms:
          anyOf:
            - maximum: 5000
              minimum: 0
              type: integer
            - type: 'null'
          title: Mean Blink Ms
      required:
        - blinks
        - long_closures
        - blinks_per_min_by_third
      title: EyeMetrics
      type: object
    FaceMetrics:
      additionalProperties: false
      properties:
        brow_raises:
          maximum: 100000
          minimum: 0
          title: Brow Raises
          type: integer
        expression_variability:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          title: Expression Variability
        lip_press_pct:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - type: 'null'
          title: Lip Press Pct
        mouth_open_events:
          maximum: 100000
          minimum: 0
          title: Mouth Open Events
          type: integer
        mouth_open_pct:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - type: 'null'
          title: Mouth Open Pct
        smile_events:
          maximum: 100000
          minimum: 0
          title: Smile Events
          type: integer
        smile_pct:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - type: 'null'
          title: Smile Pct
        talking_like_s:
          maximum: 3600
          minimum: 0
          title: Talking Like S
          type: number
      required:
        - mouth_open_events
        - talking_like_s
        - smile_events
        - brow_raises
      title: FaceMetrics
      type: object
    GazeMetrics:
      additionalProperties: false
      properties:
        fixation_spread_deg:
          anyOf:
            - maximum: 10000
              minimum: 0
              type: number
            - type: 'null'
          title: Fixation Spread Deg
        heatmap:
          items:
            maximum: 100
            minimum: 0
            type: number
          maxItems: 9
          minItems: 9
          title: Heatmap
          type: array
        longest_off_screen_s:
          maximum: 3600
          minimum: 0
          title: Longest Off Screen S
          type: number
        mean_glance_s:
          anyOf:
            - maximum: 3600
              minimum: 0
              type: number
            - type: 'null'
          title: Mean Glance S
        off_screen_glances:
          maximum: 100000
          minimum: 0
          title: Off Screen Glances
          type: integer
        on_screen_pct:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - type: 'null'
          title: On Screen Pct
        rapid_shifts_per_min:
          anyOf:
            - maximum: 10000
              minimum: 0
              type: number
            - type: 'null'
          title: Rapid Shifts Per Min
      required:
        - off_screen_glances
        - longest_off_screen_s
        - heatmap
      title: GazeMetrics
      type: object
    HandMetrics:
      additionalProperties: false
      properties:
        available:
          title: Available
          type: boolean
        face_touches:
          maximum: 100000
          minimum: 0
          title: Face Touches
          type: integer
        visible_pct:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - type: 'null'
          title: Visible Pct
      required:
        - available
        - face_touches
      title: HandMetrics
      type: object
    HeadMetrics:
      additionalProperties: false
      properties:
        longest_still_s:
          maximum: 3600
          minimum: 0
          title: Longest Still S
          type: number
        mean_speed_deg_s:
          anyOf:
            - maximum: 10000
              minimum: 0
              type: number
            - type: 'null'
          title: Mean Speed Deg S
        nods:
          maximum: 100000
          minimum: 0
          title: Nods
          type: integer
        pitch:
          anyOf:
            - $ref: '#/components/schemas/AngleStats'
            - type: 'null'
        roll:
          anyOf:
            - $ref: '#/components/schemas/AngleStats'
            - type: 'null'
        shakes:
          maximum: 100000
          minimum: 0
          title: Shakes
          type: integer
        yaw:
          anyOf:
            - $ref: '#/components/schemas/AngleStats'
            - type: 'null'
      required:
        - nods
        - shakes
        - longest_still_s
      title: HeadMetrics
      type: object
    LightingMetrics:
      additionalProperties: false
      properties:
        label:
          enum:
            - dark
            - ok
            - bright
          title: Label
          type: string
        mean_brightness:
          maximum: 1
          minimum: 0
          title: Mean Brightness
          type: number
      required:
        - mean_brightness
        - label
      title: LightingMetrics
      type: object
    PresenceMetrics:
      additionalProperties: false
      properties:
        distance_variability_pct:
          anyOf:
            - maximum: 10000
              minimum: 0
              type: number
            - type: 'null'
          title: Distance Variability Pct
        face_pct:
          maximum: 100
          minimum: 0
          title: Face Pct
          type: number
        lean_change_pct:
          anyOf:
            - maximum: 1000
              minimum: -1000
              type: number
            - type: 'null'
          title: Lean Change Pct
        longest_absence_s:
          maximum: 3600
          minimum: 0
          title: Longest Absence S
          type: number
        multiple_faces_s:
          maximum: 3600
          minimum: 0
          title: Multiple Faces S
          type: number
      required:
        - face_pct
        - multiple_faces_s
        - longest_absence_s
      title: PresenceMetrics
      type: object
    AngleStats:
      additionalProperties: false
      properties:
        max:
          maximum: 360
          minimum: -360
          title: Max
          type: number
        mean:
          maximum: 360
          minimum: -360
          title: Mean
          type: number
        min:
          maximum: 360
          minimum: -360
          title: Min
          type: number
        sd:
          maximum: 360
          minimum: 0
          title: Sd
          type: number
      required:
        - mean
        - min
        - max
        - sd
      title: AngleStats
      type: object
  securitySchemes:
    ParticipantToken:
      bearerFormat: spt_...
      description: Short-lived token bound to one participant session.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.