# HOOP Inventory Hub API — LLM / Agent cheat sheet

> For coding assistants and ops agents (Cursor, OpenClaw-style runners, etc.).
> Human help: https://hoop.956.jp/help.html#api-hub
> OpenAPI 3: https://hoop.956.jp/openapi.yaml
> Product overview: https://hoop.956.jp/llms.txt

## What this API is

- **Base URL:** `https://hoop.956.jp`
- **Style:** HTTPS JSON REST, **read-only**
- **Auth:** company API key → `Authorization: Bearer <key>` (keys usually start with `hoop_`)
- **Scopes on keys:** `catalog:read`, `stock:read`
- **Tenant:** every key is bound to one HOOP company; responses never cross companies
- **Not available yet:** write/update stock, reservations, Webhooks, OAuth user login for API

Do **not** invent POST/PATCH/DELETE endpoints. Do **not** claim OpenAPI beyond the published `openapi.yaml`.

## Issue a key (human step)

1. Sign in as company admin → **設定 → APIキー**
2. Create a named key (plaintext shown **once**)
3. Store secret in the agent/runtime vault; never commit keys

## Endpoints (copy-paste ready)

### Catalog list
```http
GET /api/v1/catalog/skus?public_only=true&exclude_discontinued=true&limit=100
Authorization: Bearer hoop_REPLACE_ME
```
Query (all optional):
- `public_only=1|true|yes` — only `is_public` SKUs
- `exclude_discontinued=1|true|yes`
- `updated_since=<ISO8601>` — incremental sync
- `limit=1..500`

### SKU detail
```http
GET /api/v1/skus/{code_or_id}
Authorization: Bearer hoop_REPLACE_ME
```
Prefer SKU **code** (`alt_id`). Internal numeric id also works.

### Stock list
```http
GET /api/v1/stock?sku_codes[]=SKU-A&sku_codes[]=SKU-B&limit=100
Authorization: Bearer hoop_REPLACE_ME
```
`sku_codes` may also be a comma-separated string.

### Single SKU stock
```http
GET /api/v1/skus/{code_or_id}/stock
Authorization: Bearer hoop_REPLACE_ME
```

## curl examples

```bash
export HOOP_API_KEY='hoop_…'
export HOOP_BASE='https://hoop.956.jp'

curl -sS -H "Authorization: Bearer $HOOP_API_KEY" \
  "$HOOP_BASE/api/v1/catalog/skus?exclude_discontinued=true&limit=50"

curl -sS -H "Authorization: Bearer $HOOP_API_KEY" \
  "$HOOP_BASE/api/v1/stock?sku_codes[]=SAMPLE-001"

curl -sS -H "Authorization: Bearer $HOOP_API_KEY" \
  "$HOOP_BASE/api/v1/skus/SAMPLE-001/stock"
```

## Response shapes (fields agents should use)

**Sku** (`skus[]` / `sku`):
`id`, `code`, `name`, `product_id`, `product_code`, `product_name`, `category_id`, `unit`,
`is_active`, `is_public`, `is_discontinued`, `updated_at`

**Stock** (`stocks[]` / `stock`):
`code`, `qty` (on hand), `free_qty` (sellable / unreserved), `safe_qty`, `unit`,
`location_code` (always `"default"` today), `is_discontinued`, `updated_at`

**meta:** `{ count, location_code: "default" }`

## Errors

| HTTP | body | meaning |
|------|------|---------|
| 401 | `{ "error": "unauthorized" }` | missing/invalid key |
| 403 | `{ "error": "forbidden", "required_scope": "…" }` | key lacks scope |
| 404 | `{ "error": "not_found" }` | SKU not in this company |

## Agent playbooks

### Sync public catalog into another system
1. `GET /api/v1/catalog/skus?public_only=true&exclude_discontinued=true`
2. Upsert by `code`
3. Next runs: add `updated_since=<last_success_iso8601>`

### Check sellable qty before promising stock
1. `GET /api/v1/skus/{code}/stock`
2. Use **`free_qty`**, not only `qty` (reservations reduce free)

### Batch stock for a SKU list
1. `GET /api/v1/stock?sku_codes[]=A&sku_codes[]=B…` (or comma list)
2. Map by `code`

### Health check for automation
1. `GET /api/v1/catalog/skus?limit=1`
2. Expect 200 + JSON; 401 → rotate/reissue key

## Safety rules for agents

- Treat API keys as secrets; redact in logs
- Rate gently; prefer `limit` + `updated_since` over full dumps every minute
- `location_code` is placeholder multi-site support — do not invent other locations
- Portal / LINE / shared links are **not** this API; do not mix auth models
- If a user asks to “update stock via API”, say write API is not available yet

## Related URLs

- OpenAPI: https://hoop.956.jp/openapi.yaml
- Help (human): https://hoop.956.jp/help.html#api-hub
- Overview: https://hoop.956.jp/llms.txt
- Sign-in (humans): https://hoop.956.jp/users/sign_in