# Quickstart

Your first CarFleet API call, in about five minutes.

## 1. Get a key

**Settings → API & MCP → Create key.** Name it after whatever will use it — "Marketplace sync",
"Our accounting job" — so you can recognise it later.

The key is shown **once**. Copy it now; it cannot be recovered afterwards, including by us. If you
lose it, revoke it and make another.

Keys look like `cf_live_sk_…`. You choose at minting whether a key is **read-only** or **read-write**;
read-write reaches reference data only — vehicles, add-ons, charge types, invoice settings — and only
over MCP. Every REST endpoint below reads. Nothing you build against this API can take a
payment, issue an invoice, change a booking or message a customer.

## 2. Make a call

```bash
curl https://carfleet.ae/api/v1/me \
  -H "Authorization: Bearer cf_live_sk_your_key_here"
```

```json
{ "workspace": { "slug": "your-company", "status": "active" }, "role": "custom:api-readonly" }
```

`/v1/me` reads none of your data. It exists so you can prove a key works before pointing anything
real at it.

If you get a 401, the body says which of five things went wrong — malformed, unknown, revoked,
expired, or a frozen workspace. A revoked key never reads as a typo.

## 3. Ask something useful

Which cars are free next weekend:

```bash
curl -G https://carfleet.ae/api/v1/vehicles \
  -H "Authorization: Bearer $CARFLEET_KEY" \
  --data-urlencode "from=2026-08-22T10:00:00Z" \
  --data-urlencode "to=2026-08-24T10:00:00Z"
```

Supply `from` and `to` and every vehicle comes back with an `available` flag. Omit them and you get
a plain search — the flag is absent rather than guessed, because "available" with no window means
nothing.

Who owes you money, oldest debt first:

```bash
curl https://carfleet.ae/api/v1/receivables \
  -H "Authorization: Bearer $CARFLEET_KEY"
```

Each customer carries `current`, `d1_30`, `d31_60` and `d60p`. Names and figures only — no phone
numbers, emails or identity documents pass through this API at all.

## Things that will bite you if nobody says them

**Money is in fils.** Every amount is AED × 100. `784140` is AED 7,841.40. There are no decimals
anywhere in this API, and reading one of these as dirhams is the single most likely mistake to make
against it.

**`days` on a booking is the ORIGINAL booked term**, not how long the rental lasted. A booking
extended three times still reports its first `days`. For actual duration use `pickupAt` and
`actualReturnAt`.

**A draft invoice has no number.** Numbers are allocated when an invoice is issued, are gapless by
UAE tax rule, and are never reused. A blank number on a draft is correct.

**Statuses are open sets.** A workspace can define its own booking and vehicle statuses. Do not
assume the ones you have seen are all of them.

## Where to go next

- **[API reference](/docs/api)** — every endpoint, with its parameters and a runnable example.
- **[Webhooks](/docs/webhooks.md)** — be told when something happens, instead of polling for it.
- **[MCP](/docs/mcp.md)** — connect Claude or ChatGPT to a workspace and ask in plain language.
- **Machine-readable spec** — `/api/v1/openapi.json`.