{"openapi":"3.1.0","info":{"title":"United Logistics API","version":"0.1.0","description":"Industry-grade public API for fleet, fuel, and toll operations. Every endpoint is scoped to the organization owning the API key. Authentication: bearer API key (`ulk_<prefix>_<secret>`). Rate limit: 60 requests/minute/key by default (override per key via the dashboard).","contact":{"name":"United Logistics Engineering","email":"sfuentes@solidarityagents.com"}},"servers":[{"url":"http://localhost:3000/api/v1","description":"Local development (npm run dev)"},{"url":"https://unitedpetroleum.app/api/v1","description":"Production"},{"url":"https://app.unitedlogistics.com.do/api/v1","description":"Configured (NEXT_PUBLIC_APP_URL)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"ulk_<prefix>_<secret>","description":"Send your API key in the Authorization header: `Authorization: Bearer ulk_<prefix>_<secret>`. New keys are created in Settings > API Keys. Legacy `ak_...` keys from older dashboard builds are also accepted."}},"schemas":{"ErrorObject":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"unauthorized"},"message":{"type":"string","example":"Missing Authorization header."},"details":{}},"required":["code","message"]}},"required":["error"]},"PaginationCursor":{"type":"object","properties":{"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Null when there are no more results.","example":"eyJpZCI6IjAxQUI..."},"has_more":{"type":"boolean"}},"required":["next_cursor","has_more"]},"Provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}],"description":"Registered: karma (Karma sync), internal (created in the app). Custom integrators use a stable lowercase slug.","example":"karma"},"EnabledModules":{"type":"object","properties":{"paso_rapido":{"type":"boolean"},"telematics":{"type":"boolean"},"pois":{"type":"boolean"},"fuel_management":{"type":"boolean"}}},"Organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"avatar_url":{"type":["string","null"]},"enabled_modules":{"$ref":"#/components/schemas/EnabledModules"},"project_purge_grace_days":{"type":["integer","null"]},"archived_at":{"type":["string","null"]},"members_count":{"type":"integer","minimum":0},"projects_count":{"type":"integer","minimum":0},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","avatar_url","enabled_modules","project_purge_grace_days","archived_at","members_count","projects_count","created_at","updated_at"]},"OrganizationMeResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Organization"}},"required":["data"]},"Vehicle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"integer"},"provider":{"$ref":"#/components/schemas/Provider"},"org_id":{"type":"string","format":"uuid"},"fleet_id":{"type":["integer","null"]},"device_id":{"type":["integer","null"]},"time_zone":{"type":["string","null"],"enum":["America/Santo_Domingo","America/New_York","America/Puerto_Rico","America/Bogota","America/Caracas","America/Panama","America/Mexico_City","America/Guatemala","America/Chicago","America/Denver","America/Phoenix","America/Los_Angeles","America/Havana","America/Jamaica","America/Lima","America/Santiago","America/Buenos_Aires","America/Sao_Paulo","UTC"],"description":"IANA time zone for trip and event timestamps (e.g. America/Santo_Domingo).","example":"America/Santo_Domingo"},"number":{"type":["string","null"]},"license_plate":{"type":["string","null"]},"title":{"type":["string","null"]},"type":{"type":["string","null"],"description":"Raw vehicle type string as reported by the provider (e.g. 'truck', 'sedan')."},"sub_type":{"type":["string","null"]},"year":{"type":["string","null"]},"color":{"type":["string","null"]},"sim_imsi":{"type":["string","null"]},"sim_phone":{"type":["string","null"]},"provider_metadata":{"description":"Free-form provider-specific structured metadata. Schema varies by provider."},"fetch_timestamp":{"type":["string","null"]},"icon_url":{"type":["string","null"]},"maintenance_status":{"type":["boolean","null"]},"vehicle_type":{"type":["string","null"],"description":"User-curated vehicle classification used for analytics (overrides `type`)."},"deactivated_at":{"type":["string","null"]},"deactivation_reason":{"type":["string","null"]}},"required":["id","external_id","provider","org_id","fleet_id","device_id","time_zone","number","license_plate","title","type","sub_type","year","color","sim_imsi","sim_phone","fetch_timestamp","icon_url","maintenance_status","vehicle_type","deactivated_at","deactivation_reason"]},"CreateVehicleResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Vehicle"}},"required":["data"]},"CreateVehicleRequest":{"type":"object","properties":{"external_id":{"type":"integer","exclusiveMinimum":0},"provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}]},"fleet_id":{"type":["integer","null"],"exclusiveMinimum":0},"device_id":{"type":["integer","null"]},"time_zone":{"type":"string","enum":["America/Santo_Domingo","America/New_York","America/Puerto_Rico","America/Bogota","America/Caracas","America/Panama","America/Mexico_City","America/Guatemala","America/Chicago","America/Denver","America/Phoenix","America/Los_Angeles","America/Havana","America/Jamaica","America/Lima","America/Santiago","America/Buenos_Aires","America/Sao_Paulo","UTC"]},"number":{"type":["string","null"],"maxLength":200},"license_plate":{"type":["string","null"],"maxLength":100},"title":{"type":["string","null"],"maxLength":200},"type":{"type":["string","null"],"maxLength":100},"sub_type":{"type":["string","null"],"maxLength":100},"year":{"type":["string","null"],"maxLength":20},"color":{"type":["string","null"],"maxLength":50},"sim_imsi":{"type":["string","null"],"maxLength":50},"sim_phone":{"type":["string","null"],"maxLength":50},"vehicle_type":{"type":["string","null"],"maxLength":100},"provider_metadata":{}},"required":["external_id","provider"]},"VehicleListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"VehicleResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Vehicle"}},"required":["data"]},"UpdateVehicleRequest":{"type":"object","properties":{"external_id":{"type":"integer","exclusiveMinimum":0},"provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}]},"fleet_id":{"type":["integer","null"],"exclusiveMinimum":0},"device_id":{"type":["integer","null"]},"time_zone":{"type":["string","null"],"enum":["America/Santo_Domingo","America/New_York","America/Puerto_Rico","America/Bogota","America/Caracas","America/Panama","America/Mexico_City","America/Guatemala","America/Chicago","America/Denver","America/Phoenix","America/Los_Angeles","America/Havana","America/Jamaica","America/Lima","America/Santiago","America/Buenos_Aires","America/Sao_Paulo","UTC"]},"number":{"type":["string","null"],"maxLength":200},"license_plate":{"type":["string","null"],"maxLength":100},"title":{"type":["string","null"],"maxLength":200},"type":{"type":["string","null"],"maxLength":100},"sub_type":{"type":["string","null"],"maxLength":100},"year":{"type":["string","null"],"maxLength":20},"color":{"type":["string","null"],"maxLength":50},"sim_imsi":{"type":["string","null"],"maxLength":50},"sim_phone":{"type":["string","null"],"maxLength":50},"vehicle_type":{"type":["string","null"],"maxLength":100},"provider_metadata":{},"maintenance_status":{"type":["boolean","null"]},"reactivate":{"type":"boolean"}}},"MapVehicleLocation":{"type":"object","properties":{"message_id":{"type":"integer"},"vehicle_id":{"type":"integer"},"carnumber":{"type":"string"},"device_id":{"type":"string"},"extra":{"type":"string"},"edt":{"type":"string"},"eid":{"type":"integer"},"latitude":{"type":"number"},"longitude":{"type":"number"},"spd":{"type":"number"},"head":{"type":"number"},"odo":{"type":"number"},"alt":{"type":"number"},"eng":{"type":"integer"},"driver_id":{"type":["integer","null"],"description":"Provider driver external_id at time of snapshot (`drivers.external_id`).","example":4821},"car_title":{"type":"string"},"license_plate":{"type":"string"},"icon_url":{"type":"string"},"car_type":{"type":"string"},"sub_type":{"type":"string"}},"required":["message_id","vehicle_id","carnumber","device_id","edt","eid","latitude","longitude","spd","head","odo","alt"]},"VehicleLocationResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"integer"},"provider":{"type":"string"},"location":{"$ref":"#/components/schemas/MapVehicleLocation"},"location_updated_at":{"type":"string"}},"required":["id","external_id","provider","location","location_updated_at"]}},"required":["data"]},"VehicleLocationUpdateRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"integer","exclusiveMinimum":0},"provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}]},"message_id":{"type":"integer"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"edt":{"type":"string"},"eid":{"type":"integer"},"spd":{"type":"number"},"head":{"type":"number"},"odo":{"type":"number"},"alt":{"type":"number"},"eng":{"type":"integer","minimum":0,"maximum":1},"driver_id":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Provider driver external_id currently operating this vehicle (`drivers.external_id`). Optional — pass `null` to clear.","example":4821},"extra":{"type":["string","null"]},"device_id":{"type":["string","null"]},"carnumber":{"type":["string","null"]}},"required":["message_id","latitude","longitude"]},"VehicleLocationListResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/MapVehicleLocation"}},"total":{"type":"integer"}},"required":["locations","total"]}},"required":["data"]},"Driver":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"integer","description":"Org-scoped integer id used as the natural key when paired with `provider`."},"provider":{"$ref":"#/components/schemas/Provider"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"driver_key":{"type":"string","description":"Unique RFID/credential the driver presents on the in-vehicle device."},"license_number":{"type":["string","null"]},"profile_picture_url":{"type":["string","null"]},"status":{"type":["string","null"]},"phone_number":{"type":["string","null"]},"email":{"type":["string","null"]},"notes":{"type":["string","null"]},"deactivated_at":{"type":["string","null"]},"deactivation_reason":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","external_id","provider","org_id","name","driver_key","license_number","profile_picture_url","status","phone_number","email","notes","deactivated_at","deactivation_reason","created_at","updated_at"]},"DriverListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"DriverResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]},"CreateDriverRequest":{"type":"object","properties":{"external_id":{"type":"integer","exclusiveMinimum":0},"provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}]},"name":{"type":"string","minLength":1,"maxLength":200},"driver_key":{"type":"string","minLength":1,"maxLength":200},"license_number":{"type":["string","null"],"maxLength":100},"profile_picture_url":{"type":["string","null"],"format":"uri"},"status":{"type":"string","enum":["active","inactive","on_leave","suspended"]},"phone_number":{"type":["string","null"],"maxLength":50},"email":{"anyOf":[{"type":["string","null"],"maxLength":200,"format":"email"},{"type":"string","enum":[""]},{"type":"null"}]},"notes":{"type":["string","null"],"maxLength":2000}},"required":["external_id","provider","name","driver_key"]},"UpdateDriverRequest":{"type":"object","properties":{"external_id":{"type":"integer","exclusiveMinimum":0},"provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}]},"name":{"type":"string","minLength":1,"maxLength":200},"driver_key":{"type":"string","minLength":1,"maxLength":200},"license_number":{"type":["string","null"],"maxLength":100},"profile_picture_url":{"type":["string","null"],"format":"uri"},"status":{"type":"string","enum":["active","inactive","on_leave","suspended"]},"phone_number":{"type":["string","null"],"maxLength":50},"email":{"anyOf":[{"type":["string","null"],"maxLength":200,"format":"email"},{"type":"string","enum":[""]},{"type":"null"}]},"notes":{"type":["string","null"],"maxLength":2000},"reactivate":{"type":"boolean"}}},"Event":{"type":"object","properties":{"id":{"type":"integer"},"provider":{"$ref":"#/components/schemas/Provider"},"org_id":{"type":"string"},"fleet_id":{"type":["integer","null"]},"vehicle_external_id":{"type":"integer","description":"The provider's id for the vehicle that emitted this event. Pair with /api/v1/vehicles?include_inactive=true to resolve."},"device_id":{"type":["string","null"]},"external_message_id":{"type":["integer","null"],"description":"Provider message id. Stable per `fleet_id`."},"event_date":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"eid":{"type":["integer","null"],"description":"Provider event-type code."},"speed_kph":{"type":["number","null"]},"heading_deg":{"type":["number","null"]},"odometer_km":{"type":["number","null"]},"altitude_m":{"type":["number","null"]},"engine_status":{"type":["number","null"]},"ignition_status":{"type":["number","null"]},"extra":{"type":["string","null"]},"inserted_at":{"type":"string"}},"required":["id","provider","org_id","fleet_id","vehicle_external_id","device_id","external_message_id","event_date","latitude","longitude","eid","speed_kph","heading_deg","odometer_km","altitude_m","engine_status","ignition_status","extra","inserted_at"]},"EventListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"EventBulkCreateResponse":{"type":"object","properties":{"inserted":{"type":"integer"},"skipped":{"type":"integer"},"ids":{"type":"array","items":{"type":"integer"}}},"required":["inserted","skipped","ids"]},"EventBulkCreateRequest":{"anyOf":[{"type":"object","properties":{"vehicle_external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider vehicle id (= `vehicles.external_id`).","example":12345},"fleet_id":{"type":"integer","exclusiveMinimum":0,"description":"Fleet (provider account) scope. Required on each event; used for access validation.","example":1029},"provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}],"description":"Telematics provider slug (e.g. `karma`, `queclink`, custom integrator slug).","example":"karma"},"external_message_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider message id. Required for idempotent bulk inserts; unique per `fleet_id`.","example":55001234},"event_date":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the event occurred.","example":"2026-05-15T14:32:10.000Z"},"device_id":{"type":["string","null"],"maxLength":255,"example":"GPS-DEV-001"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"eid":{"type":["integer","null"],"description":"Provider event-type code.","example":1},"speed_kph":{"type":["number","null"],"minimum":0},"heading_deg":{"type":["number","null"],"minimum":0,"maximum":360},"odometer_km":{"type":["number","null"],"minimum":0},"altitude_m":{"type":["number","null"]},"engine_status":{"type":["integer","null"]},"ignition_status":{"type":["integer","null"]},"extra":{"type":["string","null"],"maxLength":4096,"description":"Opaque provider payload (driver key, raw extras, etc.)."}},"required":["vehicle_external_id","fleet_id","provider","external_message_id","event_date"]},{"type":"array","items":{"type":"object","properties":{"vehicle_external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider vehicle id (= `vehicles.external_id`).","example":12345},"fleet_id":{"type":"integer","exclusiveMinimum":0,"description":"Fleet (provider account) scope. Required on each event; used for access validation.","example":1029},"provider":{"anyOf":[{"type":"string","enum":["karma","internal"]},{"type":"string","pattern":"^[a-z][a-z0-9][a-z0-9_-]{0,62}$"}],"description":"Telematics provider slug (e.g. `karma`, `queclink`, custom integrator slug).","example":"karma"},"external_message_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider message id. Required for idempotent bulk inserts; unique per `fleet_id`.","example":55001234},"event_date":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the event occurred.","example":"2026-05-15T14:32:10.000Z"},"device_id":{"type":["string","null"],"maxLength":255,"example":"GPS-DEV-001"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"eid":{"type":["integer","null"],"description":"Provider event-type code.","example":1},"speed_kph":{"type":["number","null"],"minimum":0},"heading_deg":{"type":["number","null"],"minimum":0,"maximum":360},"odometer_km":{"type":["number","null"],"minimum":0},"altitude_m":{"type":["number","null"]},"engine_status":{"type":["integer","null"]},"ignition_status":{"type":["integer","null"]},"extra":{"type":["string","null"],"maxLength":4096,"description":"Opaque provider payload (driver key, raw extras, etc.)."}},"required":["vehicle_external_id","fleet_id","provider","external_message_id","event_date"]},"minItems":1,"maxItems":1000}]},"EventBulkDeleteResponse":{"type":"object","properties":{"deleted":{"type":"integer"},"not_found":{"type":"integer"},"ids":{"type":"array","items":{"type":"integer"}}},"required":["deleted","not_found","ids"]},"EventBulkDeleteRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"minItems":1,"maxItems":1000,"description":"Numeric event ids to delete. Scoped to the API key's organization.","example":[987654321,987654322]}},"required":["ids"]},"EventResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Event"}},"required":["data"]},"Trip":{"type":"object","properties":{"id":{"type":"integer","description":"Internal numeric id. Stable per org.","example":482219},"external_id":{"type":"integer","description":"Provider trip id (legacy `trip_id`). Stable per `org_id`.","example":9876543},"provider":{"$ref":"#/components/schemas/Provider"},"org_id":{"type":"string"},"vehicle_external_id":{"type":"integer","description":"Provider vehicle id (legacy `vehicle_id`).","example":12345},"driver_external_id":{"type":["integer","null"],"description":"Local driver id (legacy `driver_id`).","example":4421},"device_id":{"type":["string","null"]},"vehicle_number":{"type":["string","null"]},"trip_active":{"type":["integer","null"]},"start_message_id":{"type":["integer","null"]},"start_date":{"type":["string","null"]},"start_latitude":{"type":["number","null"]},"start_longitude":{"type":["number","null"]},"start_odometer_km":{"type":["number","null"]},"stop_message_id":{"type":["integer","null"]},"stop_date":{"type":["string","null"]},"stop_latitude":{"type":["number","null"]},"stop_longitude":{"type":["number","null"]},"stop_odometer_km":{"type":["number","null"]},"duration_s":{"type":["integer","null"]},"distance_km":{"type":["number","null"]},"duration_night_s":{"type":["integer","null"]},"distance_night_km":{"type":["number","null"]},"max_speed_kph":{"type":["number","null"]},"driving_score":{"type":["integer","null"]},"eco_score":{"type":["number","null"]},"fetch_timestamp":{"type":["string","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","external_id","provider","org_id","vehicle_external_id","driver_external_id","device_id","vehicle_number","trip_active","start_message_id","start_date","start_latitude","start_longitude","start_odometer_km","stop_message_id","stop_date","stop_latitude","stop_longitude","stop_odometer_km","duration_s","distance_km","duration_night_s","distance_night_km","max_speed_kph","driving_score","eco_score","fetch_timestamp","created_at","updated_at"]},"TripListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Trip"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"CreateTripResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]},"CreateTripRequest":{"type":"object","properties":{"external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider trip id (legacy `trip_id`). Unique per `org_id`.","example":9876543},"vehicle_external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider vehicle id (legacy `vehicle_id`).","example":12345},"provider":{"type":"string","minLength":1,"maxLength":64,"default":"karma","description":"Telematics provider slug. Defaults to `karma`.","example":"karma"},"driver_external_id":{"type":["integer","null"],"description":"Provider driver id, if known.","example":4421},"device_id":{"type":["string","null"],"maxLength":255,"example":"GPS-DEV-001"},"vehicle_number":{"type":["string","null"],"maxLength":255,"description":"Denormalized vehicle number at the time of the trip.","example":"UL-021"},"trip_active":{"type":["integer","null"]},"start_message_id":{"type":["integer","null"]},"start_date":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the trip started.","example":"2026-05-26T08:32:00.000Z"},"start_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"start_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"start_odometer_km":{"type":["number","null"],"minimum":0},"stop_message_id":{"type":["integer","null"]},"stop_date":{"type":["string","null"],"format":"date-time"},"stop_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"stop_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"stop_odometer_km":{"type":["number","null"],"minimum":0},"duration_s":{"type":["integer","null"],"minimum":0},"distance_km":{"type":["number","null"],"minimum":0},"duration_night_s":{"type":["integer","null"],"minimum":0},"distance_night_km":{"type":["number","null"],"minimum":0},"max_speed_kph":{"type":["number","null"],"minimum":0},"driving_score":{"type":["integer","null"],"minimum":0,"maximum":100},"eco_score":{"type":["number","null"],"minimum":0,"maximum":100}},"required":["external_id","vehicle_external_id","start_date"]},"TripBulkImportResponse":{"type":"object","properties":{"inserted":{"type":"integer","description":"Number of trips newly created.","example":18},"updated":{"type":"integer","description":"Number of existing trips updated.","example":2},"ids":{"type":"array","items":{"type":"integer"},"description":"Internal ids of every imported (inserted or updated) trip."}},"required":["inserted","updated","ids"]},"TripBulkImportRequest":{"anyOf":[{"type":"object","properties":{"external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider trip id (legacy `trip_id`). Unique per `org_id`.","example":9876543},"vehicle_external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider vehicle id (legacy `vehicle_id`).","example":12345},"provider":{"type":"string","minLength":1,"maxLength":64,"default":"karma","description":"Telematics provider slug. Defaults to `karma`.","example":"karma"},"driver_external_id":{"type":["integer","null"],"description":"Provider driver id, if known.","example":4421},"device_id":{"type":["string","null"],"maxLength":255,"example":"GPS-DEV-001"},"vehicle_number":{"type":["string","null"],"maxLength":255,"description":"Denormalized vehicle number at the time of the trip.","example":"UL-021"},"trip_active":{"type":["integer","null"]},"start_message_id":{"type":["integer","null"]},"start_date":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the trip started.","example":"2026-05-26T08:32:00.000Z"},"start_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"start_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"start_odometer_km":{"type":["number","null"],"minimum":0},"stop_message_id":{"type":["integer","null"]},"stop_date":{"type":["string","null"],"format":"date-time"},"stop_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"stop_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"stop_odometer_km":{"type":["number","null"],"minimum":0},"duration_s":{"type":["integer","null"],"minimum":0},"distance_km":{"type":["number","null"],"minimum":0},"duration_night_s":{"type":["integer","null"],"minimum":0},"distance_night_km":{"type":["number","null"],"minimum":0},"max_speed_kph":{"type":["number","null"],"minimum":0},"driving_score":{"type":["integer","null"],"minimum":0,"maximum":100},"eco_score":{"type":["number","null"],"minimum":0,"maximum":100}},"required":["external_id","vehicle_external_id","start_date"]},{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider trip id (legacy `trip_id`). Unique per `org_id`.","example":9876543},"vehicle_external_id":{"type":"integer","exclusiveMinimum":0,"description":"Provider vehicle id (legacy `vehicle_id`).","example":12345},"provider":{"type":"string","minLength":1,"maxLength":64,"default":"karma","description":"Telematics provider slug. Defaults to `karma`.","example":"karma"},"driver_external_id":{"type":["integer","null"],"description":"Provider driver id, if known.","example":4421},"device_id":{"type":["string","null"],"maxLength":255,"example":"GPS-DEV-001"},"vehicle_number":{"type":["string","null"],"maxLength":255,"description":"Denormalized vehicle number at the time of the trip.","example":"UL-021"},"trip_active":{"type":["integer","null"]},"start_message_id":{"type":["integer","null"]},"start_date":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the trip started.","example":"2026-05-26T08:32:00.000Z"},"start_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"start_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"start_odometer_km":{"type":["number","null"],"minimum":0},"stop_message_id":{"type":["integer","null"]},"stop_date":{"type":["string","null"],"format":"date-time"},"stop_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"stop_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"stop_odometer_km":{"type":["number","null"],"minimum":0},"duration_s":{"type":["integer","null"],"minimum":0},"distance_km":{"type":["number","null"],"minimum":0},"duration_night_s":{"type":["integer","null"],"minimum":0},"distance_night_km":{"type":["number","null"],"minimum":0},"max_speed_kph":{"type":["number","null"],"minimum":0},"driving_score":{"type":["integer","null"],"minimum":0,"maximum":100},"eco_score":{"type":["number","null"],"minimum":0,"maximum":100}},"required":["external_id","vehicle_external_id","start_date"]},"minItems":1,"maxItems":1000}]},"TripResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]},"UpdateTripRequest":{"type":"object","properties":{"driver_external_id":{"type":["integer","null"]},"device_id":{"type":["string","null"],"maxLength":255},"vehicle_number":{"type":["string","null"],"maxLength":255},"trip_active":{"type":["integer","null"]},"start_message_id":{"type":["integer","null"]},"start_date":{"type":"string","format":"date-time"},"start_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"start_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"start_odometer_km":{"type":["number","null"],"minimum":0},"stop_message_id":{"type":["integer","null"]},"stop_date":{"type":["string","null"],"format":"date-time"},"stop_latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"stop_longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"stop_odometer_km":{"type":["number","null"],"minimum":0},"duration_s":{"type":["integer","null"],"minimum":0},"distance_km":{"type":["number","null"],"minimum":0},"duration_night_s":{"type":["integer","null"],"minimum":0},"distance_night_km":{"type":["number","null"],"minimum":0},"max_speed_kph":{"type":["number","null"],"minimum":0},"driving_score":{"type":["integer","null"],"minimum":0,"maximum":100},"eco_score":{"type":["number","null"],"minimum":0,"maximum":100}}},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"integer","description":"Provider project id (legacy `fleet_id`)."},"provider":{"$ref":"#/components/schemas/Provider"},"name":{"type":["string","null"]},"org_id":{"type":["string","null"],"format":"uuid"},"fetch_timestamp":{"type":["string","null"]},"deactivated_at":{"type":["string","null"]},"deactivation_reason":{"type":["string","null"]}},"required":["id","external_id","provider","name","org_id","fetch_timestamp","deactivated_at","deactivation_reason"]},"ProjectListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"ProjectResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"Brand":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"green_max":{"type":["integer","null"],"description":"Upper bound (kph) for the 'green' speed bucket."},"yellow_max":{"type":["integer","null"],"description":"Upper bound (kph) for the 'yellow' speed bucket."},"red_threshold":{"type":["integer","null"],"description":"Lower bound (kph) where the 'red' (over-speed) bucket begins."},"idle_max_percentage":{"type":["number","null"],"description":"Maximum allowed idle-time percentage before the vehicle is flagged."},"fuel_efficiency_min":{"type":["number","null"]},"fuel_efficiency_max":{"type":["number","null"]},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","name","description","green_max","yellow_max","red_threshold","idle_max_percentage","fuel_efficiency_min","fuel_efficiency_max","is_default","created_at","updated_at"]},"BrandListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"GpsFleet":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"integer","description":"Provider fleet id (legacy Karma project id)."},"provider":{"$ref":"#/components/schemas/Provider"},"name":{"type":["string","null"]},"org_id":{"type":["string","null"],"format":"uuid"},"fetch_timestamp":{"type":["string","null"]},"deactivated_at":{"type":["string","null"]},"deactivation_reason":{"type":["string","null"]}},"required":["id","external_id","provider","name","org_id","fetch_timestamp","deactivated_at","deactivation_reason"]},"GpsFleetListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GpsFleet"}},"pagination":{"type":"object","properties":{"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["next_cursor","has_more"]}},"required":["data","pagination"]},"GpsFleetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GpsFleet"}},"required":["data"]},"POI":{"type":"object","properties":{"id":{"type":"integer","description":"Internal numeric POI id. Stable for the lifetime of the POI.","example":42},"org_id":{"type":"string","format":"uuid"},"fleet_id":{"type":["integer","null"],"description":"Fleet (provider account) this POI is scoped to.","example":1029},"name":{"type":"string","example":"Estación La Vega"},"description":{"type":["string","null"]},"latitude":{"type":"number","example":19.221},"longitude":{"type":"number","example":-70.529},"image_url":{"type":["string","null"]},"geometry_type":{"type":"string","enum":["circle","polygon"],"description":"`circle` for radius-based geofences, `polygon` for arbitrary shapes.","example":"circle"},"geofence_radius_meters":{"type":["integer","null"],"description":"Radius in meters for circle geofences (10-1000). `null` for polygons.","example":50},"polygon_coordinates":{"type":["array","null"],"items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},"description":"Polygon vertices as `[latitude, longitude]` tuples. Closed automatically (no need to repeat the first point).","example":[[18.5,-69.9],[18.51,-69.9],[18.51,-69.89],[18.5,-69.89]]},"tags":{"type":"array","items":{"type":"string"},"description":"User-defined tags used for filtering and reports.","example":["estacion","gasolinera"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","fleet_id","name","description","latitude","longitude","image_url","geometry_type","geofence_radius_meters","polygon_coordinates","tags","created_at","updated_at"]},"POIListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/POI"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"CreatePOIResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/POI"}},"required":["data"]},"CreatePOIRequest":{"type":"object","properties":{"fleet_id":{"type":"integer","exclusiveMinimum":0,"description":"Fleet (provider account) this POI is scoped to.","example":1029},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name.","example":"Cliente Altice – Bávaro"},"description":{"type":["string","null"],"maxLength":2000,"description":"Free-form description.","example":"Punto de entrega cliente Altice zona este"},"image_url":{"type":["string","null"],"format":"uri","description":"Public image URL (typically Supabase storage `poi-images` bucket).","example":null},"geometry_type":{"type":"string","enum":["circle","polygon"],"default":"circle","description":"`circle` for radius-based geofences, `polygon` for arbitrary shapes.","example":"circle"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Required for `circle`. For `polygon`, derived from centroid if omitted.","example":18.6792},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Required for `circle`. For `polygon`, derived from centroid if omitted.","example":-68.4014},"geofence_radius_meters":{"type":["integer","null"],"minimum":10,"maximum":1000,"description":"Required for `circle`. 10–1000 meters. `null` for polygons.","example":250},"polygon_coordinates":{"type":["array","null"],"items":{"type":"array","prefixItems":[{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180}]},"minItems":3,"maxItems":500,"description":"Required for `polygon`. At least 3 `[lat, lng]` vertices; the polygon is closed automatically.","example":[[18.5012,-69.9305],[18.5012,-69.929],[18.5,-69.929],[18.5,-69.9305]]},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":32,"description":"User-defined tags for filtering and reports.","example":["cliente","distribución-este"]}},"required":["fleet_id","name"]},"POIResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/POI"}},"required":["data"]},"UpdatePOIRequest":{"type":"object","properties":{"fleet_id":{"type":"integer","exclusiveMinimum":0,"example":1029},"name":{"type":"string","minLength":1,"maxLength":255,"example":"Cliente Altice – Bávaro"},"description":{"type":["string","null"],"maxLength":2000,"example":"Actualizado: nuevo punto de entrega"},"image_url":{"type":["string","null"],"format":"uri","example":null},"geometry_type":{"type":"string","enum":["circle","polygon"],"example":"circle"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":18.6792},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-68.4014},"geofence_radius_meters":{"type":["integer","null"],"minimum":10,"maximum":1000,"example":300},"polygon_coordinates":{"type":["array","null"],"items":{"type":"array","prefixItems":[{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180}]},"minItems":3,"maxItems":500},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":32,"example":["cliente","vip"]}}},"POIVisit":{"type":"object","properties":{"id":{"type":"integer","example":9183721},"org_id":{"type":"string","format":"uuid","example":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1"},"poi_id":{"type":"integer","example":481},"vehicle_external_id":{"type":"integer","example":16444},"stay_id":{"type":["integer","null"],"example":9183714},"visit_start":{"type":["string","null"],"example":"2026-05-20T13:11:03.412Z"},"visit_end":{"type":["string","null"],"example":"2026-05-20T14:42:51.000Z"},"duration_minutes":{"type":["integer","null"],"example":92},"poi_name":{"type":["string","null"],"example":"Cliente Altice – Bávaro"},"poi_tags":{"type":["array","null"],"items":{"type":"string"},"example":["cliente","distribución-este"]},"poi_latitude":{"type":["number","null"],"example":18.6792},"poi_longitude":{"type":["number","null"],"example":-68.4014},"poi_image_url":{"type":["string","null"],"example":null},"vehicle_number":{"type":["string","null"],"example":"T-114"},"license_plate":{"type":["string","null"],"example":"L139558"},"event_count":{"type":["integer","null"],"example":318},"distance_to_poi_meters":{"type":["number","null"],"example":41.5},"poi_version":{"type":["integer","null"],"example":3},"created_at":{"type":"string","example":"2026-05-20T14:43:01.117Z"},"updated_at":{"type":"string","example":"2026-05-20T14:43:01.117Z"}},"required":["id","org_id","poi_id","vehicle_external_id","stay_id","visit_start","visit_end","duration_minutes","poi_name","poi_tags","poi_latitude","poi_longitude","poi_image_url","vehicle_number","license_plate","event_count","distance_to_poi_meters","poi_version","created_at","updated_at"]},"POIVisitListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/POIVisit"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"Toll":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"image_url":{"type":["string","null"],"description":"Optional photo of the toll booth (legacy `image` column)."},"category_1_price":{"type":["integer","null"]},"category_2_price":{"type":["integer","null"]},"category_3_price":{"type":["integer","null"]},"category_4_price":{"type":["integer","null"]},"category_5_price":{"type":["integer","null"]}},"required":["id","name","latitude","longitude","image_url","category_1_price","category_2_price","category_3_price","category_4_price","category_5_price"]},"TollListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Toll"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"TollCharge":{"type":"object","properties":{"id":{"type":"integer"},"org_id":{"type":["string","null"],"format":"uuid"},"date":{"type":["string","null"]},"amount":{"type":["number","null"]},"tag":{"type":["integer","null"]},"station":{"type":["string","null"]},"type":{"type":["string","null"]},"vehicle_external_id":{"type":["integer","null"],"description":"Vehicle currently attributed to this charge (post-matching). Legacy `vehicle_id`."},"matched_vehicle_external_id":{"type":["integer","null"],"description":"Vehicle the validation pipeline matched against (legacy `matched_vehicle_id`)."},"matched_license_plate":{"type":["string","null"]},"matched_message_id":{"type":["integer","null"]},"csv_id":{"type":["integer","null"]},"import_batch_id":{"type":["string","null"]},"validated_at":{"type":["string","null"]},"validated_by":{"type":["string","null"]},"is_duplicate":{"type":["boolean","null"]},"duplicate_resolution":{"type":["string","null"]},"duplicate_validation_status":{"type":["string","null"]},"category_error":{"type":["boolean","null"]},"category_validation_status":{"type":["string","null"]},"expected_amount":{"type":["number","null"]},"amount_difference":{"type":["number","null"]},"tag_status_at_time":{"type":["string","null"]},"tag_status_error":{"type":["boolean","null"]},"tag_status_validation_status":{"type":["string","null"]},"location_validation_status":{"type":["string","null"]},"distance_meters":{"type":["number","null"]},"time_diff_minutes":{"type":["number","null"]},"fraud_type":{"type":["string","null"]},"fraud_reasons":{"type":["string","null"]},"is_fraudulent":{"type":["boolean","null"]},"validation_status":{"type":["string","null"]},"validation_details":{"type":["string","null"]},"overall_validation_status":{"type":["string","null"]},"assignment_date_used":{"type":["string","null"]},"fleet":{"type":["string","null"]},"manual_revision_status":{"type":["string","null"]},"manual_revision_at":{"type":["string","null"]},"manual_revision_by":{"type":["string","null"]},"manual_revision_comment":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","date","amount","tag","station","type","vehicle_external_id","matched_vehicle_external_id","matched_license_plate","matched_message_id","csv_id","import_batch_id","validated_at","validated_by","is_duplicate","duplicate_resolution","duplicate_validation_status","category_error","category_validation_status","expected_amount","amount_difference","tag_status_at_time","tag_status_error","tag_status_validation_status","location_validation_status","distance_meters","time_diff_minutes","fraud_type","fraud_reasons","is_fraudulent","validation_status","validation_details","overall_validation_status","assignment_date_used","fleet","manual_revision_status","manual_revision_at","manual_revision_by","manual_revision_comment","created_at","updated_at"]},"TollChargeListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TollCharge"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"Tag":{"type":"object","properties":{"id":{"type":"integer"},"org_id":{"type":"string","format":"uuid"},"tag_number":{"type":"integer"},"has_gps":{"type":"boolean"},"vehicle_external_id":{"type":["integer","null"],"description":"External id of the GPS vehicle (legacy `vehicle_id`). Null for non-GPS tags."},"vehicle_title":{"type":["string","null"]},"vehicle_license_plate":{"type":["string","null"]},"category":{"type":"integer"},"assignment_category":{"type":["string","null"]},"type":{"type":"string"},"date":{"type":"string"},"issued_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"status":{"type":"string"},"notes":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","tag_number","has_gps","vehicle_external_id","vehicle_title","vehicle_license_plate","category","assignment_category","type","date","issued_at","expires_at","status","notes","created_at","updated_at"]},"TagListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"CreateTagResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tag"}},"required":["data"]},"CreateTagRequest":{"type":"object","properties":{"tag_number":{"type":"integer","exclusiveMinimum":0},"has_gps":{"type":"boolean","description":"Whether the assigned vehicle is GPS-tracked. Defaults to true."},"vehicle_external_id":{"type":["integer","null"],"exclusiveMinimum":0,"description":"External id of the GPS vehicle (maps to `vehicle_id`). Required when `has_gps` is true."},"vehicle_title":{"type":["string","null"],"maxLength":200,"description":"Free-text label for a non-GPS vehicle. Required when `has_gps` is false."},"vehicle_license_plate":{"type":["string","null"],"maxLength":50,"description":"License plate for a non-GPS vehicle. Required when `has_gps` is false."},"category":{"type":"integer","minimum":1,"maximum":5},"assignment_category":{"type":["string","null"],"maxLength":200},"type":{"type":"string","enum":["corporativo","prepago"]},"date":{"type":"string","description":"Assignment date (YYYY-MM-DD)."},"issued_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"status":{"type":"string","enum":["Valido","Inhabilitado"],"description":"Defaults to `Valido`."},"notes":{"type":["string","null"]}},"required":["tag_number","category","type","date"]},"TagResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tag"}},"required":["data"]},"UpdateTagRequest":{"type":"object","properties":{"tag_number":{"type":"integer","exclusiveMinimum":0},"has_gps":{"type":"boolean"},"vehicle_external_id":{"type":["integer","null"],"exclusiveMinimum":0},"vehicle_title":{"type":["string","null"],"maxLength":200},"vehicle_license_plate":{"type":["string","null"],"maxLength":50},"category":{"type":"integer","minimum":1,"maximum":5},"assignment_category":{"type":["string","null"],"maxLength":200},"type":{"type":"string","enum":["corporativo","prepago"]},"date":{"type":"string"},"issued_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"status":{"type":"string","enum":["Valido","Inhabilitado"]},"notes":{"type":["string","null"]}}},"FuelEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"transaction_date":{"type":["string","null"]},"transaction_id":{"type":["string","null"]},"notes":{"type":["string","null"]},"vehicle_external_id":{"type":["integer","null"]},"vehicle_number":{"type":["string","null"]},"vehicle_name":{"type":["string","null"]},"driver_external_id":{"type":["integer","null"]},"driver_key":{"type":["string","null"]},"name":{"type":["string","null"]},"product_id":{"type":["string","null"],"format":"uuid"},"product_name":{"type":["string","null"]},"product_type":{"type":["string","null"]},"vendor_id":{"type":["string","null"],"format":"uuid"},"vendor_name":{"type":["string","null"]},"vendor_address":{"type":["string","null"]},"gallons":{"type":["number","null"]},"price_per_gallon":{"type":["number","null"]},"total_cost":{"type":["number","null"]},"odometer_reading":{"type":["number","null"]},"previous_odometer_reading":{"type":["number","null"]},"distance_traveled":{"type":["number","null"]},"fuel_efficiency":{"type":["number","null"]},"trip_external_id":{"type":["integer","null"]},"matched_message_id":{"type":["integer","null"]},"gps_odometer_reading":{"type":["number","null"]},"karma_driver_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reference_id":{"type":["string","null"]},"created_by":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","transaction_date","transaction_id","notes","vehicle_external_id","vehicle_number","vehicle_name","driver_external_id","driver_key","name","product_id","product_name","product_type","vendor_id","vendor_name","vendor_address","gallons","price_per_gallon","total_cost","odometer_reading","previous_odometer_reading","distance_traveled","fuel_efficiency","trip_external_id","matched_message_id","gps_odometer_reading","karma_driver_id","source","reference_id","created_by","created_at","updated_at"]},"FuelEntryListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FuelEntry"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"CreateFuelEntryResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuelEntry"}},"required":["data"]},"CreateFuelEntryRequest":{"type":"object","properties":{"vehicle_external_id":{"type":["integer","null"],"description":"Provider vehicle id (legacy `vehicle_id`). Enables trip/GPS matching.","example":16056},"vehicle_number":{"type":"string","minLength":1,"maxLength":255,"description":"Denormalized vehicle number/plate at the time of the refuel.","example":"L18N / L534991"},"vehicle_name":{"type":["string","null"],"maxLength":255},"driver_external_id":{"type":["integer","null"]},"driver_key":{"type":["string","null"],"maxLength":255},"name":{"type":["string","null"],"maxLength":255,"description":"Driver name (denormalized). Defaults to `Desconocido`.","example":"Juan Pérez"},"product_id":{"type":["string","null"],"format":"uuid"},"product_name":{"type":"string","minLength":1,"maxLength":255,"example":"Diesel Regular"},"product_type":{"type":"string","minLength":1,"maxLength":255,"example":"Regular"},"vendor_id":{"type":["string","null"],"format":"uuid"},"vendor_name":{"type":["string","null"],"maxLength":255},"vendor_address":{"type":["string","null"],"maxLength":500},"gallons":{"type":"number","exclusiveMinimum":0,"example":60.008},"price_per_gallon":{"type":"number","minimum":0,"example":224.8},"odometer_reading":{"type":"number","minimum":0,"example":10997},"transaction_date":{"type":["string","null"],"format":"date-time","example":"2026-02-26T03:15:47.000Z"},"transaction_id":{"type":["string","null"],"maxLength":255},"notes":{"type":["string","null"],"maxLength":2000},"source":{"type":["string","null"],"enum":["API","ERM"],"description":"Origin of the entry. `ERM` for manual/UI, `API` for integrations.","example":"API"},"reference_id":{"type":["string","null"],"maxLength":255},"trip_external_id":{"type":["integer","null"]},"matched_message_id":{"type":["integer","null"]},"gps_odometer_reading":{"type":["number","null"],"minimum":0},"karma_driver_id":{"type":["integer","null"]}},"required":["vehicle_number","product_name","product_type","gallons","price_per_gallon"]},"FuelEntryResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuelEntry"}},"required":["data"]},"UpdateFuelEntryRequest":{"type":"object","properties":{"vehicle_number":{"type":"string","minLength":1,"maxLength":255},"vehicle_name":{"type":["string","null"],"maxLength":255},"driver_external_id":{"type":["integer","null"]},"driver_key":{"type":["string","null"],"maxLength":255},"name":{"type":["string","null"],"maxLength":255},"product_id":{"type":["string","null"],"format":"uuid"},"product_name":{"type":"string","minLength":1,"maxLength":255},"product_type":{"type":"string","minLength":1,"maxLength":255},"vendor_id":{"type":["string","null"],"format":"uuid"},"vendor_name":{"type":["string","null"],"maxLength":255},"vendor_address":{"type":["string","null"],"maxLength":500},"gallons":{"type":"number","exclusiveMinimum":0},"price_per_gallon":{"type":"number","minimum":0},"odometer_reading":{"type":"number","minimum":0},"transaction_date":{"type":["string","null"],"format":"date-time"},"transaction_id":{"type":["string","null"],"maxLength":255},"notes":{"type":["string","null"],"maxLength":2000},"source":{"type":["string","null"],"enum":["API","ERM"],"description":"Origin of the entry. `ERM` for manual/UI, `API` for integrations.","example":"API"},"reference_id":{"type":["string","null"],"maxLength":255},"trip_external_id":{"type":["integer","null"]},"matched_message_id":{"type":["integer","null"]},"gps_odometer_reading":{"type":["number","null"],"minimum":0},"karma_driver_id":{"type":["integer","null"]}}},"FuelEntryBulkImportResponse":{"type":"object","properties":{"inserted":{"type":"integer","description":"Number of entries created.","example":42},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids of every created entry."}},"required":["inserted","ids"]},"FuelEntryBulkImportRequest":{"anyOf":[{"$ref":"#/components/schemas/CreateFuelEntryRequest"},{"type":"array","items":{"$ref":"#/components/schemas/CreateFuelEntryRequest"},"minItems":1,"maxItems":1000}]},"FuelProduct":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"product_type":{"type":["string","null"]},"default_price_per_gallon":{"type":["number","null"]},"internal_id":{"type":["string","null"]},"notes":{"type":["string","null"]},"is_active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","name","product_type","default_price_per_gallon","internal_id","notes","is_active","created_at","updated_at"]},"FuelProductListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FuelProduct"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"FuelVendor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"contact_name":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"contact_email":{"type":["string","null"]},"address":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"internal_id":{"type":["string","null"]},"notes":{"type":["string","null"]},"is_active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","name","phone","website","contact_name","contact_phone","contact_email","address","latitude","longitude","internal_id","notes","is_active","created_at","updated_at"]},"FuelVendorListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FuelVendor"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"ScheduledRoute":{"type":"object","properties":{"id":{"type":"integer"},"route_id":{"type":["string","null"],"format":"uuid","description":"Logical route id (groups versions of the same route)."},"org_id":{"type":"string","format":"uuid"},"fleet_id":{"type":["integer","null"]},"name":{"type":"string"},"description":{"type":["string","null"]},"vehicle_external_id":{"type":["integer","null"],"description":"Vehicle assigned to the route (legacy `vehicle_id`)."},"driver_external_id":{"type":["integer","null"]},"status":{"type":["string","null"]},"state":{"type":["string","null"]},"scheduled_start_time":{"type":["string","null"]},"planned_start_at":{"type":["string","null"]},"actual_departure_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"cancelled_at":{"type":["string","null"]},"started_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"estimated_duration_minutes":{"type":["integer","null"]},"actual_duration_minutes":{"type":["integer","null"]},"estimated_distance_km":{"type":["number","null"]},"actual_distance_km":{"type":["number","null"]},"telemetry_health":{"type":["string","null"]},"start_message_id":{"type":["integer","null"]},"end_message_id":{"type":["integer","null"]},"current_message_id":{"type":["integer","null"]},"start_telemetry_timestamp":{"type":["string","null"]},"end_telemetry_timestamp":{"type":["string","null"]},"current_plan_version_id":{"type":["integer","null"]},"scheduler_tolerance_seconds":{"type":["integer","null"]},"flags":{},"notes":{"type":["string","null"]},"created_by_user_id":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","route_id","org_id","fleet_id","name","description","vehicle_external_id","driver_external_id","status","state","scheduled_start_time","planned_start_at","actual_departure_at","completed_at","cancelled_at","started_at","ended_at","estimated_duration_minutes","actual_duration_minutes","estimated_distance_km","actual_distance_km","telemetry_health","start_message_id","end_message_id","current_message_id","start_telemetry_timestamp","end_telemetry_timestamp","current_plan_version_id","scheduler_tolerance_seconds","notes","created_by_user_id","created_at","updated_at"]},"ScheduledRouteListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ScheduledRoute"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]},"SharedTripView":{"type":"object","properties":{"id":{"type":"integer"},"token":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"created_by":{"type":["string","null"]},"filters":{},"created_at":{"type":"string"},"expires_at":{"type":["string","null"]},"last_accessed_at":{"type":["string","null"]},"access_count":{"type":["integer","null"]},"metadata":{}},"required":["id","token","org_id","created_by","created_at","expires_at","last_accessed_at","access_count"]},"SharedTripViewListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SharedTripView"}},"pagination":{"$ref":"#/components/schemas/PaginationCursor"}},"required":["data","pagination"]}},"parameters":{}},"paths":{"/organizations/me":{"get":{"summary":"Get the organization that owns the API key","description":"Returns the organization tied to the bearer API key plus its enabled modules and a couple of headline counts. Use this on integration boot-up to confirm the key is healthy and the org has the modules you expect.","tags":["Organizations"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMeResponse"}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/vehicles":{"post":{"summary":"Create a vehicle","description":"Creates a vehicle for your organization. `external_id` must be unique per org. `time_zone` must be an allowed IANA identifier.","tags":["Vehicles"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVehicleRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVehicleResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"get":{"summary":"List vehicles","description":"Returns a paginated list of vehicles belonging to the API key's organization. Ordered by `external_id` ascending so the cursor is stable. Active (non-deactivated) vehicles only unless `include_inactive=true`.","tags":["Vehicles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-200. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned by a previous call's `pagination.next_cursor`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Set to `true` to include deactivated vehicles. Defaults to `false`."},"required":false,"name":"include_inactive","in":"query"},{"schema":{"type":"string","description":"Filter by GPS provider slug (`karma`, `internal`, or your custom slug). Recommended when syncing a single feed."},"required":false,"name":"provider","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter by provider-scoped external_id (integer). Use with `provider` for natural-key lookup."},"required":false,"name":"external_id","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleListResponse"}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/vehicles/{id}":{"get":{"summary":"Get a vehicle by id","description":"Returns a single vehicle by its internal UUID `id`. To look up by Karma `external_id`, use the list endpoint with a filter.","tags":["Vehicles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleResponse"}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"patch":{"summary":"Update a vehicle","description":"Partially updates a vehicle. Set `reactivate: true` to clear `deactivated_at` and restore an inactive vehicle.","tags":["Vehicles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVehicleRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"delete":{"summary":"Deactivate a vehicle","description":"Soft-deactivates a vehicle by setting `deactivated_at`. The row remains in the database and can be restored with `PATCH` + `reactivate: true`.","tags":["Vehicles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deactivated"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/vehicles/location":{"patch":{"summary":"Update vehicle last-known location","description":"Updates the stored location snapshot for one vehicle. Identify the vehicle by `id` (UUID) or by `external_id` + `provider`. Optional `driver_id` (provider driver external id) may be included when the engine is on. Does not modify unrelated vehicle fields.","tags":["Vehicles"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleLocationUpdateRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleLocationResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/vehicles/locations":{"get":{"summary":"List last-known vehicle locations","description":"Returns stored location snapshots for the org (same field names as the legacy Karma location payload). Used by the live map and integrator diagnostics.","tags":["Vehicles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Comma-separated external_id values. Omit to return all vehicles with a stored location."},"required":false,"name":"external_ids","in":"query"},{"schema":{"type":"string","description":"Optional filter to one provider slug."},"required":false,"name":"provider","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleLocationListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/drivers":{"get":{"summary":"List drivers","description":"Returns a paginated list of drivers for the API key's organization. Drivers are sorted by `external_id` ascending so the cursor is stable.","tags":["Drivers"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-200. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned by a previous call's `pagination.next_cursor`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Set to `true` to include drivers with `deactivated_at` set. Defaults to `false`."},"required":false,"name":"include_inactive","in":"query"},{"schema":{"type":"string","description":"Filter by GPS provider slug (`karma`, `internal`, or your custom slug)."},"required":false,"name":"provider","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter by provider-scoped external_id (integer). Use with `provider` for natural-key lookup."},"required":false,"name":"external_id","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverListResponse"}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"post":{"summary":"Create a driver","description":"Creates a driver for your organization. `(provider, external_id)` must be unique per org. `driver_key` (RFID) must also be unique per org.","tags":["Drivers"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDriverRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/drivers/{id}":{"get":{"summary":"Get a driver by id","description":"Returns a single driver by its internal UUID.","tags":["Drivers"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverResponse"}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Driver not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"patch":{"summary":"Update a driver","description":"Partially updates a driver. Set `reactivate: true` to clear `deactivated_at` and restore an inactive driver.","tags":["Drivers"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDriverRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"delete":{"summary":"Deactivate or delete a driver","description":"Soft-deactivates a driver by setting `deactivated_at`. Pass `?permanent=true` to hard-delete an already-inactive driver.","tags":["Drivers"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Pass `true` to hard-delete (only allowed for inactive drivers)."},"required":false,"name":"permanent","in":"query"}],"responses":{"204":{"description":"Deactivated or deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/events":{"get":{"summary":"List telemetry events","description":"Returns telemetry events scoped to the API key's org. Cursor-paginated on (event_date desc, id desc). For dense historical pulls, prefer narrow time ranges to keep latency low.","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-500. Defaults to 100."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned by a previous call."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter to events emitted by a specific vehicle (provider external id)."},"required":false,"name":"vehicle_external_id","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO timestamp. Only events with `event_date >= start` are returned.","example":"2026-05-01T00:00:00Z"},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO timestamp. Only events with `event_date <= end` are returned.","example":"2026-05-08T00:00:00Z"},"required":false,"name":"end","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListResponse"},"example":{"data":[{"id":987654321,"provider":"karma","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","fleet_id":42,"vehicle_external_id":11964,"device_id":"DEV-001","external_message_id":55001234,"event_date":"2026-05-15T14:32:10.000Z","latitude":18.4861,"longitude":-69.9312,"eid":1,"speed_kph":62.5,"heading_deg":180,"odometer_km":45231.7,"altitude_m":35,"engine_status":1,"ignition_status":1,"extra":null,"inserted_at":"2026-05-15T14:35:00.000Z"}],"pagination":{"next_cursor":"eyJldmVudF9kYXRlIjoi…","has_more":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"limit must be an integer between 1 and 500."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"post":{"summary":"Create telemetry events","description":"Inserts one event object or an array of up to 1000 events. Idempotent on `(external_message_id, fleet_id)` — duplicate rows are skipped. `fleet_id` and `external_message_id` are required on each event.","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBulkCreateRequest"},"examples":{"single":{"summary":"Single event","value":{"vehicle_external_id":11964,"fleet_id":42,"provider":"karma","external_message_id":55001234,"event_date":"2026-05-15T14:32:10.000Z","latitude":18.4861,"longitude":-69.9312,"speed_kph":62.5,"heading_deg":180,"eid":1}},"bulk":{"summary":"Bulk array","value":[{"vehicle_external_id":11964,"fleet_id":42,"provider":"karma","external_message_id":55001234,"event_date":"2026-05-15T14:32:10.000Z","latitude":18.4861,"longitude":-69.9312,"speed_kph":62.5},{"vehicle_external_id":11964,"fleet_id":42,"provider":"karma","external_message_id":55001235,"event_date":"2026-05-15T14:33:10.000Z","latitude":18.487,"longitude":-69.93,"speed_kph":65}]}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBulkCreateResponse"},"example":{"inserted":2,"skipped":0,"ids":[987654321,987654322]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"limit must be an integer between 1 and 500."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"API key lacks the required scope."}}}}},"404":{"description":"Vehicle or fleet not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Evento no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"delete":{"summary":"Bulk delete telemetry events","description":"Permanently deletes up to 1000 events by numeric `id`. Only events belonging to the API key's organization are removed; unknown ids are counted in `not_found` (no error).","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBulkDeleteRequest"},"example":{"ids":[987654321,987654322,987654399]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBulkDeleteResponse"},"example":{"deleted":2,"not_found":1,"ids":[987654321,987654322]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"limit must be an integer between 1 and 500."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"API key lacks the required scope."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/events/{id}":{"get":{"summary":"Get an event by id","description":"Returns a single telemetry event by its numeric `id` (scoped to the API key's organization).","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric event id."},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventResponse"},"example":{"data":{"id":987654321,"provider":"karma","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","fleet_id":42,"vehicle_external_id":11964,"device_id":"DEV-001","external_message_id":55001234,"event_date":"2026-05-15T14:32:10.000Z","latitude":18.4861,"longitude":-69.9312,"eid":1,"speed_kph":62.5,"heading_deg":180,"odometer_km":45231.7,"altitude_m":35,"engine_status":1,"ignition_status":1,"extra":null,"inserted_at":"2026-05-15T14:35:00.000Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"limit must be an integer between 1 and 500."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Evento no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"delete":{"summary":"Delete an event","description":"Permanently deletes a telemetry event.","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric event id."},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"limit must be an integer between 1 and 500."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"API key lacks the required scope."}}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Evento no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/trips":{"get":{"summary":"List trips","description":"Returns trips scoped to the API key's org. Cursor-paginated on `(start_date desc, id desc)`. Filter by vehicle and/or `start_date` range.","tags":["Trips"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-200. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned by a previous call's `pagination.next_cursor`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter by provider vehicle id."},"required":false,"name":"vehicle_external_id","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Return trips whose `start_date` is >= this ISO 8601 timestamp."},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Return trips whose `start_date` is <= this ISO 8601 timestamp."},"required":false,"name":"end","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TripListResponse"},"example":{"data":[{"id":482219,"external_id":9876543,"provider":"karma","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","vehicle_external_id":12345,"driver_external_id":4421,"device_id":"GPS-DEV-001","vehicle_number":"UL-021","trip_active":0,"start_message_id":91827361,"start_date":"2026-05-26T08:32:00.000Z","start_latitude":18.4861,"start_longitude":-69.9312,"start_odometer_km":124530.4,"stop_message_id":91827881,"stop_date":"2026-05-26T10:14:00.000Z","stop_latitude":18.6792,"stop_longitude":-68.4014,"stop_odometer_km":124612.8,"duration_s":6120,"distance_km":82.4,"duration_night_s":0,"distance_night_km":0,"max_speed_kph":104.2,"driving_score":87,"eco_score":72.4,"fetch_timestamp":"2026-05-26T10:14:31.221Z","created_at":"2026-05-26T10:14:31.221Z","updated_at":"2026-05-26T10:14:31.221Z"}],"pagination":{"next_cursor":"eyJzdGFydF9kYXRlIjoiMjAyNi0wNS0yNlQwODozMjowMC4wMDBaIiwiaWQiOjQ4MjIxOX0","has_more":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid trip payload.","details":{"fieldErrors":{"start_date":["start_date must be ISO 8601 datetime"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"post":{"summary":"Create a trip","description":"Creates a trip for your organization. The vehicle (`vehicle_external_id`) must belong to the API key's org. `external_id` must be unique per org.","tags":["Trips"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTripRequest"},"examples":{"minimal":{"summary":"Minimal trip","value":{"external_id":9876543,"vehicle_external_id":12345,"start_date":"2026-05-26T08:32:00.000Z"}},"complete":{"summary":"Complete trip with metrics","value":{"external_id":9876543,"vehicle_external_id":12345,"provider":"karma","driver_external_id":4421,"device_id":"GPS-DEV-001","vehicle_number":"UL-021","start_date":"2026-05-26T08:32:00.000Z","start_latitude":18.4861,"start_longitude":-69.9312,"start_odometer_km":124530.4,"stop_date":"2026-05-26T10:14:00.000Z","stop_latitude":18.6792,"stop_longitude":-68.4014,"stop_odometer_km":124612.8,"duration_s":6120,"distance_km":82.4,"max_speed_kph":104.2,"driving_score":87,"eco_score":72.4}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTripResponse"},"example":{"data":{"id":482219,"external_id":9876543,"provider":"karma","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","vehicle_external_id":12345,"driver_external_id":4421,"device_id":"GPS-DEV-001","vehicle_number":"UL-021","trip_active":0,"start_message_id":91827361,"start_date":"2026-05-26T08:32:00.000Z","start_latitude":18.4861,"start_longitude":-69.9312,"start_odometer_km":124530.4,"stop_message_id":91827881,"stop_date":"2026-05-26T10:14:00.000Z","stop_latitude":18.6792,"stop_longitude":-68.4014,"stop_odometer_km":124612.8,"duration_s":6120,"distance_km":82.4,"duration_night_s":0,"distance_night_km":0,"max_speed_kph":104.2,"driving_score":87,"eco_score":72.4,"fetch_timestamp":"2026-05-26T10:14:31.221Z","created_at":"2026-05-26T10:14:31.221Z","updated_at":"2026-05-26T10:14:31.221Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid trip payload.","details":{"fieldErrors":{"start_date":["start_date must be ISO 8601 datetime"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"No tienes permisos para modificar viajes."}}}}},"404":{"description":"Vehicle not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"El vehículo especificado no existe en esta organización."}}}}},"409":{"description":"Trip with this external_id already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"conflict","message":"Ya existe un viaje con ese external_id para esta organización."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/trips/bulk":{"post":{"summary":"Bulk import trips","description":"Imports a single trip or an array of up to 1000 trips for your organization. Idempotent on `(external_id, org_id)`: trips that already exist are updated, the rest are inserted — so you can safely re-send the same batch. Every `vehicle_external_id` must belong to the API key's org. Duplicate `external_id`s within one request are collapsed (last one wins).","tags":["Trips"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TripBulkImportRequest"},"examples":{"bulk":{"summary":"Bulk array","value":[{"external_id":9876543,"vehicle_external_id":12345,"start_date":"2026-05-26T08:32:00.000Z","stop_date":"2026-05-26T10:14:00.000Z","distance_km":82.4,"max_speed_kph":104.2},{"external_id":9876544,"vehicle_external_id":12345,"start_date":"2026-05-26T12:05:00.000Z","stop_date":"2026-05-26T12:48:00.000Z","distance_km":31.7}]},"single":{"summary":"Single trip","value":{"external_id":9876543,"vehicle_external_id":12345,"start_date":"2026-05-26T08:32:00.000Z"}}}}}},"responses":{"200":{"description":"Imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TripBulkImportResponse"},"example":{"inserted":18,"updated":2,"ids":[482219,482220,482221]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid trip payload.","details":{"fieldErrors":{"start_date":["start_date must be ISO 8601 datetime"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"No tienes permisos para modificar viajes."}}}}},"404":{"description":"A referenced vehicle does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"El vehículo especificado no existe en esta organización."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/trips/{id}":{"get":{"summary":"Get a trip by id","description":"Returns a single trip by its numeric `id` (scoped to the API key's organization).","tags":["Trips"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric trip id."},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TripResponse"},"example":{"data":{"id":482219,"external_id":9876543,"provider":"karma","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","vehicle_external_id":12345,"driver_external_id":4421,"device_id":"GPS-DEV-001","vehicle_number":"UL-021","trip_active":0,"start_message_id":91827361,"start_date":"2026-05-26T08:32:00.000Z","start_latitude":18.4861,"start_longitude":-69.9312,"start_odometer_km":124530.4,"stop_message_id":91827881,"stop_date":"2026-05-26T10:14:00.000Z","stop_latitude":18.6792,"stop_longitude":-68.4014,"stop_odometer_km":124612.8,"duration_s":6120,"distance_km":82.4,"duration_night_s":0,"distance_night_km":0,"max_speed_kph":104.2,"driving_score":87,"eco_score":72.4,"fetch_timestamp":"2026-05-26T10:14:31.221Z","created_at":"2026-05-26T10:14:31.221Z","updated_at":"2026-05-26T10:14:31.221Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid trip payload.","details":{"fieldErrors":{"start_date":["start_date must be ISO 8601 datetime"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"404":{"description":"Trip not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Viaje no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"patch":{"summary":"Update a trip","description":"Partially updates a trip. Send only the fields you want to change. `external_id`, `vehicle_external_id`, `provider` and `org_id` cannot be changed once set.","tags":["Trips"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric trip id."},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTripRequest"},"examples":{"assign_driver":{"summary":"Assign driver and update metrics","value":{"driver_external_id":4421,"driving_score":87,"eco_score":72.4}},"close_trip":{"summary":"Close trip with stop info","value":{"stop_date":"2026-05-26T10:14:00.000Z","stop_latitude":18.6792,"stop_longitude":-68.4014,"stop_odometer_km":124612.8,"duration_s":6120,"distance_km":82.4,"max_speed_kph":104.2}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TripResponse"},"example":{"data":{"id":482219,"external_id":9876543,"provider":"karma","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","vehicle_external_id":12345,"driver_external_id":4421,"device_id":"GPS-DEV-001","vehicle_number":"UL-021","trip_active":0,"start_message_id":91827361,"start_date":"2026-05-26T08:32:00.000Z","start_latitude":18.4861,"start_longitude":-69.9312,"start_odometer_km":124530.4,"stop_message_id":91827881,"stop_date":"2026-05-26T10:14:00.000Z","stop_latitude":18.6792,"stop_longitude":-68.4014,"stop_odometer_km":124612.8,"duration_s":6120,"distance_km":82.4,"duration_night_s":0,"distance_night_km":0,"max_speed_kph":104.2,"driving_score":87,"eco_score":72.4,"fetch_timestamp":"2026-05-26T10:14:31.221Z","created_at":"2026-05-26T10:14:31.221Z","updated_at":"2026-05-26T10:14:31.221Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid trip payload.","details":{"fieldErrors":{"start_date":["start_date must be ISO 8601 datetime"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"No tienes permisos para modificar viajes."}}}}},"404":{"description":"Trip not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Viaje no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"delete":{"summary":"Delete a trip","description":"Permanently deletes a trip.","tags":["Trips"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric trip id."},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid trip payload.","details":{"fieldErrors":{"start_date":["start_date must be ISO 8601 datetime"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"No tienes permisos para modificar viajes."}}}}},"404":{"description":"Trip not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Viaje no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/projects":{"get":{"summary":"List provider fleets (deprecated)","description":"**Deprecated** — use `GET /fleets` for org fleet groupings. This endpoint lists legacy GPS-provider sync fleets (Karma) still used by the internal sync pipeline.","tags":["Projects (deprecated)"],"deprecated":true,"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-200. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_inactive","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/projects/{id}":{"get":{"summary":"Get a project by id","tags":["Projects"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponse"}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/brands":{"get":{"summary":"List vehicle brands and velocity thresholds","description":"Returns vehicle brands (legacy `marcas`) for your org. Each brand carries the velocity buckets and fuel-efficiency bounds applied to vehicles assigned to it.","tags":["Brands"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/fleets":{"get":{"summary":"List GPS fleets","description":"Returns Karma GPS fleets (sync scopes) your organization owns or has been granted access to.","tags":["Fleets"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_inactive","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GpsFleetListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/fleets/{id}":{"get":{"summary":"Get a GPS fleet by id","tags":["Fleets"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GpsFleetResponse"}}}}}}},"/pois":{"get":{"summary":"List points of interest","description":"Returns POIs (geofences) for your org. Each POI is either a circle (point + `geofence_radius_meters`) or a polygon (`polygon_coordinates`). Ordered by `id` ascending so the cursor is stable.","tags":["POIs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-200. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned by a previous call's `pagination.next_cursor`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter by fleet (provider account) id."},"required":false,"name":"fleet_id","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIListResponse"},"example":{"data":[{"id":481,"org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","fleet_id":1029,"name":"Cliente Altice – Bávaro","description":"Punto de entrega cliente Altice zona este","latitude":18.6792,"longitude":-68.4014,"image_url":null,"geometry_type":"circle","geofence_radius_meters":250,"polygon_coordinates":null,"tags":["cliente","distribución-este"],"created_at":"2025-09-15T13:00:00.000Z","updated_at":"2026-04-22T18:45:11.221Z"},{"id":612,"org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","fleet_id":1029,"name":"Patio operativo Santo Domingo","description":null,"latitude":18.5006,"longitude":-69.9298,"image_url":null,"geometry_type":"polygon","geofence_radius_meters":null,"polygon_coordinates":[[18.5012,-69.9305],[18.5012,-69.929],[18.5,-69.929],[18.5,-69.9305]],"tags":["patio","operaciones"],"created_at":"2026-01-08T09:14:22.000Z","updated_at":"2026-01-08T09:14:22.000Z"}],"pagination":{"next_cursor":"eyJpZCI6NjEyfQ","has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"post":{"summary":"Create a point of interest","description":"Creates a circle (default) or polygon POI for your organization. The fleet must be owned by or assigned to your org. For circles, `latitude`, `longitude` and `geofence_radius_meters` (10-1000) are required. For polygons, `polygon_coordinates` with at least 3 `[lat, lng]` vertices is required; `latitude`/`longitude` will be set to the polygon centroid automatically.","tags":["POIs"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePOIRequest"},"examples":{"circle":{"summary":"Circle POI (radius geofence)","value":{"fleet_id":1029,"name":"Cliente Altice – Bávaro","description":"Punto de entrega cliente Altice zona este","geometry_type":"circle","latitude":18.6792,"longitude":-68.4014,"geofence_radius_meters":250,"tags":["cliente","distribución-este"]}},"polygon":{"summary":"Polygon POI (arbitrary shape)","value":{"fleet_id":1029,"name":"Patio operativo Santo Domingo","geometry_type":"polygon","polygon_coordinates":[[18.5012,-69.9305],[18.5012,-69.929],[18.5,-69.929],[18.5,-69.9305]],"tags":["patio","operaciones"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePOIResponse"},"example":{"data":{"id":481,"org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","fleet_id":1029,"name":"Cliente Altice – Bávaro","description":"Punto de entrega cliente Altice zona este","latitude":18.6792,"longitude":-68.4014,"image_url":null,"geometry_type":"circle","geofence_radius_meters":250,"polygon_coordinates":null,"tags":["cliente","distribución-este"],"created_at":"2025-09-15T13:00:00.000Z","updated_at":"2026-04-22T18:45:11.221Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid POI payload.","details":{"fieldErrors":{"geofence_radius_meters":["geofence_radius_meters es requerido para geocercas circulares"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"La flota no está asignada a tu organización."}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"La flota especificada no existe."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/pois/{id}":{"get":{"summary":"Get a POI by id","description":"Returns a single POI by its numeric `id` (scoped to the API key's organization).","tags":["POIs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric POI id."},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIResponse"},"example":{"data":{"id":481,"org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","fleet_id":1029,"name":"Cliente Altice – Bávaro","description":"Punto de entrega cliente Altice zona este","latitude":18.6792,"longitude":-68.4014,"image_url":null,"geometry_type":"circle","geofence_radius_meters":250,"polygon_coordinates":null,"tags":["cliente","distribución-este"],"created_at":"2025-09-15T13:00:00.000Z","updated_at":"2026-04-22T18:45:11.221Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid POI payload.","details":{"fieldErrors":{"geofence_radius_meters":["geofence_radius_meters es requerido para geocercas circulares"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"404":{"description":"POI not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"POI no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"patch":{"summary":"Update a POI","description":"Partially updates a POI. Send only the fields you want to change. To switch geometry, include `geometry_type` plus either `latitude`/`longitude`/`geofence_radius_meters` (for `circle`) or `polygon_coordinates` (for `polygon`).","tags":["POIs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric POI id."},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePOIRequest"},"examples":{"rename":{"summary":"Rename and add tags","value":{"name":"Cliente Altice – Bávaro (Principal)","tags":["cliente","vip"]}},"resize_circle":{"summary":"Resize circle radius","value":{"geofence_radius_meters":350}},"switch_to_polygon":{"summary":"Switch geometry from circle to polygon","value":{"geometry_type":"polygon","polygon_coordinates":[[18.681,-68.403],[18.681,-68.4],[18.678,-68.4],[18.678,-68.403]]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIResponse"},"example":{"data":{"id":481,"org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","fleet_id":1029,"name":"Cliente Altice – Bávaro (Principal)","description":"Punto de entrega cliente Altice zona este","latitude":18.6792,"longitude":-68.4014,"image_url":null,"geometry_type":"circle","geofence_radius_meters":250,"polygon_coordinates":null,"tags":["cliente","vip"],"created_at":"2025-09-15T13:00:00.000Z","updated_at":"2026-05-26T03:21:18.412Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid POI payload.","details":{"fieldErrors":{"geofence_radius_meters":["geofence_radius_meters es requerido para geocercas circulares"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"La flota no está asignada a tu organización."}}}}},"404":{"description":"POI not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"POI no encontrado."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"delete":{"summary":"Delete a POI","description":"Permanently deletes a POI. Returns `409 conflict` if the POI is referenced by any scheduled route stops — remove the route stops first.","tags":["POIs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Numeric POI id."},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid POI payload.","details":{"fieldErrors":{"geofence_radius_meters":["geofence_radius_meters es requerido para geocercas circulares"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"La flota no está asignada a tu organización."}}}}},"404":{"description":"POI not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"POI no encontrado."}}}}},"409":{"description":"POI is referenced by a scheduled route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"conflict","message":"Este POI no se puede eliminar porque está referenciado por rutas programadas. Elimina las paradas primero."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/poi-visits":{"get":{"summary":"List POI visits","description":"Returns POI visits (geofence entries/exits) for your org, cursor-paginated on (`visit_start desc`, `id desc`). A visit is one entry-to-exit cycle: a vehicle entered the geofence, stayed for some time, then left. The fields prefixed `poi_*` and `vehicle_*` are denormalized snapshots so historical visits remain stable even when the underlying POI/vehicle is later edited.","tags":["POIs"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-500. Defaults to 50.","example":"50"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from a previous call's `pagination.next_cursor`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter to a single POI.","example":"481"},"required":false,"name":"poi_id","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter to a single vehicle (`vehicles.external_id`).","example":"16444"},"required":false,"name":"vehicle_external_id","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO-8601 lower bound on `visit_start` (inclusive)."},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO-8601 upper bound on `visit_start` (inclusive)."},"required":false,"name":"end","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIVisitListResponse"},"example":{"data":[{"id":9183721,"org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","poi_id":481,"vehicle_external_id":16444,"stay_id":9183714,"visit_start":"2026-05-20T13:11:03.412Z","visit_end":"2026-05-20T14:42:51.000Z","duration_minutes":92,"poi_name":"Cliente Altice – Bávaro","poi_tags":["cliente","distribución-este"],"poi_latitude":18.6792,"poi_longitude":-68.4014,"poi_image_url":null,"vehicle_number":"T-114","license_plate":"L139558","event_count":318,"distance_to_poi_meters":41.5,"poi_version":3,"created_at":"2026-05-20T14:43:01.117Z","updated_at":"2026-05-20T14:43:01.117Z"},{"id":9183720,"org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","poi_id":481,"vehicle_external_id":16444,"stay_id":9183714,"visit_start":"2026-05-19T08:02:51.000Z","visit_end":"2026-05-19T08:48:14.000Z","duration_minutes":45,"poi_name":"Cliente Altice – Bávaro","poi_tags":["cliente","distribución-este"],"poi_latitude":18.6792,"poi_longitude":-68.4014,"poi_image_url":null,"vehicle_number":"T-114","license_plate":"L139558","event_count":162,"distance_to_poi_meters":22.8,"poi_version":3,"created_at":"2026-05-19T08:48:25.000Z","updated_at":"2026-05-19T08:48:25.000Z"}],"pagination":{"next_cursor":"eyJ2aXNpdF9zdGFydCI6IjIwMjYtMDUtMTlUMDg6MDI6NTEuMDAwWiIsImlkIjo5MTgzNzIwfQ","has_more":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"limit must be between 1 and 500."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/paso-rapido/tolls":{"get":{"summary":"List Paso Rápido tolls","description":"Returns the global Paso Rápido toll catalog with the price for each of the 5 vehicle categories.","tags":["Paso Rápido"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TollListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/paso-rapido/toll-charges":{"get":{"summary":"List toll charges","description":"Returns Paso Rápido toll charges for your org, ordered by date desc. Includes the validation-pipeline outputs (`validation_status`, `fraud_type`, `location_validation_status`, etc.).","tags":["Paso Rápido"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"end","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"vehicle_external_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"station","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TollChargeListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/paso-rapido/tags":{"get":{"summary":"List tag assignments","description":"Returns Paso Rápido tag assignments for your org, ordered by `id` desc. Supports filtering by `tag_number`, `status` and `has_gps`.","tags":["Paso Rápido"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-200. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from a previous call's `pagination.next_cursor`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter by exact tag number."},"required":false,"name":"tag_number","in":"query"},{"schema":{"type":"string","enum":["Valido","Inhabilitado"],"description":"Filter by status."},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by GPS state."},"required":false,"name":"has_gps","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"post":{"summary":"Create a tag assignment","description":"Creates a tag assignment. When `has_gps` is true, `vehicle_external_id` is required; otherwise `vehicle_title` and `vehicle_license_plate` are required. `tag_number` is unique per organization.","tags":["Paso Rápido"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTagRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTagResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/paso-rapido/tags/{id}":{"get":{"summary":"Get a tag assignment by id","description":"Returns a single tag assignment by its numeric `id`.","tags":["Paso Rápido"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"patch":{"summary":"Update a tag assignment","description":"Partially updates a tag assignment. Changing `has_gps` or any vehicle field re-normalizes the GPS/manual vehicle fields together.","tags":["Paso Rápido"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTagRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"delete":{"summary":"Delete a tag assignment","description":"Permanently deletes a tag assignment.","tags":["Paso Rápido"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/fuel/entries":{"get":{"summary":"List fuel entries","description":"Returns fuel entries (refills, fleet card transactions, ad-hoc imports) for your org, cursor-paginated on `(transaction_date desc, id desc)`. Filter by vehicle and/or `transaction_date` range.","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Page size, 1-500. Defaults to 50."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor returned by a previous call's `pagination.next_cursor`."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Return entries whose `transaction_date` is >= this ISO 8601 timestamp."},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Return entries whose `transaction_date` is <= this ISO 8601 timestamp."},"required":false,"name":"end","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Filter by provider vehicle id."},"required":false,"name":"vehicle_external_id","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelEntryListResponse"},"example":{"data":[{"id":"589c258d-4736-4b6f-876f-87835992191e","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","transaction_date":"2026-02-26T03:15:47.000Z","transaction_id":"TXN-9921","notes":null,"vehicle_external_id":16056,"vehicle_number":"L18N / L534991","vehicle_name":"L18N","driver_external_id":null,"driver_key":null,"name":"Juan Pérez","product_id":"f788c39d-02c8-4bd6-aa1a-fa2af011b5a3","product_name":"Diesel Regular","product_type":"Regular","vendor_id":"2f81f423-db0c-46d8-923e-c177fa78a54c","vendor_name":"Estación El Higuero - United Petroleum","vendor_address":"Santo Domingo Norte, DO","gallons":60.008,"price_per_gallon":224.8,"total_cost":13489.8,"odometer_reading":10997,"previous_odometer_reading":10120,"distance_traveled":877,"fuel_efficiency":14.61,"trip_external_id":null,"matched_message_id":6213486243,"gps_odometer_reading":10997.05,"karma_driver_id":null,"source":"API","reference_id":"300030586","created_by":null,"created_at":"2026-02-26T15:30:03.048Z","updated_at":"2026-02-26T15:30:03.048Z"}],"pagination":{"next_cursor":null,"has_more":false}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"post":{"summary":"Create a fuel entry","description":"Creates a fuel entry for your organization. When `vehicle_external_id` and `transaction_date` are provided, the entry is automatically matched against the nearest trip and GPS message (±30 min). `odometer_reading` drives the efficiency trigger.","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFuelEntryRequest"},"examples":{"minimal":{"summary":"Minimal entry","value":{"vehicle_number":"L18N / L534991","product_name":"Diesel Regular","product_type":"Regular","gallons":60.008,"price_per_gallon":224.8}},"complete":{"summary":"Complete entry with telemetry hints","value":{"vehicle_external_id":16056,"vehicle_number":"L18N / L534991","vehicle_name":"L18N","name":"Juan Pérez","product_id":"f788c39d-02c8-4bd6-aa1a-fa2af011b5a3","product_name":"Diesel Regular","product_type":"Regular","vendor_id":"2f81f423-db0c-46d8-923e-c177fa78a54c","gallons":60.008,"price_per_gallon":224.8,"odometer_reading":10997,"transaction_date":"2026-02-26T03:15:47.000Z","source":"API","reference_id":"300030586"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFuelEntryResponse"},"example":{"data":{"id":"589c258d-4736-4b6f-876f-87835992191e","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","transaction_date":"2026-02-26T03:15:47.000Z","transaction_id":"TXN-9921","notes":null,"vehicle_external_id":16056,"vehicle_number":"L18N / L534991","vehicle_name":"L18N","driver_external_id":null,"driver_key":null,"name":"Juan Pérez","product_id":"f788c39d-02c8-4bd6-aa1a-fa2af011b5a3","product_name":"Diesel Regular","product_type":"Regular","vendor_id":"2f81f423-db0c-46d8-923e-c177fa78a54c","vendor_name":"Estación El Higuero - United Petroleum","vendor_address":"Santo Domingo Norte, DO","gallons":60.008,"price_per_gallon":224.8,"total_cost":13489.8,"odometer_reading":10997,"previous_odometer_reading":10120,"distance_traveled":877,"fuel_efficiency":14.61,"trip_external_id":null,"matched_message_id":6213486243,"gps_odometer_reading":10997.05,"karma_driver_id":null,"source":"API","reference_id":"300030586","created_by":null,"created_at":"2026-02-26T15:30:03.048Z","updated_at":"2026-02-26T15:30:03.048Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid fuel entry payload.","details":{"fieldErrors":{"gallons":["gallons must be greater than 0"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"API key is missing required scope: fuel_entries:write."}}}}},"404":{"description":"Vehicle not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"El vehículo especificado no existe en esta organización."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/fuel/entries/{id}":{"get":{"summary":"Get a fuel entry by id","description":"Returns a single fuel entry by its UUID (scoped to the API key's org).","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Fuel entry UUID."},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelEntryResponse"},"example":{"data":{"id":"589c258d-4736-4b6f-876f-87835992191e","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","transaction_date":"2026-02-26T03:15:47.000Z","transaction_id":"TXN-9921","notes":null,"vehicle_external_id":16056,"vehicle_number":"L18N / L534991","vehicle_name":"L18N","driver_external_id":null,"driver_key":null,"name":"Juan Pérez","product_id":"f788c39d-02c8-4bd6-aa1a-fa2af011b5a3","product_name":"Diesel Regular","product_type":"Regular","vendor_id":"2f81f423-db0c-46d8-923e-c177fa78a54c","vendor_name":"Estación El Higuero - United Petroleum","vendor_address":"Santo Domingo Norte, DO","gallons":60.008,"price_per_gallon":224.8,"total_cost":13489.8,"odometer_reading":10997,"previous_odometer_reading":10120,"distance_traveled":877,"fuel_efficiency":14.61,"trip_external_id":null,"matched_message_id":6213486243,"gps_odometer_reading":10997.05,"karma_driver_id":null,"source":"API","reference_id":"300030586","created_by":null,"created_at":"2026-02-26T15:30:03.048Z","updated_at":"2026-02-26T15:30:03.048Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"404":{"description":"Fuel entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Entrada de combustible no encontrada."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"patch":{"summary":"Update a fuel entry","description":"Partially updates a fuel entry. Send only the fields you want to change. `org_id` cannot be changed.","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Fuel entry UUID."},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFuelEntryRequest"},"examples":{"correct_price":{"summary":"Correct gallons and price","value":{"gallons":58.4,"price_per_gallon":222}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelEntryResponse"},"example":{"data":{"id":"589c258d-4736-4b6f-876f-87835992191e","org_id":"d87f7281-ea19-45cd-b6fd-d8eb9e310da1","transaction_date":"2026-02-26T03:15:47.000Z","transaction_id":"TXN-9921","notes":null,"vehicle_external_id":16056,"vehicle_number":"L18N / L534991","vehicle_name":"L18N","driver_external_id":null,"driver_key":null,"name":"Juan Pérez","product_id":"f788c39d-02c8-4bd6-aa1a-fa2af011b5a3","product_name":"Diesel Regular","product_type":"Regular","vendor_id":"2f81f423-db0c-46d8-923e-c177fa78a54c","vendor_name":"Estación El Higuero - United Petroleum","vendor_address":"Santo Domingo Norte, DO","gallons":60.008,"price_per_gallon":224.8,"total_cost":13489.8,"odometer_reading":10997,"previous_odometer_reading":10120,"distance_traveled":877,"fuel_efficiency":14.61,"trip_external_id":null,"matched_message_id":6213486243,"gps_odometer_reading":10997.05,"karma_driver_id":null,"source":"API","reference_id":"300030586","created_by":null,"created_at":"2026-02-26T15:30:03.048Z","updated_at":"2026-02-26T15:30:03.048Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid fuel entry payload.","details":{"fieldErrors":{"gallons":["gallons must be greater than 0"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"API key is missing required scope: fuel_entries:write."}}}}},"404":{"description":"Fuel entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Entrada de combustible no encontrada."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}},"delete":{"summary":"Delete a fuel entry","description":"Permanently deletes a fuel entry (historical record).","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Fuel entry UUID."},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"API key is missing required scope: fuel_entries:write."}}}}},"404":{"description":"Fuel entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"Entrada de combustible no encontrada."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/fuel/entries/bulk":{"post":{"summary":"Bulk create fuel entries","description":"Creates a single entry or an array of up to 1000 fuel entries for your organization. Every `vehicle_external_id` (when provided) must belong to the API key's org. Telemetry (trip, GPS message, odometer + position) is auto-matched best-effort for entries with a vehicle + `transaction_date`; pass `trip_external_id` / `matched_message_id` to skip matching for that entry.","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelEntryBulkImportRequest"},"examples":{"bulk":{"summary":"Bulk array","value":[{"vehicle_number":"L18N / L534991","product_name":"Diesel Regular","product_type":"Regular","gallons":60.008,"price_per_gallon":224.8,"transaction_date":"2026-02-26T03:15:47.000Z","source":"API","reference_id":"300030586"},{"vehicle_number":"T-114","product_name":"Diesel Regular","product_type":"Regular","gallons":41.2,"price_per_gallon":224.8,"transaction_date":"2026-02-26T05:02:11.000Z","source":"API","reference_id":"300030587"}]}}}}},"responses":{"201":{"description":"Imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelEntryBulkImportResponse"},"example":{"inserted":2,"ids":["589c258d-4736-4b6f-876f-87835992191e","7b2a3d2c-6e88-4a4d-8e7b-2c7a1f5d83b9"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"bad_request","message":"Invalid fuel entry payload.","details":{"fieldErrors":{"gallons":["gallons must be greater than 0"]}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"unauthorized","message":"API key missing or invalid."}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"forbidden","message":"API key is missing required scope: fuel_entries:write."}}}}},"404":{"description":"A referenced vehicle does not exist in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"not_found","message":"El vehículo especificado no existe en esta organización."}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"},"example":{"error":{"code":"too_many_requests","message":"Rate limit exceeded."}}}}}}}},"/fuel/products":{"get":{"summary":"List fuel products","description":"Returns fuel products configured for your org (diesel, regular, premium, etc.).","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelProductListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/fuel/vendors":{"get":{"summary":"List fuel vendors","description":"Returns fuel vendors / gas stations configured for your org.","tags":["Fuel"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelVendorListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/routes":{"get":{"summary":"List scheduled routes","description":"Returns scheduled routes (legacy `scheduled_routes`) for your org, ordered by `scheduled_start_time` desc.","tags":["Scheduled Routes"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"vehicle_external_id","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"end","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledRouteListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}},"/shares":{"get":{"summary":"List shared trip views","description":"Returns tokenized public share links generated for trips / map snapshots. The bearer of the link can view the trip without an account; revoke by setting `expires_at` in the dashboard.","tags":["Shares"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_expired","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedTripViewListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorObject"}}}}}}}},"webhooks":{}}