--- updatedAt: 2025-09-10T20:59:54.000Z agentTools: projectIndex: https://shipcars.readme.io/llms.txt --- # /trips/ Returns a list of trips. A trip is a set of loads that are transported in one go. It has a starting as well as an ending point, or destination. Carriers are responsible for managing and overseeing trips. During a trip, vehicles can be released from the truck and others can be picked up. Trips always consist of loads and are also used to determine the total cost of expenses (e.g fuel) and earnings (e.g driver’s pay). They can thus be considered management entities that carriers use for easier assignment of orders to drivers and reporting and grouping of loads. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "CTMS", "description": "Ship.Cars CTMS", "contact": { "url": "https://ship.cars", "email": "support@ship.cars" }, "version": "1.0.0" }, "components": { "securitySchemes": { "bearerAuth": { "type": "oauth2", "flows": { "password": { "tokenUrl": "https://auth.ship.cars/auth/realms/master/protocol/openid-connect/token", "scopes": {} } } } } }, "servers": [ { "url": "https://ship.cars/api" } ], "paths": { "/trips/": { "get": { "tags": [ "Trips" ], "description": "Returns a list of trips.\n\nA trip is a set of loads that are transported in one go. It has a starting as well as an ending point, or destination. Carriers are responsible for managing and overseeing trips. \n\nDuring a trip, vehicles can be released from the truck and others can be picked up. Trips always consist of loads and are also used to determine the total cost of expenses (e.g fuel) and earnings (e.g driver’s pay). They can thus be considered management entities that carriers use for easier assignment of orders to drivers and reporting and grouping of loads.\n", "operationId": "trips_list", "parameters": [ { "name": "Authorization", "in": "header", "description": "Authenticates API requests with a valid access token.", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Returns all the trips that match the specified status.", "schema": { "type": "string", "enum": [ "active", "completed", "archived" ] } }, { "name": "name", "in": "query", "description": "Returns the trip that matches the specified trip's name.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "description": "Returns the trip that matches the specified trip's ID.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Specifies the maximum number of results to return per page. Combine with `offset` for pagination.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Specifies the number of results to skip in the response. Combine with `limit` for pagination.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "required": [ "count", "results" ], "type": "object", "properties": { "results": { "uniqueItems": true, "type": "array", "description": "List of results on the page.", "items": { "type": "object", "properties": { "driver_id": { "type": "string", "description": "Internal ID of the driver assigned to the trip. Trips can still exist without a driver.", "format": "uri", "readOnly": true }, "driver": { "type": "string", "description": "Url form of the driver.", "readOnly": true }, "update_time": { "type": "string", "description": "Last time the trip was updated.", "format": "date-time", "readOnly": true }, "create_time": { "type": "string", "description": "Time the trip was created.", "format": "date-time", "readOnly": true }, "name": { "type": "string", "description": "Name of the trip. The only condition needed to create a trip." }, "status": { "type": "string", "description": "Status of the trip; Active – The trip is active. Archived – The trip is finished but kept in the history log of trips.", "enum": [ "active", "archived" ] }, "id": { "type": "string", "description": "Internal ID of the trip.", "readOnly": true }, "url": { "type": "string", "description": "Url form of the trip.", "readOnly": true }, "loads": { "type": "array", "description": "Represents loads that are grouped in the trip. Can be added once the trip is named. However, trips can still exist without loads. Internal ID of the load in the trip.", "items": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Internal ID of the load" } } } } } } }, "previous": { "type": "string", "description": "URL of the previous page of results.", "format": "uri" }, "next": { "type": "string", "description": "URL of the next page of results.", "format": "uri" }, "count": { "type": "integer", "description": "Total number of results." } } }, "example": { "results": [ { "driver_id": "je45", "driver": "https://ship.cars/api/users/je45/", "update_time": "2021-04-15T14:25:48.249Z", "create_time": "2021-04-15T14:25:36.275Z", "name": "Trip (04.15.2021)", "status": "active", "loads": [ { "id": "dsa3f3" }, { "id": "sd3ds3" } ], "id": "jkw2", "url": "https://ship.cars/api/trips/jkw2/" }, { "update_time": "2021-03-15T14:25:48.249Z", "create_time": "2021-03-15T14:25:36.275Z", "name": "Trip LA to NY", "status": "active", "loads": [ { "id": "83mx68" } ], "id": "sdw4", "url": "https://ship.cars/api/trips/sdw4/" } ], "count": 2 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Message giving details about the reason for the error response." } } }, "example": { "detail": "Authentication credentials were not provided." } } } } }, "x-code-samples": [ { "lang": "cURL", "source": "curl --request GET \\\n--url 'https://ship.cars/api/trips/?limit=1' \\\n--header 'Authorization: Bearer <>'\n" } ], "security": [ { "bearerAuth": [] } ] } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```