openapi: 3.1.0
info:
  title: YAS SDK
  version: 0.2.0
  description: >
    Partner REST for robots. Asset, maps, events, status, components, tasks,
    maintenance, media, and samples. The server key never enters the app. All
    robot routes are beta.
servers:
  - url: https://api.example.yas
    description: YAS API.
tags:
  - name: Robots
  - name: Raw
paths:
  /v1/robots/{robotId}:
    put:
      tags:
        - Robots
      operationId: upsertRobot
      summary: Create or replace robot (beta)
      x-beta: true
      description: >
        Beta. Create or replace a robot with the server key. Send `partnerId`,
        `schemaVersion`, `sourceSystem`, `model`, and `serial`. A later call
        replaces the stored body. Leave an optional field out and it is cleared.
        `updatedAt` is ISO-8601 UTC.
      parameters:
        - name: robotId
          in: path
          required: true
          schema:
            type: string
          example: rbt_example
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotUpsertRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              model: M1
              serial: SN-1001
              vin: VIN-1001
              firmwareVersion: 1.4.2
      responses:
        "200":
          description: Robot stored. A later call replaces it.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotWriteResponse"
              example:
                robotId: rbt_example
                updatedAt: 2026-10-15T10:00:00.000Z
        "400":
          description: A required field is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
  /v1/robots/maps:
    post:
      tags:
        - Robots
      operationId: postRobotMap
      summary: Mint robot map upload (beta)
      x-beta: true
      description: >
        Beta. Mint a URL for one map with the server key. Send partnerId,
        schemaVersion, sourceSystem,

        robotId, mapId, unitM, contentType, and byteLength. The robot must
        already exist for this

        partner. unitM must be 1. contentType is occupancy_grid or point_cloud;
        PUT the bytes with

        Content-Type: application/octet-stream. byteLength is 1 to 52428800 (50
        MiB), or the lower

        configured Storage limit. A second mint for the same partnerId, robotId
        and mapId replaces only

        the open upload. The live map stays unchanged until complete succeeds.
        Replaced Storage objects

        are retired safely after their credentials expire. contentSha256 and
        pointCount are stored but

        not verified.


        Upload credentials last two hours; expiresAt is the credential deadline
        in ISO-8601 UTC.

        Complete within 24 hours of minting. The bytes enter private Storage on
        upload and become ready

        only after complete verifies their length and type. Storage does not
        bind the signed URL to

        byteLength; a mismatched file may be stored temporarily but cannot
        become ready. Uploads cannot

        overwrite an object. Mint a new upload after invalid content. Each
        partner may have at most 10

        outstanding upload reservations totaling at most 1 GiB across maps and
        media. Each reservation

        uses the effective bucket limit, including abandoned uploads until safe
        cleanup. Revoking Robots

        access immediately blocks mint and complete, but an issued Storage
        credential may remain usable

        until it expires. Uncompleted objects are cleaned after upload
        credentials and sessions expire;

        ready media and the current live map are retained.


        contentBase64 is not accepted and returns 400 invalid_body. Send
        byteLength, upload the

        bytes to the signed URL, then call complete.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotMapMintRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              robotId: rbt_example
              mapId: map_1
              mapVersion: 2026-10
              unitM: 1
              contentType: occupancy_grid
              byteLength: 1048576
      responses:
        "200":
          description: Signed upload URL minted. The signed URL lasts two hours; complete
            within 24 hours of minting.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotMapMintResponse"
              example:
                robotId: rbt_example
                mapId: map_1
                uploadUrl: https://upload.example.yas/maps/map_1
                objectKey: partners/partner/robot/rbt_example/map/map_1/20261015T100000123Z
                expiresAt: 2026-10-15T12:00:00.000Z
                byteLength: 1048576
        "400":
          description: A required field is missing or invalid, the content type is
            unsupported, or contentBase64 was sent. No upload is created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "413":
          description: The declared size exceeds the effective Storage limit (at most
            52428800 bytes).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: payload_too_large
        "429":
          description: Outstanding upload reservations reached the partner limit. Retry
            after cleanup releases capacity.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: upload_quota_exceeded
        "503":
          description: Storage or its required configuration is unavailable. Retry after
            the Retry-After interval.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: unavailable
  /v1/robots/maps/complete:
    post:
      tags:
        - Robots
      operationId: completeRobotMap
      summary: Complete robot map (beta)
      x-beta: true
      description: "Beta. Complete makes the map live. Send `partnerId`,
        `schemaVersion`, `sourceSystem`, `robotId`, and `mapId`. PUT the bytes
        to the minted URL first. An unknown `robotId` or map is 404. The first
        complete returns `status` `ready` and `updatedAt` as ISO-8601 UTC. A
        repeat when the map is already live is 200 with `status` `ready` and no
        `updatedAt`. Complete within 24 hours of minting. A missing upload is
        409 upload_incomplete; a size or type mismatch is 422 invalid_media. A
        credential may expire before the completion deadline: an already
        uploaded valid object can still complete. Mint again for invalid content
        because objects cannot be overwritten."
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotMapCompleteRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              robotId: rbt_example
              mapId: map_1
      responses:
        "200":
          description: >
            Map is live. `status` is `ready`. `updatedAt` is ISO-8601 UTC on the
            first complete. A repeat when the map is already live is 200 with
            `status` `ready` and no `updatedAt`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotMapCompleteResponse"
              example:
                robotId: rbt_example
                mapId: map_1
                status: ready
                updatedAt: 2026-10-15T10:00:00.000Z
        "400":
          description: A required field is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId` or map. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "409":
          description: No completed object is available yet. Upload before the credential
            expires and retry complete.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: upload_incomplete
        "410":
          description: The 24-hour completion deadline has expired. Mint again; a previous
            ready map is unchanged.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: upload_expired
        "422":
          description: The uploaded object does not match its declared size or type. Mint
            again and upload valid bytes; the object cannot be overwritten.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_media
        "503":
          description: Storage or its required configuration is unavailable. Retry after
            the Retry-After interval.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: unavailable
  /v1/robots/events:
    post:
      tags:
        - Robots
      operationId: postRobotEvents
      summary: Post robot events (beta)
      x-beta: true
      description: >
        Beta. Post 1 to 500 events with the server key. Each event needs
        `robotId`, `eventId`, `eventStart`, `timezone`, `type`, and
        `nativeCode`. `type` is `mode_change`, `alarm`, `intervention`,
        `navigation`, `incident`, `task_state`, `software_change`, or
        `proximity`. For a `proximity` event, send `distanceM`, `objectMotion`,
        and `subject` when you know them. The robot must already exist for this
        `partnerId`. An unknown `robotId` is 404; nothing in the call is stored.
        An empty list, a missing field, or an unknown `type`, `objectMotion`,
        `subject`, `resolution`, or `consequence` is 400. More than 500 events
        is 413. A repeated `partnerId`, `robotId`, and `eventId` keeps the first
        body. Fields for another `type` are stored and are not a 400. `accepted`
        is new rows. `duplicates` is rows already stored. `eventIds` lists every
        id in order. `accepted` plus `duplicates` equals the number of events.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotEventsRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              events:
                - robotId: rbt_example
                  eventId: evt_1001
                  eventStart: 2026-10-15T10:00:00.000Z
                  timezone: Asia/Hong_Kong
                  type: mode_change
                  nativeCode: "100"
                  nativeDescription: Autonomous moving
      responses:
        "200":
          description: >
            Events stored. `accepted` is new rows. `duplicates` is rows already
            stored for that partner, robot, and event id. `eventIds` lists every
            id in order.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotEventsResponse"
              example:
                accepted: 1
                duplicates: 0
                eventIds:
                  - evt_1001
        "400":
          description: >
            The events list is empty, a required field is missing, or `type`,
            `objectMotion`, `subject`, `resolution`, or `consequence` is not one
            of the allowed values.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "413":
          description: More than 500 events. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: payload_too_large
  /v1/robots/summaries/status:
    post:
      tags:
        - Robots
      operationId: postRobotStatusSummaries
      summary: Post robot status summaries (beta)
      x-beta: true
      description: >
        Beta. Post 1 to 1000 status records with the server key. Each record
        covers 1 to 5 seconds and needs `robotId`, `recordedAt`, `timezone`, and
        `periodSeconds`. Connectivity, movement, and pose fields are optional.
        `xM`, `yM`, and `zM` are metres in the map frame. Prefer a `mapId` you
        already completed. A missing map is still stored. YAS counts online and
        active time from `operatingMode`. Online counts only an explicit `idle`,
        `autonomous`, `manual`, or `charging`. A window that omits
        `operatingMode` is not online and not active. `idle` and `charging` are
        online and not active. Active time is `autonomous` or `manual`. `moving`
        is recorded on its own and is not added to those totals. The robot must
        already exist for this `partnerId`. An unknown `robotId` is 404; nothing
        in the call is stored. An empty list, a missing field, `periodSeconds`
        outside 1 to 5, or an unknown `operatingMode` is 400. More than 1000
        records is 413. Records have no id. Post the same window again and YAS
        stores another row. `accepted` equals the number of records.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotStatusRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              records:
                - robotId: rbt_example
                  recordedAt: 2026-10-15T10:00:05.000Z
                  timezone: Asia/Hong_Kong
                  periodSeconds: 5
                  cloudLink: up
                  wifiRssiDbm: -62
                  speedAvgMps: 0.4
      responses:
        "200":
          description: Status records stored. `accepted` equals the number of records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotSummaryResponse"
              example:
                accepted: 1
        "400":
          description: >
            The records list is empty, a required field is missing,
            `periodSeconds` is outside 1 to 5, or `operatingMode` is not one of
            the allowed values.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "413":
          description: More than 1000 records. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: payload_too_large
  /v1/robots/summaries/components:
    post:
      tags:
        - Robots
      operationId: postRobotComponentSummaries
      summary: Post robot component summaries (beta)
      x-beta: true
      description: >
        Beta. Post 1 to 500 component records with the server key. Each record
        covers 10 to 60 seconds and needs `robotId`, `recordedAt`, `timezone`,
        and `periodSeconds`. Battery, drive, perception, and surroundings fields
        are optional. Current and temperature stay on this call. Send one row
        per actuator in `actuators`, up to 32. A single drive may still use
        `motorCurrentA` and `motorTempC`. Send bands and classes only. Do not
        send video, audio, or a person's name. The robot must already exist for
        this `partnerId`. An unknown `robotId` is 404; nothing in the call is
        stored. An empty list, a missing field, `periodSeconds` outside 10 to
        60, or more than 32 actuators is 400. More than 500 records is 413.
        Records have no id. Post the same window again and YAS stores another
        row. `accepted` equals the number of records.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotComponentRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              records:
                - robotId: rbt_example
                  recordedAt: 2026-10-15T10:01:00.000Z
                  timezone: Asia/Hong_Kong
                  periodSeconds: 60
                  socPct: 72
                  peopleNearbyBand: few
      responses:
        "200":
          description: Component records stored. `accepted` equals the number of records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotSummaryResponse"
              example:
                accepted: 1
        "400":
          description: >
            The records list is empty, a required field is missing,
            `periodSeconds` is outside 10 to 60, or `actuators` has more than 32
            items.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "413":
          description: More than 500 records. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: payload_too_large
  /v1/robots/tasks:
    post:
      tags:
        - Robots
      operationId: postRobotTask
      summary: Post robot task (beta)
      x-beta: true
      description: >
        Beta. Create or replace one task with the server key. Send `partnerId`,
        `schemaVersion`, `sourceSystem`, `robotId`, `taskInstanceId`,
        `executeStart`, and `timezone`. The robot must already exist for this
        `partnerId`. An unknown `robotId` is 404. A later call with the same
        `partnerId`, `robotId`, and `taskInstanceId` replaces the stored body.
        Leave an optional field out and it is cleared. Examples for `taskType`
        are `patrol` and `charging`. Examples for `keywords` are `shared_space`,
        `night`, and `heavy_traffic`. Other words are stored. Leave `keywords`
        out and it is cleared. An empty list stores no words. `updatedAt` is
        ISO-8601 UTC.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotTaskRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              robotId: rbt_example
              taskInstanceId: task_1001
              taskId: patrol_12
              taskType: patrol
              keywords:
                - shared_space
                - night
              executeStart: 2026-10-15T10:00:00.000Z
              timezone: Asia/Hong_Kong
              status: complete
      responses:
        "200":
          description: >
            Task stored. A later call with the same task instance replaces it.
            `updatedAt` is ISO-8601 UTC.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotTaskResponse"
              example:
                robotId: rbt_example
                taskInstanceId: task_1001
                updatedAt: 2026-10-15T10:45:00.000Z
        "400":
          description: >
            A required field is missing, or `status`, `closer`, or `outcome` is
            not one of the allowed values.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
  /v1/robots/maintenance:
    post:
      tags:
        - Robots
      operationId: postRobotMaintenance
      summary: Post robot maintenance (beta)
      x-beta: true
      description: >
        Beta. Create or replace one maintenance record with the server key. Send
        `partnerId`, `schemaVersion`, `sourceSystem`, `robotId`,
        `maintenanceId`, and `timezone`. The robot must already exist for this
        `partnerId`. An unknown `robotId` is 404. A later call with the same
        `partnerId`, `robotId`, and `maintenanceId` replaces the stored body.
        Leave an optional field out and it is cleared. `updatedAt` is ISO-8601
        UTC.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotMaintenanceRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              robotId: rbt_example
              maintenanceId: mnt_1001
              timezone: Asia/Hong_Kong
              component: drive
              downtimeStart: 2026-10-15T12:00:00.000Z
      responses:
        "200":
          description: >
            Maintenance stored. A later call with the same maintenance id
            replaces it. `updatedAt` is ISO-8601 UTC.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotMaintenanceResponse"
              example:
                robotId: rbt_example
                maintenanceId: mnt_1001
                updatedAt: 2026-10-15T13:00:00.000Z
        "400":
          description: A required field is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
  /v1/robots/raw/media:
    post:
      tags:
        - Raw
      operationId: postRobotMedia
      summary: Mint robot media upload (beta)
      x-beta: true
      description: >
        Beta. Mint a URL for one media file with the server key. Send partnerId,
        schemaVersion,

        sourceSystem, robotId, recordedAt, timezone, contentType, and
        byteLength. The robot must already

        exist for this partner. Allowed content types are video/mp4, image/jpeg,
        image/png,

        application/json, application/x-ndjson, text/csv, text/plain and
        application/gzip. PUT with the

        declared Content-Type. application/octet-stream is not accepted for
        media. byteLength is 1 to

        52428800 (50 MiB), or the lower configured Storage limit. Each mint
        returns a new mediaId and

        does not replace an earlier file.


        Upload credentials last two hours; expiresAt is the credential deadline
        in ISO-8601 UTC.

        Complete within 24 hours of minting. The bytes enter private Storage on
        upload and become ready

        only after complete verifies their length and type. Storage does not
        bind the signed URL to

        byteLength; a mismatched file may be stored temporarily but cannot
        become ready. Uploads cannot

        overwrite an object. Mint a new upload after invalid content. Each
        partner may have at most 10

        outstanding upload reservations totaling at most 1 GiB across maps and
        media. Each reservation

        uses the effective bucket limit, including abandoned uploads until safe
        cleanup. Revoking Robots

        access immediately blocks mint and complete, but an issued Storage
        credential may remain usable

        until it expires. Uncompleted objects are cleaned after upload
        credentials and sessions expire;

        ready media and the current live map are retained.


        contentBase64 is not accepted and returns 400 invalid_body. Send
        byteLength, upload the

        bytes to the signed URL, then call complete.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotMediaRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              robotId: rbt_example
              recordedAt: 2026-10-15T10:00:00.000Z
              timezone: Asia/Hong_Kong
              contentType: text/csv
              byteLength: 1048576
      responses:
        "200":
          description: Signed upload URL minted. The signed URL lasts two hours; complete
            within 24 hours of minting.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotMediaMintResponse"
              example:
                mediaId: 62bc5e66-8e11-4940-a70d-22efc1979674
                uploadUrl: https://upload.example.yas/media/62bc5e66-8e11-4940-a70d-22efc1979674
                objectKey: partners/partner/62bc5e66-8e11-4940-a70d-22efc1979674
                expiresAt: 2026-10-15T12:00:00.000Z
                byteLength: 1048576
        "400":
          description: A required field is missing or invalid, the content type is
            unsupported, or contentBase64 was sent. No upload is created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "413":
          description: The declared size exceeds the effective Storage limit (at most
            52428800 bytes).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: payload_too_large
        "429":
          description: Outstanding upload reservations reached the partner limit. Retry
            after cleanup releases capacity.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: upload_quota_exceeded
        "503":
          description: Storage or its required configuration is unavailable. Retry after
            the Retry-After interval.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: unavailable
  /v1/robots/raw/media/{mediaId}/complete:
    post:
      tags:
        - Raw
      operationId: completeRobotMedia
      summary: Complete robot media (beta)
      x-beta: true
      description: "Beta. Complete makes the file live. Send `partnerId`,
        `schemaVersion`, and `sourceSystem`. `mediaId` is the id from mint. PUT
        the bytes to the minted URL first. An unknown `mediaId` for this partner
        is 404. The first complete returns `status` `ready`. A repeat on a ready
        file is 200 with `status` `ready`. Complete within 24 hours of minting.
        A missing upload is 409 upload_incomplete; a size or type mismatch is
        422 invalid_media. A credential may expire before the completion
        deadline: an already uploaded valid object can still complete. Mint
        again for invalid content because objects cannot be overwritten."
      parameters:
        - name: mediaId
          in: path
          required: true
          description: Id returned by mint.
          schema:
            type: string
          example: 62bc5e66-8e11-4940-a70d-22efc1979674
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotMediaCompleteRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
      responses:
        "200":
          description: >
            File is live. `status` is `ready`. A repeat on a ready file is 200
            with `status` `ready`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotMediaCompleteResponse"
              example:
                mediaId: 62bc5e66-8e11-4940-a70d-22efc1979674
                status: ready
        "400":
          description: A required field is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `mediaId`. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "409":
          description: No completed object is available yet. Upload before the credential
            expires and retry complete.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: upload_incomplete
        "410":
          description: The 24-hour completion deadline has expired. Mint again; a previous
            ready map is unchanged.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: upload_expired
        "422":
          description: The uploaded object does not match its declared size or type. Mint
            again and upload valid bytes; the object cannot be overwritten.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_media
        "503":
          description: Storage or its required configuration is unavailable. Retry after
            the Retry-After interval.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: unavailable
  /v1/robots/raw/samples:
    post:
      tags:
        - Raw
      operationId: postRobotSamples
      summary: Post robot samples (beta)
      x-beta: true
      description: >
        Beta. Post 1 to 100 samples with the server key. Each record needs
        `robotId`, `recordedAt`, `timezone`, and `label`. `payload` is optional
        and is stored as sent. The robot must already exist for this
        `partnerId`. An unknown `robotId` is 404; nothing in the call is stored.
        An empty list or a missing field is 400. More than 100 records is 413.
        Records have no id. Post again and YAS stores another row. `accepted`
        equals the number of records.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RobotSamplesRequest"
            example:
              partnerId: partner
              schemaVersion: 2026-11
              sourceSystem: partner-export
              records:
                - robotId: rbt_example
                  recordedAt: 2026-10-15T10:00:05.000Z
                  timezone: Asia/Hong_Kong
                  label: dock_camera
                  payload:
                    note: glare
      responses:
        "200":
          description: Samples stored. `accepted` equals the number of records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RobotSummaryResponse"
              example:
                accepted: 1
        "400":
          description: The list is empty or a required field is missing. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_body
        "401":
          description: The server key is missing or wrong.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: invalid_credentials
        "403":
          description: A server key may be limited to vehicles, robots, or both. A call
            outside that limit is 403 `forbidden` and stores nothing.
            `identity_mismatch` means `partnerId` does not match the server key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: forbidden
        "404":
          description: Unknown `robotId`. Nothing in this call is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "413":
          description: More than 100 records. Nothing is stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: payload_too_large
components:
  securitySchemes:
    serverKey:
      type: http
      scheme: bearer
      description: >
        Server key for the partner backend. Send it on the calls in this file. A
        server key may be limited to vehicles, robots, or both. A call outside
        that limit is 403 `forbidden` and stores nothing. It never enters the
        app.
  schemas:
    RobotUpsertRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - model
        - serial
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        model:
          type: string
          description: Robot model name.
        serial:
          type: string
          description: Serial number.
        vin:
          type: string
          description: Vehicle identification number, when the robot has one.
        massKg:
          type: number
          description: Mass in kilograms.
        lengthM:
          type: number
          description: Length in metres.
        widthM:
          type: number
          description: Width in metres.
        heightM:
          type: number
          description: Height in metres.
        ratedSpeedMps:
          type: number
          description: Rated speed in metres per second.
        maxSpeedMps:
          type: number
          description: Top speed this robot is built for, in metres per second.
        batteryType:
          type: string
          description: "Battery chemistry or pack type. Example: `lithium`."
        batteryCapacityWh:
          type: number
          description: Battery capacity in watt-hours.
        sensorSuite:
          type: array
          description: "Sensor names on this robot. Example: `lidar`."
          items:
            type: string
        controller:
          type: string
          description: Controller name.
        firmwareVersion:
          type: string
          description: Firmware version at the time of this call.
        deployedOn:
          type: string
          format: date
          description: Date the robot was deployed, as `YYYY-MM-DD`.
        metadata:
          type: object
          description: Extra fields from the partner. Stored as sent.
          additionalProperties: true
    RobotWriteResponse:
      type: object
      required:
        - robotId
        - updatedAt
      properties:
        robotId:
          type: string
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Stable error code. No stack trace.
    RobotMapMintRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - robotId
        - mapId
        - unitM
        - contentType
        - byteLength
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        mapId:
          type: string
          description: Map id. A second mint replaces only the open upload. The live map
            changes when complete succeeds.
        unitM:
          type: integer
          enum:
            - 1
          description: One map unit is one metre. The only allowed value is 1.
        contentType:
          type: string
          description: "Map format: `occupancy_grid` or `point_cloud`."
          enum:
            - occupancy_grid
            - point_cloud
        byteLength:
          type: integer
          minimum: 1
          maximum: 52428800
          description: Exact uploaded size from 1 to 52428800 bytes, subject to the lower
            configured Storage limit. Verified at complete.
        mapVersion:
          type: string
          description: Version label stored with this upload. The live map stays as it is
            until complete.
        originXM:
          type: number
          description: Map origin X in metres.
        originYM:
          type: number
          description: Map origin Y in metres.
        originZM:
          type: number
          description: Map origin Z in metres.
        contentSha256:
          type: string
          description: SHA-256 of the bytes to upload. Stored and not checked.
        pointCount:
          type: integer
          description: Point count the partner reports. Stored and not checked against the
            bytes.
        firmwareVersion:
          type: string
          description: Firmware version at the time of this call.
        metadata:
          type: object
          description: Extra fields from the partner. Stored as sent.
          additionalProperties: true
      not:
        required:
          - contentBase64
    RobotMapMintResponse:
      type: object
      required:
        - robotId
        - mapId
        - uploadUrl
        - objectKey
        - expiresAt
        - byteLength
      properties:
        robotId:
          type: string
        mapId:
          type: string
        uploadUrl:
          type: string
          format: uri
          description: PUT raw bytes here before expiresAt. The private object becomes
            ready only after complete. Do not share or log this credential.
        objectKey:
          type: string
          description: Assigned by YAS. Send the bytes to `uploadUrl`. Do not set this
            value yourself.
        expiresAt:
          type: string
          format: date-time
          description: Upload credential expiry in ISO-8601 UTC, two hours after minting.
            Complete has a separate 24-hour deadline.
        byteLength:
          type: integer
          description: Declared byteLength. Complete rejects an object whose actual size
            differs.
    RobotMapCompleteRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - robotId
        - mapId
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        mapId:
          type: string
          description: Map id from mint. The live map changes when complete succeeds.
    RobotMapCompleteResponse:
      type: object
      required:
        - robotId
        - mapId
        - status
      properties:
        robotId:
          type: string
        mapId:
          type: string
        status:
          type: string
          enum:
            - ready
          description: "`ready` means the map is live."
        updatedAt:
          type: string
          format: date-time
          description: ISO-8601 UTC on the first complete. A repeat when the map is
            already live omits this field.
    RobotEventsRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - events
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        firmwareVersion:
          type: string
          description: Firmware version at the time of this call.
        metadata:
          type: object
          description: Extra fields from the partner. Stored as sent.
          additionalProperties: true
        events:
          type: array
          description: Events in this call. Send 1 to 500.
          minItems: 1
          maxItems: 500
          items:
            $ref: "#/components/schemas/RobotEvent"
    RobotEventsResponse:
      type: object
      required:
        - accepted
        - duplicates
        - eventIds
      properties:
        accepted:
          type: integer
        duplicates:
          type: integer
        eventIds:
          type: array
          items:
            type: string
    RobotStatusRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - records
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        firmwareVersion:
          type: string
          description: Firmware version at the time of this call.
        metadata:
          type: object
          description: Extra fields from the partner. Stored as sent.
          additionalProperties: true
        records:
          type: array
          description: Status windows in this call. Send 1 to 1000.
          minItems: 1
          maxItems: 1000
          items:
            $ref: "#/components/schemas/RobotStatusRecord"
    RobotSummaryResponse:
      type: object
      required:
        - accepted
      properties:
        accepted:
          type: integer
    RobotComponentRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - records
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        firmwareVersion:
          type: string
          description: Firmware version at the time of this call.
        metadata:
          type: object
          description: Extra fields from the partner. Stored as sent.
          additionalProperties: true
        records:
          type: array
          description: Component windows in this call. Send 1 to 500.
          minItems: 1
          maxItems: 500
          items:
            $ref: "#/components/schemas/RobotComponentRecord"
    RobotTaskRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - robotId
        - taskInstanceId
        - executeStart
        - timezone
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        taskInstanceId:
          type: string
          description: Id of this run of the task. The same partner, robot, and task
            instance replaces the stored body.
        executeStart:
          type: string
          format: date-time
          description: When the task started, as ISO-8601.
        timezone:
          type: string
          description: "IANA timezone. Example: `Asia/Hong_Kong`."
        taskId:
          type: string
          description: "Partner task definition id. Example: `patrol_12`."
        taskType:
          type: string
          description: "What the robot was doing. Examples: `patrol`, `charging`."
        keywords:
          type: array
          maxItems: 32
          description: "Words that describe this task. YAS uses them later to group
            similar tasks. Examples: `shared_space`, `night`, `heavy_traffic`.
            Other words are stored."
          items:
            type: string
        executeEnd:
          type: string
          format: date-time
          description: When the task ended, as ISO-8601.
        status:
          type: string
          description: Task status. Any other value is rejected.
          enum:
            - planned
            - running
            - complete
            - failed
            - cancelled
        closer:
          type: string
          description: "Who ended the task: `robot`, `operator`, or `partner`."
          enum:
            - robot
            - operator
            - partner
        isArrived:
          type: boolean
          description: True when the robot reached the goal.
        routeId:
          type: string
          description: Route id.
        distanceM:
          type: number
          description: Mission distance in metres.
        durationSeconds:
          type: number
          description: Mission length in seconds.
        startSoc:
          type: number
          description: State of charge at the start, as a percent.
        endSoc:
          type: number
          description: State of charge at the end, as a percent.
        interventionCount:
          type: integer
          description: How many interventions happened during the task.
        abnormalReason:
          type: string
          description: Why the task was abnormal.
        siteId:
          type: string
          description: Site id.
        sharedSpace:
          type: boolean
          description: True when the task runs in a space shared with people.
        outcome:
          type: string
          description: "How the task ended: `complete`, `interrupted`, or `aborted`."
          enum:
            - complete
            - interrupted
            - aborted
        firmwareVersion:
          type: string
          description: Firmware version at the time of this call.
        metadata:
          type: object
          description: Extra fields from the partner. Stored as sent.
          additionalProperties: true
    RobotTaskResponse:
      type: object
      required:
        - robotId
        - taskInstanceId
        - updatedAt
      properties:
        robotId:
          type: string
        taskInstanceId:
          type: string
        updatedAt:
          type: string
          format: date-time
    RobotMaintenanceRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - robotId
        - maintenanceId
        - timezone
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        maintenanceId:
          type: string
          description: Id of this service visit. The same partner, robot, and maintenance
            id replaces the stored body.
        timezone:
          type: string
          description: "IANA timezone. Example: `Asia/Hong_Kong`."
        taskInstanceId:
          type: string
          description: Task instance this visit relates to, when there is one.
        eventId:
          type: string
          description: Event id this visit relates to, when there is one.
        complaint:
          type: string
          description: What was reported.
        diagnosis:
          type: string
          description: What was found.
        component:
          type: string
          description: "Part that was serviced. Example: `drive`."
        partReplacement:
          type: string
          description: Part that was replaced.
        correctiveAction:
          type: string
          description: What was done.
        downtimeStart:
          type: string
          format: date-time
          description: When downtime started, as ISO-8601.
        downtimeEnd:
          type: string
          format: date-time
          description: When downtime ended, as ISO-8601.
        labourHours:
          type: number
          description: Labour hours for this visit.
        cost:
          type: number
          description: Cost amount. Pair it with `currency`.
        currency:
          type: string
          description: "Currency code. Example: `HKD`."
        recurrence:
          type: boolean
          description: True when this fault has happened before.
        warranty:
          type: boolean
          description: True when the visit was under warranty.
        firmwareVersion:
          type: string
          description: Firmware version at the time of this call.
        metadata:
          type: object
          description: Extra fields from the partner. Stored as sent.
          additionalProperties: true
    RobotMaintenanceResponse:
      type: object
      required:
        - robotId
        - maintenanceId
        - updatedAt
      properties:
        robotId:
          type: string
        maintenanceId:
          type: string
        updatedAt:
          type: string
          format: date-time
    RobotMediaRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - robotId
        - recordedAt
        - timezone
        - contentType
        - byteLength
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        recordedAt:
          type: string
          format: date-time
          description: When the file was recorded, as ISO-8601.
        timezone:
          type: string
          description: "IANA timezone. Example: `Asia/Hong_Kong`."
        contentType:
          type: string
          description: Media type. Allowed values are `video/mp4`, `image/jpeg`,
            `image/png`, `application/json`, `application/x-ndjson`, `text/csv`,
            `text/plain`, and `application/gzip`.
          enum:
            - video/mp4
            - image/jpeg
            - image/png
            - application/json
            - application/x-ndjson
            - text/csv
            - text/plain
            - application/gzip
        byteLength:
          type: integer
          minimum: 1
          maximum: 52428800
          description: Exact uploaded size from 1 to 52428800 bytes, subject to the lower
            configured Storage limit. Verified at complete.
      not:
        required:
          - contentBase64
    RobotMediaMintResponse:
      type: object
      required:
        - mediaId
        - uploadUrl
        - objectKey
        - expiresAt
        - byteLength
      properties:
        mediaId:
          type: string
          description: Id for this file. It is the `mediaId` in the complete path. A
            second mint returns a new id.
        uploadUrl:
          type: string
          format: uri
          description: PUT raw bytes here before expiresAt. The private object becomes
            ready only after complete. Do not share or log this credential.
        objectKey:
          type: string
          description: Assigned by YAS. Send the bytes to `uploadUrl`. Do not set this
            value yourself.
        expiresAt:
          type: string
          format: date-time
          description: Upload credential expiry in ISO-8601 UTC, two hours after minting.
            Complete has a separate 24-hour deadline.
        byteLength:
          type: integer
          description: Declared byteLength. Complete rejects an object whose actual size
            differs.
    RobotMediaCompleteRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
    RobotMediaCompleteResponse:
      type: object
      required:
        - mediaId
        - status
      properties:
        mediaId:
          type: string
        status:
          type: string
          enum:
            - ready
          description: "`ready` means the file is live."
    RobotSamplesRequest:
      type: object
      required:
        - partnerId
        - schemaVersion
        - sourceSystem
        - records
      properties:
        partnerId:
          type: string
          description: Partner id. It must match the server key.
        schemaVersion:
          type: string
          description: "Schema version of this body. Example: `2026-11`."
        sourceSystem:
          type: string
          description: "Name of the system that sent this body. Example: `partner-export`."
        records:
          type: array
          description: Other samples in this call. Send 1 to 100.
          minItems: 1
          maxItems: 100
          items:
            $ref: "#/components/schemas/RobotSampleRecord"
    RobotEvent:
      type: object
      required:
        - robotId
        - eventId
        - eventStart
        - timezone
        - type
        - nativeCode
      properties:
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        eventId:
          type: string
          description: Partner event id. The same partner, robot, and event id keeps the
            first body.
        eventStart:
          type: string
          format: date-time
          description: When the episode started, as ISO-8601.
        timezone:
          type: string
          description: "IANA timezone. Example: `Asia/Hong_Kong`."
        type:
          type: string
          description: Kind of event.
          enum:
            - mode_change
            - alarm
            - intervention
            - navigation
            - incident
            - task_state
            - software_change
            - proximity
        nativeCode:
          type: string
          description: Partner code for this event.
        nativeDescription:
          type: string
          description: Partner text for `nativeCode`.
        taskInstanceId:
          type: string
          description: Task instance this event belongs to, when there is one.
        siteId:
          type: string
          description: Site id.
        zoneId:
          type: string
          description: Zone id inside the site.
        eventEnd:
          type: string
          format: date-time
          description: When the episode ended, as ISO-8601.
        updateTime:
          type: string
          format: date-time
          description: When this body was last updated, as ISO-8601.
        durationSeconds:
          type: number
          description: Length of the episode in seconds. This is not the response lag.
        reasonCode:
          type: string
          description: Partner reason code.
        modeBefore:
          type: string
          description: Operating mode before the event.
        modeDuring:
          type: string
          description: Operating mode during the event.
        modeAfter:
          type: string
          description: Operating mode after the event.
        taskStatus:
          type: string
          description: Task status the partner recorded on this event.
        sourceRecordId:
          type: string
          description: Id of the source record in the partner system.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence from 0 to 1.
        missing:
          type: boolean
          description: True when the robot did not identify the episode and a person or
            system filled the first stored body. A repeat of this event id still
            keeps that first body.
        duplicate:
          type: boolean
          description: True when the partner marks this row as a duplicate of another event.
        annotated:
          type: boolean
          description: True when a person added detail after the first body was stored.
        operatorAction:
          type: string
          description: "What the operator did. Examples: `take_over`, `clear_path`."
        guided:
          type: boolean
          description: True when a person guided the robot through the episode.
        repositioned:
          type: boolean
          description: True when the robot was moved by hand or by a remote command.
        reset:
          type: boolean
          description: True when the robot was reset during the episode.
        consequence:
          type: string
          description: What followed an incident or a near contact.
          enum:
            - none
            - near_miss
            - contact
            - damage
            - injury
        obstacleClass:
          type: string
          description: "Obstacle class. Example: `cart`."
        stopReason:
          type: string
          description: "Why the robot stopped. Examples: `obstacle`, `estop`."
        rerouteAttempts:
          type: integer
          description: How many times the robot tried another path.
        recoveryType:
          type: string
          description: "How the robot recovered. Examples: `reroute`, `wait`."
        contactOrNearContact:
          type: boolean
          description: True when there was contact or a near contact.
        incidentClass:
          type: string
          description: "Incident class. Example: `collision`."
        injuryOrDamage:
          type: boolean
          description: True when someone was hurt or something was damaged.
        evidenceRef:
          type: string
          description: Pointer to evidence held by the partner. YAS does not fetch it.
        resolution:
          type: string
          description: How the episode ended.
          enum:
            - recovered
            - takeover
            - unresolved
            - aborted
        version:
          type: string
          description: Software version after the change.
        changeReason:
          type: string
          description: Why the software changed.
        rollback:
          type: boolean
          description: True when this change rolled software back.
        mapOrConfigUpdate:
          type: boolean
          description: True when this change updated a map or a config.
        distanceM:
          type: number
          description: Metres to the object or person. This is not distance travelled.
        objectMotion:
          type: string
          description: Whether the object was still or moving.
          enum:
            - static
            - dynamic
            - unknown
        subject:
          type: string
          description: Whether the nearby thing was a person.
          enum:
            - human
            - non_human
            - unknown
        responseSeconds:
          type: number
          description: Seconds from detection to the first action. Omit the field when
            unknown. Do not send null.
    RobotStatusRecord:
      type: object
      required:
        - robotId
        - recordedAt
        - timezone
        - periodSeconds
      properties:
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        recordedAt:
          type: string
          format: date-time
          description: When this window ended, as ISO-8601 UTC.
        timezone:
          type: string
          description: "IANA timezone. Example: `Asia/Hong_Kong`."
        periodSeconds:
          type: integer
          minimum: 1
          maximum: 5
          description: Length of this window in seconds. Allowed range is 1 to 5.
        powerOk:
          type: boolean
          description: True when main power was present during the window.
        controllerState:
          type: string
          description: "Controller state. Example: `ready`."
        cloudLink:
          type: string
          description: "Cloud link during the window. Example: `up`."
        wifiRssiDbm:
          type: number
          description: Wi-Fi signal strength in dBm.
        accessPointOrZone:
          type: string
          description: Access point or zone name.
        latencyMs:
          type: number
          description: Round-trip latency in milliseconds.
        packetLossPct:
          type: number
          description: Packet loss as a percent.
        reconnectCount:
          type: integer
          description: How many times the link reconnected in the window.
        offlineReason:
          type: string
          description: Why the robot was offline. Send this when `operatingMode` is
            `offline`.
        distanceM:
          type: number
          description: Distance travelled in this window, in metres.
        speedAvgMps:
          type: number
          description: Average speed in metres per second.
        speedMaxMps:
          type: number
          description: Highest speed in this window, in metres per second.
        localisationQuality:
          type: number
          minimum: 0
          maximum: 1
          description: Localisation quality from 0 to 1.
        mapId:
          type: string
          description: Map this pose uses. Prefer a map already completed. A missing map
            is still stored.
        xM:
          type: number
          description: X in the map frame. One unit is one metre.
        yM:
          type: number
          description: Y in the map frame. One unit is one metre.
        zM:
          type: number
          description: Z in the map frame when the partner has height. One unit is one
            metre.
        operatingMode:
          type: string
          description: How the robot was working. `offline` is not online. `idle` and
            `charging` are online and not active. `autonomous` and `manual` are
            online and active. Omit the field and the window is not online and
            not active.
          enum:
            - offline
            - idle
            - autonomous
            - manual
            - charging
        moving:
          type: boolean
          description: True when the robot was in motion during the window. This is
            separate from `operatingMode` and is not added to online or active
            time.
        sharedSpace:
          type: boolean
          description: True when the robot was in a space shared with people.
    RobotComponentRecord:
      type: object
      required:
        - robotId
        - recordedAt
        - timezone
        - periodSeconds
      properties:
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        recordedAt:
          type: string
          format: date-time
          description: When this window ended, as ISO-8601 UTC.
        timezone:
          type: string
          description: "IANA timezone. Example: `Asia/Hong_Kong`."
        periodSeconds:
          type: integer
          minimum: 10
          maximum: 60
          description: Length of this window in seconds. Allowed range is 10 to 60.
        socPct:
          type: number
          description: State of charge as a percent.
        voltageV:
          type: number
          description: Pack voltage in volts.
        currentA:
          type: number
          description: Pack current in amperes.
        packTempC:
          type: number
          description: Pack temperature in Celsius.
        chargePowerW:
          type: number
          description: Charge power in watts.
        cycleCount:
          type: integer
          description: Charge cycle count.
        bmsWarning:
          type: string
          description: Battery warning text.
        motorCurrentA:
          type: number
          description: Drive current in amperes. Use `actuators` when there is more than
            one drive.
        motorTempC:
          type: number
          description: Drive temperature in Celsius. Use `actuators` when there is more
            than one drive.
        encoderError:
          type: boolean
          description: True when the encoder reported an error.
        vibration:
          type: number
          description: Vibration reading in the partner's units.
        lidarValid:
          type: boolean
          description: True when lidar data in this window was valid.
        cameraValid:
          type: boolean
          description: True when camera data in this window was valid.
        localisationConfidence:
          type: number
          minimum: 0
          maximum: 1
          description: Localisation confidence from 0 to 1.
        sensorCommsError:
          type: boolean
          description: True when a sensor link failed.
        surfaceClass:
          type: string
          description: "Floor or ground class. Example: `tile`."
        slopePct:
          type: number
          description: Slope as a percent.
        wetOrSlippery:
          type: boolean
          description: True when the surface was wet or slippery.
        lightingBand:
          type: string
          description: "Light level. Preferred words: `dark`, `dim`, `normal`, `bright`.
            Other words are stored."
        tempC:
          type: number
          description: Air temperature in Celsius.
        humidityPct:
          type: number
          description: Relative humidity as a percent.
        peopleNearbyBand:
          type: string
          description: "How many people were nearby. Preferred words: `none`, `few`,
            `many`. Other words are stored."
        obstacleDensityBand:
          type: string
          description: "How crowded the space was. Preferred words: `clear`, `sparse`,
            `dense`. Other words are stored."
        minClearanceM:
          type: number
          description: Smallest clearance in metres.
        actuators:
          type: array
          maxItems: 32
          description: One row per actuator, up to 32. Prefer this when there is more than
            one drive.
          items:
            $ref: "#/components/schemas/RobotActuator"
    RobotSampleRecord:
      type: object
      required:
        - robotId
        - recordedAt
        - timezone
        - label
      properties:
        robotId:
          type: string
          description: Robot id. The robot must already exist.
        recordedAt:
          type: string
          format: date-time
          description: When this sample was taken, as ISO-8601.
        timezone:
          type: string
          description: "IANA timezone. Example: `Asia/Hong_Kong`."
        label:
          type: string
          description: Name the partner gives this sample.
        payload:
          type: object
          description: Extra fields for this sample. Stored as sent.
          additionalProperties: true
    RobotActuator:
      type: object
      properties:
        name:
          type: string
          description: "Actuator name. Examples: `drive_left`, `lift`."
        currentA:
          type: number
          description: Actuator current in amperes.
        tempC:
          type: number
          description: Actuator temperature in Celsius.
