# AI Case Summary API

Source: https://caseprimus.ai/docs/ai-case-summary-api

## AI API To Summarize Indian Court Cases And Orders, With A Risk Level

The **AI Case Summary API** turns a court case into a plain-language summary with a risk level and the reasoning behind it. CasePrimus.ai's AI reads the document of every order on the case, summarizes each one, and then summarizes the case as a whole.

Use it to give legal, risk and compliance teams conclusions instead of raw filings, or to enrich cases you have looked up with the Court Case Lookup API. The request returns immediately and you poll for the result, so each order's summary is available as soon as it is ready.

> **Built on certified infrastructure.** CasePrimus.ai is operated by Pegadroid IQ Solutions Private Limited, the legal entity behind Attestr's products, which holds ISO/IEC 27001:2022 certification. Data is hosted in India (AWS Mumbai, ap-south-1) and every connection is encrypted in transit.

## Key capabilities

- **A case summary in plain language.** A short written summary of where the case stands, instead of pages of filings.
- **A risk level with its reasoning.** Every summary comes with a risk level and a written justification, so your team can see why.
- **A summary for every order.** Each order is summarized individually. Order summaries appear on every poll as they finish, so you can show progress.
- **Works on any looked-up case.** Summarize a case you found with the Court Case Lookup API, without adding it to a watchlist.
- **Regenerate any time.** Every request starts a new summary. The most recent one is also returned as `latestSummary` on the case lookup.
- **Simple request and poll.** Start the summary, then poll until its status is `COMPLETE`. A case with no orders completes immediately.

## How it works

1. **Look up the case.** Call the Court Case Lookup API and keep the `searchId` it returns.
2. **Request a summary.** Send the `searchId` to `POST /case-lookup/summarize`. You get an `_id` back immediately.
3. **Poll for the result.** Call `GET /case-lookup/summarize/{id}` until the status is `COMPLETE`. The summary, risk level and order summaries come back on every poll.

## API definition

### Generate an AI case summary and risk level, on demand

Generates an AI summary of a case you have looked up, with a risk level and the reasoning behind it, without adding the case to a watchlist. Send the searchId from the case lookup. CasePrimus reads the document of every order and summarizes the case. The call returns immediately with an _id; poll the summary endpoint for the result. A case with no orders completes immediately. Every call starts a new summary, so call it again to regenerate. The most recent summary is also returned as latestSummary on the case lookup. Requires case.write.

**Request URL**

`POST https://api.caseprimus.ai/api/caseprimus/v1/case-lookup/summarize`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `Content-Type` | `application/json` | Required |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Input parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `searchId` | string | Required | The searchId returned by the case lookup. |

**Sample request**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl -X POST "$BASE/case-lookup/summarize" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId": "CPCSH0exampledemo0001"
  }'
```

**Responses**

- `200`: Summarization job queued (or completed immediately for a case with no orders to read).
- `400`: Malformed input, or the underlying case lookup failed.
- `403`: Caller lacks the case.write permission.

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `_id` | string |  | The id of the summary request. Use it to poll for the result. |
| `status` | enum |  | One of: PENDING, COMPLETE, FAILED |

**Example response (200)**

```json
{
  "_id": "CPCSS0exampledemo0001",
  "status": "PENDING"
}
```

### Poll an on-demand case summary

Returns the current status of a summary you requested. orderSummaries, riskLevel and caseSummary are included on every poll, not only once the status is COMPLETE, so you can show each order's summary as soon as it finishes. Poll until the status is COMPLETE. Requires case.read.

**Request URL**

`GET https://api.caseprimus.ai/api/caseprimus/v1/case-lookup/summarize/{id}`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Required | The _id returned when you requested the summary. |

**Sample request**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/case-lookup/summarize/SUMMARIZE_ID" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
```

**Responses**

- `200`: Current summarization status.
- `400`: This summary request does not exist.
- `403`: Caller lacks the case.read permission.

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `_id` | string |  | The id of the summary request. |
| `status` | enum |  | One of: PENDING, COMPLETE, FAILED |
| `riskLevel` | string or null |  | The risk level once the summary is complete: VERY_HIGH, HIGH, MODERATE, LOW or UNCLASSIFIED. Null until then. |
| `caseSummary` | string or null |  | The summary of the case. Null until it is complete. |
| `riskJustification` | string or null |  | Why this risk level was given. Null until the summary is complete. |
| `orderSummaries` | array of object |  | A summary for each order, each with its own status. |
| `error` | string or null |  | Why the summary failed, if it did. Otherwise null. |

**Example response (200)**

```json
{
  "_id": "CPCSS0exampledemo0001",
  "status": "PENDING",
  "riskLevel": null,
  "caseSummary": null,
  "riskJustification": null,
  "orderSummaries": [
    {
      "orderNumber": "1",
      "status": "COMPLETE",
      "summary": "Interim order granting a short adjournment."
    },
    {
      "orderNumber": "2",
      "status": "PENDING"
    }
  ],
  "error": null
}
```

## Summary statuses

| Status | Meaning |
| --- | --- |
| PENDING | The summary is still being produced. Order summaries that are finished are already included. |
| COMPLETE | The summary, risk level and risk justification are ready. |
| FAILED | The summary could not be produced. The `error` field says why. |

## Risk levels

The `riskLevel` field uses these values.

| Value | Meaning |
| --- | --- |
| VERY_HIGH | Very high risk |
| HIGH | High risk |
| MODERATE | Moderate risk |
| LOW | Low risk |
| UNCLASSIFIED | No risk level has been assigned |

> **Decision support, not legal advice.** Summaries and risk levels are produced by AI to help your team review a case faster. Have a qualified person confirm anything you rely on.

## Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | 60435 | This case summary request does not exist |

## Frequently asked questions

### What does the AI Case Summary API return?

A plain-language case summary, a risk level, a written risk justification, and a summary for each order on the case.

### Do I need to add the case to a watchlist first?

No. Look the case up with the Court Case Lookup API and send its searchId. Cases on a watchlist are summarized automatically, and you receive a case.summary_refreshed event when a summary is refreshed.

### How long does a summary take?

The request returns immediately with an _id. The summary is ready when the status is COMPLETE, which depends on how many orders the case has. Order summaries appear on every poll as they finish.

### Can I generate a summary again?

Yes. Every request starts a new summary. The most recent one is returned as latestSummary on the case lookup.

### Is the risk level legal advice?

No. The summary and risk level are produced by AI as decision support. Have a qualified person confirm anything you rely on.