openapi: 3.1.0
info:
  title: YAS SDK
  version: 0.2.0
  description: >
    Partner REST for vehicles. Mint a bearer for the phone SDK at POST
    /v1/vehicles/tokens and close a trip at POST /v1/vehicles/trips/end. POST
    /v1/tokens and POST /v1/trips/end are deprecated. The server key never
    enters the app. Trip end is beta.
servers:
  - url: https://api.example.yas
    description: YAS API.
tags:
  - name: Vehicles
paths:
  /v1/vehicles/tokens:
    post:
      tags:
        - Vehicles
      operationId: createAccessToken
      summary: Mint access token
      description: >
        The partner backend mints a bearer with the server key. The SDK can use
        that bearer for 24 hours. Mint it for the partnerId, driverId, and
        vehicleId from setup. `POST /v1/tokens` is deprecated. Use this path.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenRequest"
            example:
              partnerId: partner
              driverId: drv_example
              vehicleId: veh_example
      responses:
        "200":
          description: A bearer for tokenProvider to return.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
              example:
                accessToken: eyJexample
                expiresAt: 2026-10-16T12:00:00.000Z
                tokenType: Bearer
        "400":
          description: The body is not a JSON object, `partnerId` does not match
            `^[a-z0-9-]{1,64}$`, or `driverId` or `vehicleId` is missing or
            empty. This check runs after authentication and before the partner
            match, so a malformed `partnerId` is 400, not 403.
          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/vehicles/trips/end:
    post:
      tags:
        - Vehicles
      operationId: endTrip
      summary: End trip (beta)
      x-beta: true
      description: >
        Beta. The partner backend closes an open trip with the server key. Send
        `partnerId`, `endTime`, and exactly one of `sessionId` or `tripId`.
        Sending both, or neither, is a 400. `endTime` is UTC with a `Z` suffix.
        An offset is 400. The first `endTime` is kept. A later call does not
        replace it. An unknown `sessionId` is stored as already closed. An
        unknown `tripId` is 404. More than one open session for a `tripId` is
        409. `POST /v1/trips/end` is deprecated. Use this path.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TripEndRequest"
            example:
              partnerId: partner
              endTime: 2026-10-15T10:45:00.000Z
              sessionId: 0199e0a0-0000-7000-8000-000000000001
      responses:
        "200":
          description: Trip ended. An unknown `sessionId` is stored as already closed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TripEndResponse"
              example:
                endTime: 2026-10-15T10:45:00.000Z
                endedBy: partner
                sessionId: 0199e0a0-0000-7000-8000-000000000001
                tripId: booking_1001
        "400":
          description: >
            `endTime` must be UTC with a `Z` suffix, such as
            `2026-10-15T10:45:00.000Z`. An offset, a missing or unreal time, a
            `sessionId` that is not a UUID, an empty `tripId`, both ids, or
            neither id is 400.
          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 `tripId`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "409":
          description: More than one open session for that `tripId`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: ambiguous_trip
  /v1/tokens:
    post:
      tags:
        - Vehicles
      operationId: createAccessTokenDeprecated
      summary: Mint access token (deprecated)
      deprecated: true
      description: >
        Deprecated. Use `POST /v1/vehicles/tokens`. The body and errors are the
        same.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenRequest"
            example:
              partnerId: partner
              driverId: drv_example
              vehicleId: veh_example
      responses:
        "200":
          description: A bearer for tokenProvider to return.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
              example:
                accessToken: eyJexample
                expiresAt: 2026-10-16T12:00:00.000Z
                tokenType: Bearer
        "400":
          description: The body is not a JSON object, `partnerId` does not match
            `^[a-z0-9-]{1,64}$`, or `driverId` or `vehicleId` is missing or
            empty. This check runs after authentication and before the partner
            match, so a malformed `partnerId` is 400, not 403.
          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/trips/end:
    post:
      tags:
        - Vehicles
      operationId: endTripDeprecated
      summary: End trip (deprecated)
      deprecated: true
      x-beta: true
      description: >
        Deprecated. Use `POST /v1/vehicles/trips/end`. The body and errors are
        the same. This call is beta.
      security:
        - serverKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TripEndRequest"
            example:
              partnerId: partner
              endTime: 2026-10-15T10:45:00.000Z
              sessionId: 0199e0a0-0000-7000-8000-000000000001
      responses:
        "200":
          description: Trip ended. An unknown `sessionId` is stored as already closed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TripEndResponse"
              example:
                endTime: 2026-10-15T10:45:00.000Z
                endedBy: partner
                sessionId: 0199e0a0-0000-7000-8000-000000000001
                tripId: booking_1001
        "400":
          description: >
            `endTime` must be UTC with a `Z` suffix, such as
            `2026-10-15T10:45:00.000Z`. An offset, a missing or unreal time, a
            `sessionId` that is not a UUID, an empty `tripId`, both ids, or
            neither id is 400.
          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 `tripId`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_found
        "409":
          description: More than one open session for that `tripId`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: ambiguous_trip
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:
    TokenRequest:
      type: object
      required:
        - partnerId
        - driverId
        - vehicleId
      properties:
        partnerId:
          type: string
          pattern: ^[a-z0-9-]{1,64}$
          description: Partner id from setup. It must match the server key.
        driverId:
          type: string
          minLength: 1
          description: Driver id from setup.
        vehicleId:
          type: string
          minLength: 1
          description: Vehicle id from setup.
    TokenResponse:
      type: object
      required:
        - accessToken
        - expiresAt
        - tokenType
      properties:
        accessToken:
          type: string
        expiresAt:
          type: string
          format: date-time
          description: ISO-8601 UTC. The token lasts 24 hours.
        tokenType:
          type: string
          enum:
            - Bearer
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Stable error code. No stack trace.
    TripEndRequest:
      type: object
      required:
        - partnerId
        - endTime
      description: >
        Send exactly one of `sessionId` or `tripId`. Both, or neither, is a 400.
        `endTime` is UTC with a `Z` suffix.
      properties:
        partnerId:
          type: string
          pattern: ^[a-z0-9-]{1,64}$
          description: Partner id from setup. It must match the server key.
        endTime:
          type: string
          format: date-time
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?Z$
          description: UTC with a `Z` suffix, such as `2026-10-15T10:45:00.000Z`. An
            offset such as `+08:00` is 400.
        sessionId:
          type: string
          format: uuid
          description: Open session to close. Send this or `tripId`, not both.
        tripId:
          type: string
          minLength: 1
          description: Partner trip id to close. Send this or `sessionId`, not both.
    TripEndResponse:
      type: object
      required:
        - endTime
        - endedBy
        - sessionId
      properties:
        endTime:
          type: string
          format: date-time
          description: The time that was stored. A later call does not change it.
        endedBy:
          type: string
          enum:
            - partner
            - phone
            - silence
          description: "Who closed the trip: `partner` for the backend, `phone` for the
            SDK, or `silence` when the phone stopped reporting. A later call
            keeps the stored value."
        sessionId:
          type: string
          format: uuid
        tripId:
          type: string
