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

# Request Standards

> HTTP methods, pagination, sorting, date formats, and idempotency.

Conventions for all Partner API requests.

***

## Base URL & Versioning

| Environment    | Base URL                            |
| -------------- | ----------------------------------- |
| **Sandbox**    | `https://apiv3.thecleanlife.dev/v1` |
| **Production** | `https://api.cleanlife.sa/v1`       |

All partner routes follow this pattern:

```
{BASE_URL}/partners/{resource}
```

Examples:

```
# Sandbox
https://apiv3.thecleanlife.dev/v1/partners/services
https://apiv3.thecleanlife.dev/v1/partners/bookings

# Production
https://api.cleanlife.sa/v1/partners/services
https://api.cleanlife.sa/v1/partners/bookings
```

The API uses URI path versioning. The current version is `v1` and is included in the base URL.

***

## HTTP Methods

| Method  | Usage                                          |
| ------- | ---------------------------------------------- |
| `GET`   | Read resources (catalog, bookings)             |
| `POST`  | Create resources (bookings, price calculation) |
| `PATCH` | Partial updates (booking cancel)               |

***

## Required Headers

| Header         | Required             | Description                               |
| -------------- | -------------------- | ----------------------------------------- |
| `x-api-key`    | **Yes**              | Partner API key                           |
| `Content-Type` | **Yes** (POST/PATCH) | `application/json`                        |
| `x-request-id` | No                   | Client trace ID; echoed as `X-Request-Id` |

***

## JSON Conventions

* Request bodies use **camelCase** field names.
* Dates for booking creation use `YYYY-MM-DD` (e.g. `2026-06-20`).
* Timeslots use `HH:mm` 24-hour format (e.g. `09:00`, `12:00`).
* All UUIDs must be valid UUID v4.

***

## Pagination

List endpoints accept the following pagination query parameters:

| Parameter   | Type            | Default | Description                          |
| ----------- | --------------- | ------- | ------------------------------------ |
| `page`      | integer         | `1`     | Page number (1-based)                |
| `limit`     | integer         | `20`    | Items per page (max `100`)           |
| `sortBy`    | string          | —       | Field to sort by (endpoint-specific) |
| `sortOrder` | `ASC` \| `DESC` | —       | Sort direction                       |

### Example

```http theme={null}
GET /partners/services?addressId=bbbbbbbb-0000-0000-0000-000000000002&page=2&limit=50&sortOrder=DESC
```

***

## Idempotency

<Warning>
  — `Idempotency-Key` header support exists in the idempotency service layer but may not be enabled on all public booking endpoints. Confirm with the CleanLife integration team before relying on it in production.
</Warning>

When enabled, send:

```http theme={null}
Idempotency-Key: unique-key-per-logical-operation
```

Reusing the same key with the **same** payload replays the stored response. Reusing the key with a **different** payload returns a conflict error.

***

## Date & Timezone

* Business timezone: **Asia/Riyadh** (UTC+3).
* API timestamps in responses use ISO 8601 with timezone offset where applicable.
* Booking `date` is a calendar date in the service territory, not a UTC instant.

***

## Request Size

Keep JSON payloads reasonable (under 1 MB).