Vehicles¶

Vehicles are a solicitation-centric grouping of multiple IDVs (the “thing people usually mean” when they say “this vehicle”), exposed at /api/vehicles/.

If you want the conceptual model first, start with Getting Started – Vehicles. For field definitions, see the Vehicles Data Dictionary.

Endpoints¶

• GET /api/vehicles/ (list + search + ordering)
• GET /api/vehicles/{uuid}/ (detail; supports shaping)
• GET /api/vehicles/{uuid}/awardees/ (the underlying IDVs; supports shaping)
• GET /api/vehicles/{uuid}/orders/ (task orders / contracts under all IDVs in the vehicle; behaves like /api/contracts/)

Filtering / search¶

Vehicle list search¶

Vehicle detail “awardees” filtering¶

On GET /api/vehicles/{uuid}/, search is not vehicle search. It’s reserved for filtering the expanded awardees when your shape includes awardees(...).

Example:

• GET /api/vehicles/{uuid}/?shape=uuid,solicitation_identifier,awardees(key,piid,recipient(display_name,uei))&search=deloitte

Response shaping / flattening¶

Vehicle responses use the shaping pipeline by default — even without an explicit ?shape= parameter, responses go through the shaping system with a default shape. See Response Shaping for the full field reference and default shapes.

Vehicles support:

• shape=... (see Response Shaping)
• flat=true|false
• flat_lists=true|false
• joiner=. (only relevant when flat=true)

Ordering¶

Vehicles support ordering= with a strict allowlist:

• vehicle_obligations
• latest_award_date

Examples:

• Most obligations first: GET /api/vehicles/?ordering=-vehicle_obligations
• Most recently-active first: GET /api/vehicles/?ordering=-latest_award_date

Pagination¶

Vehicle lists use standard page-number pagination:

• page (default 1)
• limit (max 100)

Vehicle awardees (IDVs) are returned as a list endpoint and are paginated as well (see Swagger for details).

Vehicle orders (/api/vehicles/{uuid}/orders/) behave like contracts:

• cursor-based (keyset) pagination via limit + cursor
• ordering allowlist: award date, obligated, total contract value

SDK examples¶

The official SDKs don’t yet expose a first-class list_vehicles() / listVehicles() method. Until they do, you can still call the endpoint via the SDK’s internal HTTP helper.

List vehicles (search + ordering)¶

import os

from tango import TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])

# Workaround until the SDK ships a first-class list_vehicles()
data = client._get(
    "/api/vehicles/",
    params={
        "search": "SEWP",
        "ordering": "-vehicle_obligations",
        "page": 1,
        "limit": 10,
    },
)

print("count:", data.get("count"))
print("first uuid:", (data.get("results") or [{}])[0].get("uuid"))

import { TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });

// Workaround until the SDK ships a first-class listVehicles()
const http = (client as any).http;
const data = await http.get("/api/vehicles/", {
  search: "SEWP",
  ordering: "-vehicle_obligations",
  page: 1,
  limit: 10,
});

console.log("count:", data.count);
console.log("first uuid:", data?.results?.[0]?.uuid);

Vehicle detail with awardees expansion + filtering¶

import os

from tango import TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])

vehicle_uuid = "00000000-0000-0000-0000-000000000000"  # replace

data = client._get(
    f"/api/vehicles/{vehicle_uuid}/",
    params={
        "shape": "uuid,solicitation_identifier,awardees(key,piid,recipient(display_name,uei))",
        "search": "deloitte",  # filters expanded awardees
    },
)

print(data["uuid"], data.get("solicitation_identifier"))

import { TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });

const vehicleUuid = "00000000-0000-0000-0000-000000000000"; // replace

const http = (client as any).http;
const data = await http.get(`/api/vehicles/${vehicleUuid}/`, {
  shape: "uuid,solicitation_identifier,awardees(key,piid,recipient(display_name,uei))",
  search: "deloitte", // filters expanded awardees
});

console.log(data.uuid, data.solicitation_identifier);