openapi: 3.0.1
info:
  title: Fleetbase API
  description: >-
    RESTful API for the Fleetbase open-source logistics and supply chain
    operating system. Manage orders, places, contacts, drivers, vehicles,
    fleets, zones, service rates, tracking, and webhooks. Available
    self-hosted (AGPL-3.0) or via managed Fleetbase Cloud.
  termsOfService: https://www.fleetbase.io/terms
  contact:
    name: Fleetbase Support
    email: hello@fleetbase.io
    url: https://docs.fleetbase.io
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  version: '1.0'
servers:
  - url: https://api.fleetbase.io/v1
    description: Fleetbase Cloud / self-hosted REST API
security:
  - bearerAuth: []
tags:
  - name: Orders
    description: Create, dispatch, and manage delivery orders.
  - name: Places
    description: Addressable geocoded locations.
  - name: Contacts
    description: Customer and facilitator contacts.
  - name: Drivers
    description: Drivers and their assignments.
  - name: Vehicles
    description: Vehicles in the fleet.
  - name: Fleets
    description: Groupings of drivers and vehicles.
  - name: Zones
    description: Service-area geofences.
  - name: Service Rates
    description: Pricing rules and delivery quotes.
  - name: Tracking
    description: Tracking status and telemetry.
  - name: Webhooks
    description: Event subscription endpoints.
paths:
  /orders:
    get:
      operationId: listOrders
      tags:
        - Orders
      summary: List orders
      description: Returns a paginated list of orders for the organization.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: status
          in: query
          description: Filter orders by status (e.g. created, dispatched, completed).
          schema:
            type: string
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create an order
      description: Creates a new delivery order with pickup, dropoff, and payload entities.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
      responses:
        '200':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{id}:
    get:
      operationId: getOrder
      tags:
        - Orders
      summary: Retrieve an order
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    put:
      operationId: updateOrder
      tags:
        - Orders
      summary: Update an order
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    delete:
      operationId: cancelOrder
      tags:
        - Orders
      summary: Cancel an order
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the order was cancelled.
  /orders/{id}/dispatch:
    patch:
      operationId: dispatchOrder
      tags:
        - Orders
      summary: Dispatch an order
      description: Dispatches an order to an assigned driver.
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The dispatched order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /places:
    get:
      operationId: listPlaces
      tags:
        - Places
      summary: List places
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of places.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Place'
    post:
      operationId: createPlace
      tags:
        - Places
      summary: Create a place
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Place'
      responses:
        '200':
          description: The created place.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Place'
  /places/{id}:
    get:
      operationId: getPlace
      tags:
        - Places
      summary: Retrieve a place
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested place.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Place'
    put:
      operationId: updatePlace
      tags:
        - Places
      summary: Update a place
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Place'
      responses:
        '200':
          description: The updated place.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Place'
    delete:
      operationId: deletePlace
      tags:
        - Places
      summary: Delete a place
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the place was deleted.
  /contacts:
    get:
      operationId: listContacts
      tags:
        - Contacts
      summary: List contacts
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of contacts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
    post:
      operationId: createContact
      tags:
        - Contacts
      summary: Create a contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: The created contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
  /contacts/{id}:
    get:
      operationId: getContact
      tags:
        - Contacts
      summary: Retrieve a contact
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    put:
      operationId: updateContact
      tags:
        - Contacts
      summary: Update a contact
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    delete:
      operationId: deleteContact
      tags:
        - Contacts
      summary: Delete a contact
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the contact was deleted.
  /drivers:
    get:
      operationId: listDrivers
      tags:
        - Drivers
      summary: List drivers
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of drivers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Driver'
    post:
      operationId: createDriver
      tags:
        - Drivers
      summary: Create a driver
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Driver'
      responses:
        '200':
          description: The created driver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Driver'
  /drivers/{id}:
    get:
      operationId: getDriver
      tags:
        - Drivers
      summary: Retrieve a driver
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested driver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Driver'
    put:
      operationId: updateDriver
      tags:
        - Drivers
      summary: Update a driver
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Driver'
      responses:
        '200':
          description: The updated driver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Driver'
    delete:
      operationId: deleteDriver
      tags:
        - Drivers
      summary: Delete a driver
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the driver was deleted.
  /vehicles:
    get:
      operationId: listVehicles
      tags:
        - Vehicles
      summary: List vehicles
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of vehicles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Vehicle'
    post:
      operationId: createVehicle
      tags:
        - Vehicles
      summary: Create a vehicle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Vehicle'
      responses:
        '200':
          description: The created vehicle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vehicle'
  /vehicles/{id}:
    get:
      operationId: getVehicle
      tags:
        - Vehicles
      summary: Retrieve a vehicle
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested vehicle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vehicle'
    put:
      operationId: updateVehicle
      tags:
        - Vehicles
      summary: Update a vehicle
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Vehicle'
      responses:
        '200':
          description: The updated vehicle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vehicle'
    delete:
      operationId: deleteVehicle
      tags:
        - Vehicles
      summary: Delete a vehicle
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the vehicle was deleted.
  /fleets:
    get:
      operationId: listFleets
      tags:
        - Fleets
      summary: List fleets
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of fleets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Fleet'
    post:
      operationId: createFleet
      tags:
        - Fleets
      summary: Create a fleet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fleet'
      responses:
        '200':
          description: The created fleet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fleet'
  /fleets/{id}:
    get:
      operationId: getFleet
      tags:
        - Fleets
      summary: Retrieve a fleet
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested fleet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fleet'
    put:
      operationId: updateFleet
      tags:
        - Fleets
      summary: Update a fleet
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fleet'
      responses:
        '200':
          description: The updated fleet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fleet'
    delete:
      operationId: deleteFleet
      tags:
        - Fleets
      summary: Delete a fleet
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the fleet was deleted.
  /zones:
    get:
      operationId: listZones
      tags:
        - Zones
      summary: List zones
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of zones.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Zone'
    post:
      operationId: createZone
      tags:
        - Zones
      summary: Create a zone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Zone'
      responses:
        '200':
          description: The created zone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
  /zones/{id}:
    get:
      operationId: getZone
      tags:
        - Zones
      summary: Retrieve a zone
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested zone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
    put:
      operationId: updateZone
      tags:
        - Zones
      summary: Update a zone
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Zone'
      responses:
        '200':
          description: The updated zone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
    delete:
      operationId: deleteZone
      tags:
        - Zones
      summary: Delete a zone
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the zone was deleted.
  /service-rates:
    get:
      operationId: listServiceRates
      tags:
        - Service Rates
      summary: List service rates
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of service rates.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceRate'
    post:
      operationId: createServiceRate
      tags:
        - Service Rates
      summary: Create a service rate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRate'
      responses:
        '200':
          description: The created service rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRate'
  /service-rates/{id}:
    get:
      operationId: getServiceRate
      tags:
        - Service Rates
      summary: Retrieve a service rate
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested service rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRate'
    delete:
      operationId: deleteServiceRate
      tags:
        - Service Rates
      summary: Delete a service rate
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the service rate was deleted.
  /service-quotes:
    post:
      operationId: createServiceQuote
      tags:
        - Service Rates
      summary: Generate a delivery quote
      description: >-
        Calculates a delivery quote from configured service rates for a
        given pickup, dropoff, and payload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceQuoteRequest'
      responses:
        '200':
          description: The generated service quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuote'
  /tracking/{trackingNumber}:
    get:
      operationId: getTracking
      tags:
        - Tracking
      summary: Retrieve tracking status
      description: >-
        Returns tracking status and activity for a tracking number associated
        with an order or entity.
      parameters:
        - name: trackingNumber
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The tracking status and activity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingStatus'
  /webhook-endpoints:
    get:
      operationId: listWebhookEndpoints
      tags:
        - Webhooks
      summary: List webhook endpoints
      responses:
        '200':
          description: A list of webhook endpoints.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookEndpoint'
    post:
      operationId: createWebhookEndpoint
      tags:
        - Webhooks
      summary: Create a webhook endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpoint'
      responses:
        '200':
          description: The created webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
  /webhook-endpoints/{id}:
    get:
      operationId: getWebhookEndpoint
      tags:
        - Webhooks
      summary: Retrieve a webhook endpoint
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
    delete:
      operationId: deleteWebhookEndpoint
      tags:
        - Webhooks
      summary: Delete a webhook endpoint
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Confirmation the webhook endpoint was deleted.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key passed as a Bearer token in the Authorization header. Test
        keys are prefixed flb_test_ and live keys flb_live_.
  parameters:
    id:
      name: id
      in: path
      required: true
      description: The unique public identifier of the resource.
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Number of records to return (default 25, max 100).
      schema:
        type: integer
        default: 25
        maximum: 100
    offset:
      name: offset
      in: query
      description: Number of records to skip for pagination.
      schema:
        type: integer
        default: 0
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          description: Lifecycle status (created, dispatched, en route, completed, canceled).
        pickup:
          type: string
          description: Public ID of the pickup place.
        dropoff:
          type: string
          description: Public ID of the dropoff place.
        driver_assigned:
          type: string
          description: Public ID of the assigned driver.
        notes:
          type: string
        scheduled_at:
          type: string
          format: date-time
        entities:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
        tracking_number:
          type: string
        created_at:
          type: string
          format: date-time
    OrderCreateRequest:
      type: object
      properties:
        pickup:
          type: string
        dropoff:
          type: string
        notes:
          type: string
        scheduled_at:
          type: string
          format: date-time
        entities:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
    Entity:
      type: object
      description: A payload item within an order.
      properties:
        destination:
          type: string
        name:
          type: string
        description:
          type: string
        currency:
          type: string
        price:
          type: number
    Place:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        street1:
          type: string
        city:
          type: string
        province:
          type: string
        postal_code:
          type: string
        country:
          type: string
        latitude:
          type: number
        longitude:
          type: number
    Contact:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        title:
          type: string
        email:
          type: string
        phone:
          type: string
        type:
          type: string
          description: Contact type (customer or contact).
    Driver:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        status:
          type: string
        vehicle:
          type: string
          description: Public ID of the assigned vehicle.
        location:
          $ref: '#/components/schemas/Point'
    Vehicle:
      type: object
      properties:
        id:
          type: string
        make:
          type: string
        model:
          type: string
        year:
          type: integer
        plate_number:
          type: string
        vin:
          type: string
        status:
          type: string
    Fleet:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
        drivers:
          type: array
          items:
            type: string
        vehicles:
          type: array
          items:
            type: string
    Zone:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        border:
          type: object
          description: GeoJSON polygon describing the zone boundary.
    ServiceRate:
      type: object
      properties:
        id:
          type: string
        service_name:
          type: string
        service_type:
          type: string
          description: Rate model (e.g. fixed_meters, per_drop, parcel).
        currency:
          type: string
        base_fee:
          type: number
        per_meter_flat_rate_fee:
          type: number
    ServiceQuoteRequest:
      type: object
      properties:
        pickup:
          type: string
        dropoff:
          type: string
        service_type:
          type: string
        entities:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
    ServiceQuote:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
        currency:
          type: string
        service_rate:
          type: string
    TrackingStatus:
      type: object
      properties:
        tracking_number:
          type: string
        status:
          type: string
        code:
          type: string
        location:
          $ref: '#/components/schemas/Point'
        updated_at:
          type: string
          format: date-time
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        events:
          type: array
          items:
            type: string
        status:
          type: string
        version:
          type: string
    Point:
      type: object
      properties:
        type:
          type: string
          example: Point
        coordinates:
          type: array
          items:
            type: number
          description: '[longitude, latitude]'