openapi: 3.0.3
info:
  title: Bringg Drivers and Shifts API
  version: '1.0'
  description: |
    Bringg's Drivers and Shifts REST API covers driver lifecycle (users, roles, login),
    shift management (start/end shift, driver home events, availability), driver
    location updates, QR-code generation, delivery blocks (driver shift slots),
    vehicles, and vehicle profiles. Uses OAuth 2.0 Client Credentials.
  contact:
    name: Bringg Developer Support
    url: https://developers.bringg.com
  license:
    name: Bringg API Terms of Service
    url: https://developers.bringg.com/reference/terms-of-service
servers:
- url: https://us2-admin-api.bringg.com
  description: US2 region (GCP)
- url: https://us3-admin-api.bringg.com
  description: US3 region (GCP)
- url: https://us4-admin-api.bringg.com
  description: US4 region (GCP)
- url: https://eu2-admin-api.bringg.com
  description: EU2 region (GCP)
- url: https://eu3-admin-api.bringg.com
  description: EU3 region (GCP)
security:
- OAuth2ClientCredentials: []
paths:
  /services/create_user:
    post:
      summary: Create User
      description: Create a new user (driver, dispatcher, or other role).
      tags: [Users]
      operationId: createUser
      responses:
        '200': {description: User created.}
  /services/update_user:
    post:
      summary: Update User
      description: Update an existing user.
      tags: [Users]
      operationId: updateUser
      responses:
        '200': {description: User updated.}
  /services/get_user:
    get:
      summary: Get User
      description: Get a user by id.
      tags: [Users]
      operationId: getUser
      responses:
        '200': {description: User returned.}
  /services/get_users:
    get:
      summary: Get Users
      description: List all users.
      tags: [Users]
      operationId: getUsers
      responses:
        '200': {description: Users returned.}
  /services/delete_user:
    delete:
      summary: Delete User
      description: Delete a user.
      tags: [Users]
      operationId: deleteUser
      responses:
        '200': {description: User deleted.}
  /services/create_user_type:
    post:
      summary: Create User Role
      description: Create a custom user role/type.
      tags: [Users]
      operationId: createUserType
      responses:
        '200': {description: Created.}
  /services/logoff_user:
    post:
      summary: Logoff Driver
      description: Log a driver out of the Bringg Driver App.
      tags: [Drivers]
      operationId: logoffUser
      responses:
        '200': {description: Logged off.}
  /services/generate_driver_qr_code:
    post:
      summary: Generate Driver QR Code
      description: Generate an access token and QR code for Driver App login of a specified driver.
      tags: [Drivers]
      operationId: generateDriverQrCode
      responses:
        '200': {description: QR code generated.}
  /services/generate_pickup_qr_code:
    post:
      summary: Generate Pickup QR Code
      description: Generate a pickup QR code for an order or location.
      tags: [Drivers]
      operationId: generatePickupQrCode
      responses:
        '200': {description: QR code generated.}
  /services/start_shift:
    post:
      summary: Start Shift
      description: Start a driver's shift.
      tags: [Shifts]
      operationId: startShift
      responses:
        '200': {description: Shift started.}
  /services/end_shift:
    post:
      summary: End Shift
      description: End a driver's shift.
      tags: [Shifts]
      operationId: endShift
      responses:
        '200': {description: Shift ended.}
  /services/driver_home_events:
    post:
      summary: Initiate Driver Home Events
      description: Indicate whether a driver is at or has departed their home base.
      tags: [Drivers]
      operationId: driverHomeEvents
      responses:
        '200': {description: Event recorded.}
  /services/get_realtime_availability:
    get:
      summary: Get Driver Availability
      description: Retrieve real-time driver availability across specified teams.
      tags: [Drivers]
      operationId: getRealtimeAvailability
      responses:
        '200': {description: Availability returned.}
  /services/update_driver_location:
    post:
      summary: Update Driver Location
      description: Push a driver's GPS location for more accurate ETA calculations.
      tags: [Drivers]
      operationId: updateDriverLocation
      responses:
        '200': {description: Location updated.}
  /services/create_delivery_block:
    post:
      summary: Create Delivery Block
      description: Create a delivery block (driver shift slot for delivery work).
      tags: [Delivery Blocks]
      operationId: createDeliveryBlock
      responses:
        '200': {description: Created.}
  /services/update_delivery_block:
    post:
      summary: Update Delivery Block
      description: Update a delivery block.
      tags: [Delivery Blocks]
      operationId: updateDeliveryBlock
      responses:
        '200': {description: Updated.}
  /services/delete_delivery_block:
    delete:
      summary: Delete Delivery Block
      description: Delete a delivery block.
      tags: [Delivery Blocks]
      operationId: deleteDeliveryBlock
      responses:
        '200': {description: Deleted.}
  /services/get_delivery_block:
    get:
      summary: Get Delivery Block
      description: Get a delivery block by id.
      tags: [Delivery Blocks]
      operationId: getDeliveryBlock
      responses:
        '200': {description: Returned.}
  /services/assign_delivery_block:
    post:
      summary: Assign Delivery Block
      description: Assign a driver to a delivery block.
      tags: [Delivery Blocks]
      operationId: assignDeliveryBlock
      responses:
        '200': {description: Assigned.}
  /services/unassign_delivery_block:
    post:
      summary: Unassign Delivery Block
      description: Unassign a driver from a delivery block.
      tags: [Delivery Blocks]
      operationId: unassignDeliveryBlock
      responses:
        '200': {description: Unassigned.}
  /services/users_delivery_blocks:
    get:
      summary: Get Delivery Blocks By User
      description: List delivery blocks assigned to specific users.
      tags: [Delivery Blocks]
      operationId: usersDeliveryBlocks
      responses:
        '200': {description: Returned.}
  /services/team_delivery_blocks:
    get:
      summary: Get Delivery Blocks By Team
      description: List delivery blocks for a team.
      tags: [Delivery Blocks]
      operationId: teamDeliveryBlocks
      responses:
        '200': {description: Returned.}
  /services/create_vehicle:
    post:
      summary: Create Vehicle
      description: Create a vehicle record.
      tags: [Vehicles]
      operationId: createVehicle
      responses:
        '200': {description: Created.}
  /services/update_vehicle:
    post:
      summary: Update Vehicle
      description: Update a vehicle.
      tags: [Vehicles]
      operationId: updateVehicle
      responses:
        '200': {description: Updated.}
  /services/delete_vehicle:
    delete:
      summary: Delete Vehicle
      description: Delete a vehicle.
      tags: [Vehicles]
      operationId: deleteVehicle
      responses:
        '200': {description: Deleted.}
  /services/get_vehicle_by_id:
    get:
      summary: Get Vehicle
      description: Get a vehicle by id.
      tags: [Vehicles]
      operationId: getVehicleById
      responses:
        '200': {description: Returned.}
  /services/get_all_vehicles:
    get:
      summary: Get All Vehicles
      description: List all vehicles.
      tags: [Vehicles]
      operationId: getAllVehicles
      responses:
        '200': {description: Returned.}
  /services/create_vehicle_type:
    post:
      summary: Create Vehicle Profile
      description: Create a vehicle profile/type definition (capacity, constraints).
      tags: [Vehicle Profiles]
      operationId: createVehicleType
      responses:
        '200': {description: Created.}
  /services/update_vehicle_type:
    post:
      summary: Update Vehicle Profile
      description: Update a vehicle profile.
      tags: [Vehicle Profiles]
      operationId: updateVehicleType
      responses:
        '200': {description: Updated.}
  /services/destroy_vehicle_type:
    delete:
      summary: Delete Vehicle Profile
      description: Delete a vehicle profile.
      tags: [Vehicle Profiles]
      operationId: destroyVehicleType
      responses:
        '200': {description: Deleted.}
  /services/get_vehicle_type:
    get:
      summary: Get Vehicle Profile
      description: Get a vehicle profile by id.
      tags: [Vehicle Profiles]
      operationId: getVehicleType
      responses:
        '200': {description: Returned.}
  /services/get_vehicle_types:
    get:
      summary: Get Vehicle Profiles
      description: List vehicle profiles.
      tags: [Vehicle Profiles]
      operationId: getVehicleTypes
      responses:
        '200': {description: Returned.}
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 Client Credentials Grant.
      flows:
        clientCredentials:
          tokenUrl: https://admin-api.bringg.com/oauth/token
          scopes:
            create_user: Create users
            update_user: Update users
            get_user: Read users
            delete_user: Delete users
            start_shift: Start shifts
            end_shift: End shifts
            update_driver_location: Update driver location
            create_delivery_block: Create delivery blocks
            create_vehicle: Create vehicles