> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrubbe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ezra API: AI incident analysis and pattern detection

> Run Ezra's four-stage reasoning pipeline on incidents, generate audience-specific reports, submit outcome feedback, and query failure patterns.

Ezra is Scrubbe's embedded AI reasoning engine. When you submit an incident for analysis, Ezra runs a four-stage pipeline — context gathering, hypothesis generation, impact assessment, and remediation planning — producing a structured root cause analysis with confidence scoring. You can then generate audience-specific reports from that analysis, submit outcome feedback so Ezra learns from every incident, and query the recurring failure patterns it has detected across your incident history.

<Note>
  All endpoints require `Authorization: Bearer <token>`. Analysis runs asynchronously — submit with `POST /analyse` and poll `GET /analysis/:incidentId` until `status` is `COMPLETE`.
</Note>

**Base path:** `https://your-api-domain.com/api/v1/ezra`

***

## Analyse an incident

Submit an incident to Ezra for AI analysis. Ezra examines the incident timeline, affected services, correlated signals, and recent changes to produce a root cause analysis, impact assessment, and remediation options.

`POST https://your-api-domain.com/api/v1/ezra/analyse`

<ParamField body="incidentId" type="string" required>
  ID of the incident to analyse.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api-domain.com/api/v1/ezra/analyse \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{ "incidentId": "INC-20260522-0041" }'
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch('https://your-api-domain.com/api/v1/ezra/analyse', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ incidentId: 'INC-20260522-0041' }),
  });
  const { data } = await resp.json();
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      'https://your-api-domain.com/api/v1/ezra/analyse',
      headers={'Authorization': 'Bearer <token>'},
      json={'incidentId': 'INC-20260522-0041'},
  )
  print(resp.json())
  ```
</CodeGroup>

<ResponseField name="analysisId" type="string" required>Unique identifier for this analysis run.</ResponseField>
<ResponseField name="incidentId" type="string" required>The incident being analysed.</ResponseField>
<ResponseField name="status" type="string" required>`PROCESSING` while the pipeline is running; `COMPLETE` or `FAILED` when done.</ResponseField>
<ResponseField name="estimatedCompletionSeconds" type="number">Approximate seconds before the analysis is ready to retrieve.</ResponseField>

***

## List all analyses

Returns all completed and in-progress analyses for the workspace, ordered by creation date descending. Use this to audit Ezra activity or populate a history view.

`GET https://your-api-domain.com/api/v1/ezra/analyses`

<ParamField query="page" type="number" default="1">Page number.</ParamField>
<ParamField query="limit" type="number" default="20">Items per page (max 100).</ParamField>
<ParamField query="status" type="string">Filter by analysis status: `PROCESSING`, `COMPLETE`, or `FAILED`.</ParamField>

```bash cURL theme={null}
curl "https://your-api-domain.com/api/v1/ezra/analyses?status=COMPLETE&limit=50" \
  -H "Authorization: Bearer <token>"
```

<ResponseField name="data" type="object[]">Array of analysis summary objects.</ResponseField>
<ResponseField name="total" type="number">Total matching analysis count.</ResponseField>

***

## Get the latest analysis for an incident

Returns the most recently completed analysis for a specific incident, including hypothesis, root cause, impact assessment, remediation options, and confidence score.

`GET https://your-api-domain.com/api/v1/ezra/analysis/:incidentId`

<ParamField path="incidentId" type="string" required>
  The incident ID.
</ParamField>

```bash cURL theme={null}
curl https://your-api-domain.com/api/v1/ezra/analysis/INC-20260522-0041 \
  -H "Authorization: Bearer <token>"
```

<ResponseField name="analysisId" type="string" required>Unique analysis identifier.</ResponseField>
<ResponseField name="status" type="string" required>Analysis lifecycle status.</ResponseField>
<ResponseField name="hypothesis" type="string">Ezra's leading hypothesis from the hypothesis-generation stage.</ResponseField>
<ResponseField name="rootCause" type="string">AI-identified primary cause of the incident.</ResponseField>
<ResponseField name="impactAssessment" type="string">Structured assessment of user and business impact.</ResponseField>
<ResponseField name="contributingFactors" type="string[]">Secondary factors that amplified impact or extended duration.</ResponseField>
<ResponseField name="remediationOptions" type="string[]">Ordered list of recommended remediation steps.</ResponseField>
<ResponseField name="confidence" type="number">Confidence score from `0` to `1`. Scores above `0.8` indicate high certainty.</ResponseField>
<ResponseField name="completedAt" type="string">ISO 8601 timestamp when the analysis pipeline finished.</ResponseField>

***

## Generate a report

Generate a written report from a completed analysis, tailored to the target audience. Engineering reports include technical detail, system context, and step-by-step remediation. Leadership reports focus on business impact, timeline, and recovery status.

`POST https://your-api-domain.com/api/v1/ezra/report`

<ParamField body="analysisId" type="string" required>
  ID of the completed analysis to generate a report from.
</ParamField>

<ParamField body="audience" type="string" required>
  Target audience: `ENGINEER` or `LEADERSHIP`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api-domain.com/api/v1/ezra/report \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{ "analysisId": "ANLYS-20260522-0099", "audience": "LEADERSHIP" }'
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch('https://your-api-domain.com/api/v1/ezra/report', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      analysisId: 'ANLYS-20260522-0099',
      audience: 'LEADERSHIP',
    }),
  });
  const { data } = await resp.json();
  ```
</CodeGroup>

<ResponseField name="reportId" type="string" required>Unique identifier for the generated report.</ResponseField>
<ResponseField name="audience" type="string" required>The audience the report was generated for: `ENGINEER` or `LEADERSHIP`.</ResponseField>
<ResponseField name="content" type="string" required>The generated report text.</ResponseField>
<ResponseField name="generatedAt" type="string" required>ISO 8601 timestamp of report generation.</ResponseField>

***

## Submit outcome feedback

Send outcome feedback to Ezra after an incident is fully resolved. Ezra uses this signal to improve hypothesis accuracy and pattern detection over time. Submit one feedback record per incident.

`POST https://your-api-domain.com/api/v1/ezra/learn`

<ParamField body="incidentId" type="string" required>
  ID of the resolved incident.
</ParamField>

<ParamField body="outcome" type="string" required>
  Resolution outcome: `RESOLVED`, `DEGRADED`, `NEUTRAL`, or `WORSENED`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api-domain.com/api/v1/ezra/learn \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{ "incidentId": "INC-20260522-0041", "outcome": "RESOLVED" }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      'https://your-api-domain.com/api/v1/ezra/learn',
      headers={'Authorization': 'Bearer <token>'},
      json={'incidentId': 'INC-20260522-0041', 'outcome': 'RESOLVED'},
  )
  print(resp.json())
  ```
</CodeGroup>

| Outcome    | When to use                                                              |
| ---------- | ------------------------------------------------------------------------ |
| `RESOLVED` | Incident fully resolved; Ezra's suggestions were accurate and helpful.   |
| `DEGRADED` | Incident partially resolved; situation improved but not fully recovered. |
| `NEUTRAL`  | No clear improvement or worsening from the recommended actions.          |
| `WORSENED` | Following Ezra's suggestions made the situation worse.                   |

<Tip>
  Call `POST /learn` after every resolved incident to improve Ezra's pattern detection and future recommendation quality.
</Tip>

***

## Get detected patterns

Returns recurring failure patterns that Ezra has identified across your incident history. Use this to find systemic weaknesses and prioritise reliability improvements before the next incident.

`GET https://your-api-domain.com/api/v1/ezra/patterns`

```bash cURL theme={null}
curl https://your-api-domain.com/api/v1/ezra/patterns \
  -H "Authorization: Bearer <token>"
```

<ResponseField name="data" type="object[]">
  Array of detected failure patterns.

  <Expandable title="pattern object">
    <ResponseField name="patternId" type="string" required>Unique pattern identifier.</ResponseField>
    <ResponseField name="description" type="string" required>Human-readable description of the recurring failure pattern.</ResponseField>
    <ResponseField name="occurrences" type="number" required>Number of incidents matching this pattern.</ResponseField>
    <ResponseField name="affectedServices" type="string[]">Services involved in incidents that match this pattern.</ResponseField>
    <ResponseField name="firstSeen" type="string">ISO 8601 timestamp of the earliest matching incident.</ResponseField>
    <ResponseField name="lastSeen" type="string">ISO 8601 timestamp of the most recent matching incident.</ResponseField>
    <ResponseField name="suggestedFix" type="string">Ezra's recommended action to eliminate the pattern.</ResponseField>
  </Expandable>
</ResponseField>

***

## Ezra reasoning pipeline

Ezra processes each analysis through four sequential stages. Understanding the pipeline helps you interpret confidence scores and result structure.

| Stage | Name                  | What Ezra does                                                                                |
| ----- | --------------------- | --------------------------------------------------------------------------------------------- |
| 1     | Context gathering     | Collects the incident timeline, correlated signals, deployment history, and service topology. |
| 2     | Hypothesis generation | Proposes candidate root causes ranked by supporting evidence.                                 |
| 3     | Impact assessment     | Quantifies user and business impact from service dependency data.                             |
| 4     | Remediation planning  | Produces ordered remediation options weighted by historical outcome data.                     |