{"openapi":"3.1.0","info":{"title":"Samsara (BYOK) API","version":"0.1.0","description":"Samsara (BYOK) lets an AI assistant read your own Samsara data through the Samsara API with a key you supply (Samsara API token (US cloud; give it read scopes only)). Read-only: 12 tools (get_organization, list_vehicles, get_vehicle, get_vehicle_locations, get_vehicle_stats, list_trailers, list_equipment, list_trips, list_work_orders, list_upcoming_preventive_maintenance,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-samsara.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-samsara/docs"},"termsOfService":"https://connectorbay.com/byok-samsara/terms"},"servers":[{"url":"https://byok-samsara.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-samsara/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_organization":{"post":{"operationId":"get_organization","summary":"Show the Samsara organization the token belongs to: id, name and carrier settings (carrier name, USDOT number, main offi","description":"Show the Samsara organization the token belongs to: id, name and carrier settings (carrier name, USDOT number, main office address). Needs the Read Org Information scope. Use for \"Which Samsara organization is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_organizationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_vehicles":{"post":{"operationId":"list_vehicles","summary":"List the fleet's vehicles with name, VIN, make, model, year, plate, gateway serial, vehicle type, tags and external ids.","description":"List the fleet's vehicles with name, VIN, make, model, year, plate, gateway serial, vehicle type, tags and external ids. Up to 512 per page; page with the cursor. Needs the Read Vehicles scope. Use for \"Which trucks are in my Samsara fleet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":512,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items to return (1 to 512).","title":"Limit"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"},"tag_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items carrying these tag ids, comma-separated, for example '1234,5678'.","title":"Tag Ids"},"updated_after_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only vehicles updated at or after this RFC 3339 time, for example 2026-09-01T00:00:00Z.","title":"Updated After Time"}},"title":"list_vehiclesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_vehicle":{"post":{"operationId":"get_vehicle","summary":"Get one vehicle by its Samsara id (or an external id such as 'maintenanceId:250020'): name, VIN, make, model, year, plat","description":"Get one vehicle by its Samsara id (or an external id such as 'maintenanceId:250020'): name, VIN, make, model, year, plate, gateway, tags and gross weight. Use for \"Show me the details of Samsara vehicle 281474976710655\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Samsara vehicle id, or an external id written as key:value.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_vehicleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_vehicle_locations":{"post":{"operationId":"get_vehicle_locations","summary":"Get the last known position of each vehicle (or of chosen vehicles): latitude, longitude, heading, speed, time and a rev","description":"Get the last known position of each vehicle (or of chosen vehicles): latitude, longitude, heading, speed, time and a reverse-geocoded place name. Needs the Read Vehicle Statistics scope. Use for \"Where are my Samsara trucks right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vehicle_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Only these vehicle ids, comma-separated, for example '112,113'.","title":"Vehicle Ids"},"tag_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items carrying these tag ids, comma-separated, for example '1234,5678'.","title":"Tag Ids"},"time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Return the last known position at or before this RFC 3339 time. Defaults to now.","title":"Time"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"}},"title":"get_vehicle_locationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_vehicle_stats":{"post":{"operationId":"get_vehicle_stats","summary":"Get the latest engine and fuel stats of vehicles: engine state, fuel percent, odometer, battery voltage, RPM, coolant te","description":"Get the latest engine and fuel stats of vehicles: engine state, fuel percent, odometer, battery voltage, RPM, coolant temperature, GPS and fault codes. You must name 1 to 3 stat types. Use for \"What is the engine state and fuel level of my Samsara trucks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"types":{"description":"1 to 3 stat types, comma-separated, for example 'engineStates,fuelPercents,obdOdometerMeters'. Others include gps, gpsOdometerMeters, batteryMilliVolts, engineRpm, engineLoadPercent, engineCoolantTemperatureMilliC, faultCodes, defLevelMilliPercent, evStateOfChargeMilliPercent.","maxLength":200,"title":"Types","type":"string"},"vehicle_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Only these vehicle ids, comma-separated, for example '112,113'.","title":"Vehicle Ids"},"tag_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items carrying these tag ids, comma-separated, for example '1234,5678'.","title":"Tag Ids"},"time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Return the last known stats at or before this RFC 3339 time. Defaults to now.","title":"Time"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"}},"required":["types"],"title":"get_vehicle_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_trailers":{"post":{"operationId":"list_trailers","summary":"List trailers with name, plate, trailer serial number, installed gateway, tags and notes. Up to 512 per page. Use for \"W","description":"List trailers with name, plate, trailer serial number, installed gateway, tags and notes. Up to 512 per page. Use for \"Which trailers does my fleet have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":512,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items to return (1 to 512).","title":"Limit"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"},"tag_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items carrying these tag ids, comma-separated, for example '1234,5678'.","title":"Tag Ids"}},"title":"list_trailersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_equipment":{"post":{"operationId":"list_equipment","summary":"List non-vehicle equipment (generators, excavators and similar) with name, asset serial, installed gateway, tags and not","description":"List non-vehicle equipment (generators, excavators and similar) with name, asset serial, installed gateway, tags and notes. Up to 512 per page. Use for \"What equipment is tracked in Samsara\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":512,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items to return (1 to 512).","title":"Limit"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"},"tag_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items carrying these tag ids, comma-separated, for example '1234,5678'.","title":"Tag Ids"}},"title":"list_equipmentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_trips":{"post":{"operationId":"list_trips","summary":"List trips of up to 50 assets (vehicles or trailers) in a time window: start and end time, distance in meters, completio","description":"List trips of up to 50 assets (vehicles or trailers) in a time window: start and end time, distance in meters, completion status and trip purpose. Locations are not returned. Needs the Read Trips scope. Use for \"What trips did Samsara vehicle 281474976710655 make this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"description":"Start of the window, RFC 3339, for example 2026-10-10T00:00:00Z.","maxLength":40,"title":"Start Time","type":"string"},"asset_ids":{"description":"Asset (vehicle) ids, comma-separated, at most 50.","maxLength":600,"title":"Asset Ids","type":"string"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, RFC 3339. Defaults to now.","title":"End Time"},"completion_status":{"anyOf":[{"enum":["inProgress","completed","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Trips to include: inProgress, completed or all (default all).","title":"Completion Status"},"query_by":{"anyOf":[{"enum":["updatedAtTime","tripStartTime"],"type":"string"},{"type":"null"}],"default":null,"description":"Which timestamp the window applies to: updatedAtTime (default) or tripStartTime.","title":"Query By"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"}},"required":["start_time","asset_ids"],"title":"list_tripsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_work_orders":{"post":{"operationId":"list_work_orders","summary":"List maintenance work orders with status, priority, category, description, linked asset, due and completion dates, odome","description":"List maintenance work orders with status, priority, category, description, linked asset, due and completion dates, odometer and engine hours. Needs the Read Work Orders scope. Use for \"Which Samsara work orders are open for my trucks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Only these work order ids, comma-separated (up to 100).","title":"Ids"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"}},"title":"list_work_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_upcoming_preventive_maintenance":{"post":{"operationId":"list_upcoming_preventive_maintenance","summary":"List upcoming and overdue preventive maintenance per asset: status, next due time and odometer, days left and the linked","description":"List upcoming and overdue preventive maintenance per asset: status, next due time and odometer, days left and the linked schedule. Up to 200 per page. Use for \"Which trucks are overdue for preventive maintenance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"asset_ids":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":null,"description":"Only these asset ids, comma-separated.","title":"Asset Ids"},"schedule_ids":{"anyOf":[{"maxLength":600,"type":"string"},{"type":"null"}],"default":null,"description":"Only these preventive maintenance schedule ids, comma-separated.","title":"Schedule Ids"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items to return (1 to 200).","title":"Limit"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"}},"title":"list_upcoming_preventive_maintenanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_vehicle_fuel_energy_report":{"post":{"operationId":"get_vehicle_fuel_energy_report","summary":"Get a fuel and energy report per vehicle for a date range: distance, fuel used, efficiency, idle and run time, estimated","description":"Get a fuel and energy report per vehicle for a date range: distance, fuel used, efficiency, idle and run time, estimated cost and CO2. Needs the Read Fuel and Energy scope. Use for \"How much fuel did my Samsara trucks use last week and what was their efficiency\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day of the report, RFC 3339 (only the date is used), for example 2026-10-01T00:00:00Z.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"Last day of the report, RFC 3339 (only the date is used).","maxLength":40,"title":"End Date","type":"string"},"vehicle_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Only these vehicle ids, comma-separated, for example '112,113'.","title":"Vehicle Ids"},"energy_type":{"anyOf":[{"enum":["fuel","hybrid","electric"],"type":"string"},{"type":"null"}],"default":null,"description":"Only vehicles using this energy: fuel, hybrid or electric.","title":"Energy Type"},"tag_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items carrying these tag ids, comma-separated, for example '1234,5678'.","title":"Tag Ids"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"}},"required":["start_date","end_date"],"title":"get_vehicle_fuel_energy_reportArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List the organization's tags (groups) with parent tag and the vehicles, trailers and addresses assigned. Up to 512 per p","description":"List the organization's tags (groups) with parent tag and the vehicles, trailers and addresses assigned. Up to 512 per page. Use for \"What tags or depots are defined in Samsara\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":512,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items to return (1 to 512).","title":"Limit"},"after":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the pagination.endCursor value of the previous answer. Leave out for the first page.","title":"After"}},"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}