# Ever API · Getting Started

Three steps to your first successful call. Every error response tells you how to fix it; the full error catalogue is one click away.

## Easiest: the command line (one-line install · no code)

The API as commands you can type: look up stock and read docs right after installing; `--json` for scripts; AI coding agents use it as-is.

```bash
curl -fsSL https://connect.everugg.net.au/cli/install.sh | sh
ever login --sandbox
ever stock changes AU --since 0
```

Writes need --confirm and are always drafts.

## No credentials yet? Try the sandbox (no signup · demo data)

You do not need authorisation to start. The public sandbox channel runs the whole flow — same endpoints, same response shapes — only the data is demo (DEMO-* items). It cannot touch real stock, and orders return a fake reference:

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/auth/token" -H "content-type: application/json" \
  -d '{"client_id":"sandbox","client_secret":"sandbox"}'
```

Once you have the token, follow the three steps below. Sandbox responses carry an X-Sandbox: true header. When it works, ask your account manager for real credentials.

## 0. You need two things (issued by your account manager)

A channel number (e.g. 100944) and a secret key (looks like ever_xxxxxxxx…).

The key is shown once, at issue time. We store only its hash — nobody, including your account manager, can read it back. Store it safely. If it is lost, ask for a re-issue (the old key stops working immediately).

## 1. Exchange them for a token

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/auth/token" -H "content-type: application/json" \
  -d '{"client_id":"<CHANNEL>","client_secret":"<SECRET>"}'
```

Returns {"data":{"token":"eyJ…","token_type":"Bearer","expires_in":3600,"expires_at":"…"}}. token is the key for every later call; expires_in is the remaining lifetime in seconds — just exchange again when it runs out.

## 2. Call the API with the token

Put it in the Authorization: Bearer header (the API does not accept ?token= — neither secrets nor tokens ever go in a URL):

```bash
curl "https://connect.everugg.net.au/api/v1/warehouses" -H "Authorization: Bearer <YOUR_TOKEN>"

curl "https://connect.everugg.net.au/api/v1/warehouses/AU/stock?sku=OB0021611" -H "Authorization: Bearer <YOUR_TOKEN>"
```

Which endpoints and warehouses you can reach depends on what your account manager granted. To see your own identity and permissions:

```bash
curl "https://connect.everugg.net.au/whoami" -H "Authorization: Bearer <YOUR_TOKEN>"
```

Prefer to just look? My integration shows your role, capabilities, webhooks and plans on one page.

## 3. When something goes wrong

Every error response carries error.code / message / hint / request_id / doc_url — read hint first (how to fix it); if you cannot, send the request_id to your contact.

> Example: no token → error.code=AUTH_MISSING_TOKEN, and the hint points you back to step 1.

## 4. Send an idempotency key on writes (prevents duplicate orders)

For write requests such as creating an order, send an Idempotency-Key header — a unique string per business operation (a UUID, or your own order number):

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/orders" -H "Authorization: Bearer <YOUR_TOKEN>"   -H "content-type: application/json"   -H "Idempotency-Key: 8f14e45f-ea0d-4b2a-9c1b-000000000001"   -d '{"warehouse_code":"AU","lines":[{"sku":"OB0021611","quantity":1}]}'
```

Timed out, flaky network, not sure whether it went through? Just retry with the same key. You will not create a duplicate — you get the original response back (with an Idempotency-Replayed: true header). Do not change the key on retry, or you really will place two orders.

## 5. Sync incrementally, not the whole warehouse (7.3MB to a few KB)

A full warehouse pull is 7.3MB / 31k rows / 8.5s. Do that once, remember the x-stock-version response header, then just ask what changed:

```bash
curl "https://connect.everugg.net.au/api/v1/warehouses/AU/stock/changes?since=<42>" -H "Authorization: Bearer <YOUR_TOKEN>"
```

You get changes (added/updated/removed) plus a new version — use that as your next since. If the response says full: true, you were away too long and the change log has rolled past your position: do one full pull again. The full endpoint also accepts ?page=1&pageSize=1000 (omit it and you get everything, exactly as before).

## Connect this API to your AI

The docs are already shaped for AI: llms.txt is the index and every page has a Markdown version; your assistant (Claude, Cursor …) connects over MCP or runs the Ever CLI itself. Permissions always follow your token.

## Next

- [API reference (with Try it)](https://connect.everugg.net.au/reference.md?lang=en)
- [Error catalogue (how to fix)](https://connect.everugg.net.au/reference/errors.md?lang=en)
- [Command line (CLI)](https://connect.everugg.net.au/cli?lang=en)
- [llms.txt](https://connect.everugg.net.au/llms.txt?lang=en)

---
Markdown source: https://connect.everugg.net.au/start.md?lang=en · Web page: https://connect.everugg.net.au/start?lang=en