---
title: "Maintenance Copilot"
method: POST
path: "/api/agents/maintenance-copilot"
---

# Maintenance Copilot

`POST /api/agents/maintenance-copilot`

## Request

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

Answers from supplied maintenance history and recent asset events; it does not directly access customer systems. 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

- MaintenanceCopilotRequest
  - `asset` string, required
  - `config` object, nullable
  - `history` MaintenanceHistoryRecord[], required
    - `description` string, required
    - `kind` 'work_order' | 'fault' | 'note' | 'inspection', required
    - `status` string, nullable
    - `ts` string, date-time, required
  - `messages` MaintenanceMessage[], required
    - `content` string, required
    - `role` 'user' | 'assistant', required
  - `recent_events` ShiftRawEvent[]
    - `payload` union, required
      - string
      - integer
      - number
      - boolean
      - object
    - `topic` string, required
    - `ts` string, date-time, required
  - `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

- MaintenanceCopilotResponse
  - `coverage` MaintenanceCoverage, required
    - `gaps` string[]
    - `history_records` integer, required
    - `messages` integer, required
    - `mode` 'structured', required
    - `recent_events` integer, required
  - `namespace_recommendations` ShiftNamespaceRecommendation[]
    - `gap` string, required
    - `recommended_topics` string[], required
    - `unlocks` string, required
  - `recurrences` MaintenanceRecurrence[], required
    - `count` integer, required
    - `descriptions` string[], required
    - `first_ts` string, date-time, required
    - `last_ts` string, date-time, required
    - `similarity` number, required
    - `theme` string, required
  - `reply` 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)