---
title: "Oee Narrator"
method: POST
path: "/api/agents/oee-narrator"
---

# Oee Narrator

`POST /api/agents/oee-narrator`

## Request

- Base URL: `https://opwhcervi3.execute-api.ca-central-1.amazonaws.com`
- URL: `https://opwhcervi3.execute-api.ca-central-1.amazonaws.com/api/agents/oee-narrator`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Explains OEE from supplied current or historical production data; customer-local capture or historian setup supplies that data. Included in dxpert Pro; a free account may use its Try Pro runs (5 lifetime, pooled across agents), after which the endpoint answers 402 pro_required. API key or bearer authentication is required; a successful run uses the dxpert Pro allowance or one Try Pro run. No billing, email, or persistent server state is changed.

## Headers

- `Authorization` string, nullable
- `X-Api-Key` string, nullable

## Request body

- OeeNarratorRequest
  - `config` object, nullable
  - `downtime` ShiftDowntimeRecord[]
    - `category` string, required
    - `cell` string, required
    - `end` string, date-time, required
    - `reason` string, required
    - `start` string, date-time, required
  - `events` ShiftRawEvent[]
    - `payload` union, required
      - string
      - integer
      - number
      - boolean
      - object
    - `topic` string, required
    - `ts` string, date-time, required
  - `ideal_rate_per_min` object
  - `planned_minutes` integer, required
  - `production` ShiftProductionRecord[]
    - `cell` string, required
    - `good_count` integer, required
    - `scrap_count` integer, required
    - `ts` string, date-time, required
  - `quality` ShiftQualityRecord[]
    - `cell` string, required
    - `disposition` string, required
    - `issue` string, required
    - `ts` string, date-time, required
  - `question` string, nullable
  - `site_profile` ShiftSiteProfile, required
    - `language` 'en' | 'fr' | 'de' | 'es'
    - `line` string, required
    - `plant` string, required
    - `shift_label` string, required
    - `window_end` string, date-time, required
    - `window_start` string, date-time, required

## Response `200`

Successful Response

- OeeNarratorResponse
  - `coverage` ShiftReportCoverage
    - `mode` 'structured' | 'discovery' | 'config', required
    - `roles_found` string[], required
    - `roles_missing` string[], required
    - `topics_ignored` integer, required
    - `topics_used` integer, required
  - `kpis` OeeKpis, required
    - `cells` object, required
    - `total` OeeCellKpis, required
      - `availability` number, nullable, required
      - `downtime_minutes` integer, required
      - `good_count` integer, required
      - `missing` string[]
      - `oee` number, nullable, required
      - `performance` number, nullable, required
      - `quality` number, nullable, required
      - `runtime_minutes` integer, required
      - `scrap_count` integer, required
  - `namespace_recommendations` ShiftNamespaceRecommendation[]
    - `gap` string, required
    - `recommended_topics` string[], required
    - `unlocks` string, required
  - `report_markdown` string, required

## Other responses

- `401`: Missing, malformed, or invalid credentials.
- `402`: Credentials are valid but the account's plan does not include this capability (for example, Try Pro is used up and dxpert Pro is not active).
- `422`: Validation Error
- `429`: The applicable rate or quota limit has been reached. `quota_exceeded` names the limit in `scope` (for example `free_quota`: the free Advisor's 10 questions this month). `pro_allowance_exhausted`: the dxpert Pro monthly allowance, shared by the Advisor and every agent, is used up; service resumes when it renews (`resets_at`). There is no overage and nothing extra to buy.
- `502`: `llm_error`: the language-model provider failed. Retry later.

---

[API](https://skmtc.dev/dxpert/apis/dxpert-ai-api.md) · [All operations](https://skmtc.dev/dxpert/apis/dxpert-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dxpert/apis/dxpert-ai-api/revisions/460f1c8c53d1?raw)