# Requests & responses

## URL layout

All platform endpoints share the path prefix **`/platform/v1`**. Combine with your host (for example `https://api.fleet.co`) to build full URLs.

## Path IDs

Identifiers in the path (`order_id`, `user_id`, `device_id`, `product_id`, `product_group_id`, …) are **strings** that look like a **positive integer** with **no leading zeros** (e.g. `42`, not `042`). The **API reference** documents each parameter name per route.

## Pagination

List operations accept **`limit`** and **`offset`**. Defaults and maximums differ slightly by resource (for example catalog product groups often default to a smaller page size than users or devices). **`meta`** in the response repeats **`total`**, **`limit`**, and **`offset`** so you can page through large sets without guessing.

## Success payloads

- **Single resource:** top-level **`data`** is one object.
- **List:** **`data`** is an array and **`meta`** carries pagination fields.
- **Batch device create:** **`data`** wraps a **`devices`** array; the status code is **201**.

Exact field names and nested objects are in **API reference**.

## Errors

- **Domain / business rules:** usually `{ "error": "SOME_CODE" }` with a stable code (examples: `ORDER_NOT_FOUND`, `INSUFFICIENT_SCOPE`, `USER_EMAIL_CONFLICT`). Each operation lists its possible codes.
- **Validation:** often **400** with `{ "error": "<readable message>" }` when query or body does not match the schema.

## JSON bodies

For **POST** and **PATCH**, send **`Content-Type: application/json`** unless an operation documents otherwise.

## Throughput

Platform routes are **rate-limited** per credential (see [Authentication & scopes](./authentication/) for production vs non-production limits and **429** / **503** behavior).