> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Market Segments

> The accepted values for a vehicle's market segment, so you can validate before creating or updating a vehicle

[← Vehicles API](/api-reference/vehicles/overview)

List the values accepted for a vehicle's market segment. The segment is what distinguishes a supermini from an executive car when the emission factor depends on vehicle class, so sending a value that is not in this list is rejected at write time.

<Warning>
  **The path uses an underscore: `market_segments`.** Most routes in the Vehicles API separate words with hyphens (`bulk-delete-by-filters`), but this one does not.

  The hyphenated spelling does not 404 — it is captured by `GET /v1/vehicles/{vehicle_id}` and returns `422` complaining that `market-segments` is not a valid UUID. An error about a vehicle id is the signal that you spelled this path with a hyphen.
</Warning>

<Note>
  **A fixed list, not your data.** The response is the enumeration itself — it does not depend on your organization, never paginates, and does not change unless the platform adds a segment. Fetch it once and cache it, or hardcode it from this page and use the endpoint as the check that your copy is still current.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  UUID of your organization.

  **Format:** UUID
</ParamField>

<Note>
  **The organization header is required even though the list is global.** The endpoint takes no query parameters and the response is identical for every organization, but the router's authentication dependency resolves an organization from this header before the handler runs. Omitting it returns `422`, not `401`.
</Note>

## Response

Returns a **flat array of strings**, not an object wrapping one.

<ResponseField name="array" type="array[string]">
  The nine accepted market segments:

  `mini` · `supermini` · `lower_medium` · `upper_medium` · `executive` · `luxury` · `sports` · `dual_purpose_4x4` · `mpv`
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/vehicles/market_segments" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "x-organization-id: YOUR_ORGANIZATION_ID"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  segments = requests.get(
      "https://api.dcycle.io/v1/vehicles/market_segments",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "x-organization-id": "YOUR_ORGANIZATION_ID",
      },
      timeout=30,
  ).json()

  # The response is the list itself — no unwrapping
  def valid_segment(value):
      return value in segments
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.dcycle.io/v1/vehicles/market_segments",
    {
      headers: {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID",
      },
    },
  );
  const segments = await response.json();

  const validSegment = (value) => segments.includes(value);
  ```
</CodeGroup>

### Successful Response

Returns `200 OK`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  "mini",
  "supermini",
  "lower_medium",
  "upper_medium",
  "executive",
  "luxury",
  "sports",
  "dual_purpose_4x4",
  "mpv"
]
```

## Common Errors

### 422 Unprocessable Entity

**Cause:** `x-organization-id` is missing. This fires before any credential check, so it is what you get from a request with no headers at all.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["header", "x-organization-id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### 401 Unauthorized

**Cause:** The organization header is present but the credentials are not.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "CREDENTIALS_REQUIRED",
  "detail": "Credentials required (API key or JWT token)"
}
```

## Vehicle Sizes

The Vehicles API exposes a second enumeration of the same shape at `GET /v1/vehicles/sizes`, with the same headers — `x-organization-id` included — and the same flat-array response. Its four values are:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
["small_car", "medium", "large_car", "average_car"]
```

Size and market segment are separate fields and separate lists — a vehicle can carry both, and neither constrains the other.

## Use Cases

### Validate before you write

When your integration lets a user pick a segment, populate the choice from this endpoint rather than from a hardcoded list that can drift. A value that is not in the list is rejected when you create or update the vehicle, so catching it at selection time turns a write failure into a closed dropdown.

### Check a hardcoded copy is still current

If you prefer to ship the nine values in your own code, call this endpoint in a test and assert the two lists match. That way a segment added on the platform surfaces as a failing test instead of as user input your form silently refuses.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Vehicle" icon="plus" href="/api-reference/vehicles/create">
    Where the market segment is sent
  </Card>

  <Card title="Update Vehicle" icon="pencil" href="/api-reference/vehicles/update">
    Change the segment on an existing vehicle
  </Card>

  <Card title="List Vehicle Fuels" icon="gas-pump" href="/api-reference/vehicle-fuels/list">
    The other catalogue you need before creating a vehicle
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Everything the Vehicles API covers
  </Card>
</CardGroup>