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

# API

> Every route of the customer API, what it takes and what it answers.

Read your organization's cases and approve or reject their actions, with an API key made in the app, under Settings, then API.

## Keys

An API key made in the app, under Settings, then API, with the read or approve scope.
Send it in the header `authorization: Bearer <API key>` to `https://api.casefile.win`.

## The organization's cases, newest first

`GET https://api.casefile.win/v1/cases`

```bash curl theme={null}
# Lists your organization's cases with an API key, which CASEFILE_API_KEY holds.
curl --fail-with-body --silent --show-error \
  "${CASEFILE_API:-https://api.casefile.win}/v1/cases" \
  -H "authorization: Bearer $CASEFILE_API_KEY"
```

### Answers

| Status | When |
| - | - |
| `200` | Its cases. |
| `401` | The key is missing, unknown, revoked or expired. |
| `403` | The key lacks the scope, or the key's creator may not do this now. |
| `409` | The organization is closing. |
| `429` | The key is over its rate limit ("over limit"). Or the API was sent more keys it has not seen than it looks up for now, from this address or from everyone ("too many keys to check"). It says this before it looks the key up, so it tells nothing about whether the key exists. |
| `503` | The API cannot check keys just now. |

### What `200` holds

| Field | Type | Required | What it is |
| - | - | - | - |
| `cases` | array | Yes | Every case, newest first. |
| `cases[].id` | string | Yes | The case's ID. |
| `cases[].eventId` | string | Yes | The ID of what opened the case. |
| `cases[].source` | string | No | The source the case is about, when it names one. |
| `cases[].kind` | string | Yes | What opened it: success-drop, release-regression or tracking-gap. |
| `cases[].finding` | string or null | Yes | What Casefile saw, in a sentence, or null. |
| `cases[].correction` | string or null | Yes | How events that arrived late changed what Casefile sees, or null. |
| `cases[].traceId` | string | Yes | Quote this when asking about the case. |
| `cases[].openedAt` | string | Yes | When it opened, in ISO 8601. |

## One case, with the action waiting on it, if any

`GET https://api.casefile.win/v1/cases/{id}`

### Parameters

| Parameter | In | Type | What it is |
| - | - | - | - |
| `id` | path | string, matching `^[1-9]\d{0,17}$` | A case's ID, as the web app's case page shows it. |

### Answers

| Status | When |
| - | - |
| `200` | The case. |
| `400` | Not a case ID. |
| `401` | The key is missing, unknown, revoked or expired. |
| `403` | The key lacks the scope, or the key's creator may not do this now. |
| `404` | The organization has no case with this ID. |
| `409` | The organization is closing. |
| `429` | The key is over its rate limit ("over limit"). Or the API was sent more keys it has not seen than it looks up for now, from this address or from everyone ("too many keys to check"). It says this before it looks the key up, so it tells nothing about whether the key exists. |
| `503` | The API cannot check keys just now. |

### What `200` holds

| Field | Type | Required | What it is |
| - | - | - | - |
| `id` | string | Yes | The case's ID. |
| `eventId` | string | Yes | The ID of what opened the case. |
| `source` | string | No | The source the case is about, when it names one. |
| `kind` | string | Yes | What opened it: success-drop, release-regression or tracking-gap. |
| `finding` | string or null | Yes | What Casefile saw, in a sentence, or null. |
| `correction` | string or null | Yes | How events that arrived late changed what Casefile sees, or null. |
| `traceId` | string | Yes | Quote this when asking about the case. |
| `openedAt` | string | Yes | When it opened, in ISO 8601. |
| `action` | object or null | Yes | The action waiting on the case, or null. |
| `action.proposalToken` | string | Yes | Send this with an approval, so it decides this proposal and no newer one. |
| `action.kind` | string | Yes | What the action does, such as pause-provider. |
| `action.state` | string | Yes | Where it stands: awaiting-approval, approved, sending, applied, refused, unknown, rejected, expired, cancelled or over-limit. |
| `action.approvalDueAt` | string | Yes | When it expires unless approved, in ISO 8601. |
| `action.canDecide` | boolean | Yes | Whether an approval or rejection sent now can be recorded. |

## Approve or reject a case's proposed action

`POST https://api.casefile.win/v1/cases/{id}/decision`

Needs a key with the approve scope whose creator may approve.

### Parameters

| Parameter | In | Type | What it is |
| - | - | - | - |
| `id` | path | string, matching `^[1-9]\d{0,17}$` | A case's ID, as the web app's case page shows it. |

### Body

| Field | Type | Required | What it is |
| - | - | - | - |
| `proposalToken` | string, matching `^\d{1,18}$` | Yes | The proposal's token, from the case. |
| `answer` | `approve` or `reject` | Yes | Whether to approve or reject it. |

### Answers

| Status | When |
| - | - |
| `200` | Decided, or why it could not be. |
| `400` | Not a case, a proposal or an answer. |
| `401` | The key is missing, unknown, revoked or expired. |
| `403` | The key lacks the scope, or the key's creator may not do this now. |
| `404` | The organization has no such case or proposal. |
| `409` | The organization is closing. |
| `429` | The key is over its rate limit ("over limit"). Or the API was sent more keys it has not seen than it looks up for now, from this address or from everyone ("too many keys to check"). It says this before it looks the key up, so it tells nothing about whether the key exists. |
| `503` | The API cannot check keys just now. |

### What `200` holds

| Field | Type | Required | What it is |
| - | - | - | - |
| `result` | `approved` or `rejected` or `already-decided` or `case-closed` or `superseded` or `expired` or `read-only` | Yes | What became of the decision. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.