# Longhorn OEE Analysis Web API — LLM / Agent cheat sheet

> For coding assistants and ops agents (Cursor, OpenClaw-style runners, ChatGPT Actions, etc.).
> Human docs: https://longhorn.956.jp/mcp
> OpenAPI 3: https://longhorn.956.jp/openapi.yaml
> Product overview: https://longhorn.956.jp/llms.txt

## What this API is

- **Base URL:** `https://longhorn.956.jp`
- **Style:** HTTPS JSON REST + MCP JSON-RPC (`POST /mcp`)
- **Auth:** `Authorization: Bearer <LONGHORN_API_KEY>`, or `X-API-KEY`, or JSON/query `api_key`
- **Demo key:** `956-LONGHORN-DEMO-xyz-abc` — calculates only; does **not** persist history
- **Computes on Longhorn:** OEE + 工場長診断 (`diagnosis.engine: foreman`). Do **not** re-derive OEE in the LLM.
- **Not this API:** Studio UI login, personal kiosk tokens (`/kiosk/TOKEN`), billing

Do **not** invent endpoints beyond `openapi.yaml`. Do **not** print/commit/share real API keys.

## Issue a key (human step)

1. Sign up / sign in → Studio → API key (or use the demo key for calculate-only trials)
2. Store secret in the agent/runtime vault; never paste plaintext keys into chats or commits

## Endpoints (copy-paste ready)

### Shot (live OEE) — 1 API call
```http
POST /api/v1/oee/oee_shot
Content-Type: application/json
Authorization: Bearer LONGHORN_API_KEY

{
  "keyword": "鋳造ライン",
  "oee_parameters": {
    "planned_production_time_sec": 36000,
    "planned_downtime_sec": 1800,
    "loss_time_sec": 30,
    "ideal_cycle_time_sec": 30,
    "total_count": 1000,
    "defect_count": 20
  }
}
```

### Set (period OEE) — API calls = number of days
```http
POST /api/v1/oee/oee_set
Content-Type: application/json
Authorization: Bearer LONGHORN_API_KEY

{
  "keyword": "鋳造ライン",
  "daily_data": [
    {
      "date": "2026-09-01",
      "planned_production_time_sec": 36000,
      "planned_downtime_sec": 1800,
      "loss_time_sec": 30,
      "ideal_cycle_time_sec": 30,
      "total_count": 1000,
      "defect_count": 20
    }
  ]
}
```

### What-if (no history) — max 8 scenarios
```http
POST /api/v1/oee/oee_whatif
Content-Type: application/json
Authorization: Bearer LONGHORN_API_KEY

{
  "oee_parameters": {
    "planned_production_time_sec": 36000,
    "planned_downtime_sec": 1800,
    "loss_time_sec": 30,
    "ideal_cycle_time_sec": 30,
    "total_count": 1000,
    "defect_count": 20
  },
  "scenarios": [
    { "preset": "zero_defects" },
    { "preset": "zero_stops" },
    { "preset": "cut_defects_10pct" },
    { "preset": "cycle_minus_5pct" }
  ]
}
```
Presets: `zero_defects`, `zero_stops` (zero stop time **and** recover units), `cut_defects_10pct`, `cycle_minus_5pct`.
Omitting `scenarios` uses those four defaults.

### Retrieve shot history (not for demo key)
```http
GET /api/v1/oee/retrieve_shot?count=50
Authorization: Bearer LONGHORN_API_KEY
```

### MCP tool call (same math as REST)
```http
POST /mcp
Content-Type: application/json
Authorization: Bearer LONGHORN_API_KEY

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "oee_shot",
    "arguments": {
      "keyword": "鋳造ライン",
      "planned_production_time_sec": 36000,
      "planned_downtime_sec": 1800,
      "loss_time_sec": 30,
      "ideal_cycle_time_sec": 30,
      "total_count": 1000,
      "defect_count": 20
    }
  }
}
```
MCP tools: `oee_shot`, `oee_set`, `oee_whatif`, `oee_retrieve_shot`.

## curl examples

```bash
export LONGHORN_API_KEY='956-LONGHORN-DEMO-xyz-abc'
export LONGHORN_BASE='https://longhorn.956.jp'

curl -sS -H "Authorization: Bearer $LONGHORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"oee_parameters":{"planned_production_time_sec":36000,"planned_downtime_sec":1800,"loss_time_sec":30,"ideal_cycle_time_sec":30,"total_count":1000,"defect_count":20}}' \
  "$LONGHORN_BASE/api/v1/oee/oee_shot"
```

## Response fields agents should use

- **OEE:** `oee_result.oee`, `.availability`, `.performance`, `.quality` (or equivalent nested keys in set aggregates)
- **診断:** `diagnosis` — deterministic 工場長診断; treat `primary_loss` / levers as authoritative; expand in Japanese, do not contradict
- **What-if:** `baseline` + `scenarios[]` with assumed OEE
- **Billing:** shot = 1 call; set = 1 call per day in `daily_data`

## Agent playbooks

### Live line OEE now
1. `POST /api/v1/oee/oee_shot` with current counters
2. Read `oee_result` + `diagnosis`
3. Optionally open kiosk scoreboard for humans (`/kiosk` demo)

### Period review / weekly report
1. Build `daily_data[]` with `date`
2. `POST /api/v1/oee/oee_set`
3. Use aggregate + per-day trends; Studio 「ChatGPTに評価を依頼」 is optional interpretation only

### “What if defects/stops improve?”
1. Same shot inputs → `POST /api/v1/oee/oee_whatif`
2. Prefer presets; for `zero_stops` explain recovered units are added (stops alone without units hurts Performance)

### Wire Claude / Cursor as tools
1. Register remote MCP URL `https://longhorn.956.jp/mcp` with Bearer header
2. Or paste this cheat sheet / OpenAPI into the agent and generate REST clients

### Health check
1. Shot with demo key → expect 200 + `success` / OEE numbers
2. 401 → bad key; demo key must not be used for retrieve/history

## Safety rules for agents

- Never invent write/admin endpoints
- Never claim the LLM calculated OEE — Longhorn did
- Redact keys in logs; prefer env `LONGHORN_API_KEY`
- Demo key: calculate only, no retrieve history
- Do not treat `/studio` or `/kiosk/<token>` as public API docs

## Related URLs

- OpenAPI: https://longhorn.956.jp/openapi.yaml
- MCP docs: https://longhorn.956.jp/mcp
- Overview: https://longhorn.956.jp/llms.txt
- Demo simulator: https://longhorn.956.jp/pages/simulator
- Sign-up: https://longhorn.956.jp/users/sign_up