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

# API Reference

> Complete API documentation for CAS Parser.

## Base URL

```
https://api.casparser.in
```

## Authentication

All API requests require an `x-api-key` header:

```bash theme={null}
curl -X POST https://api.casparser.in/v4/smart/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@cas.pdf" \
  -F "password=ABCDE1234F"
```

<Tip>
  **Sandbox:** Use `sandbox-with-json-responses` for testing without consuming credits.
</Tip>

## Access Tokens

For frontend/SDK use, generate short-lived tokens from your backend:

```python theme={null}
response = requests.post(
    "https://api.casparser.in/v1/token",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"expiry_minutes": 30}
)
token = response.json()["access_token"]  # at_xxx
```

Access tokens (`at_` prefix) can replace API keys on all `/v4/*` endpoints.

## Endpoints

### Parsing

| Method | Endpoint                  | Description                    |
| ------ | ------------------------- | ------------------------------ |
| POST   | `/v4/smart/parse`         | Auto-detect CAS type and parse |
| POST   | `/v4/cdsl/parse`          | Parse CDSL eCAS                |
| POST   | `/v4/nsdl/parse`          | Parse NSDL eCAS                |
| POST   | `/v4/cams_kfintech/parse` | Parse CAMS/KFintech CAS        |
| POST   | `/v4/contract_note/parse` | Parse broker contract notes    |

### Data Retrieval

| Method | Endpoint                             | Description                    |
| ------ | ------------------------------------ | ------------------------------ |
| POST   | `/v4/kfintech/generate`              | Request CAS via KFintech email |
| POST   | `/v4/cdsl/fetch`                     | CDSL OTP request (Step 1)      |
| POST   | `/v4/cdsl/fetch/{session_id}/verify` | CDSL OTP verify (Step 2)       |

### Email Import

| Method | Endpoint               | Description               |
| ------ | ---------------------- | ------------------------- |
| POST   | `/v4/inbox/connect`    | Get Gmail OAuth URL       |
| POST   | `/v4/inbox/status`     | Check connection status   |
| POST   | `/v4/inbox/cas`        | List/parse CAS from inbox |
| POST   | `/v4/inbox/disconnect` | Revoke access             |

### Account

| Method | Endpoint            | Description             |
| ------ | ------------------- | ----------------------- |
| POST   | `/v1/credits`       | Check remaining credits |
| POST   | `/v1/usage`         | Get usage logs          |
| POST   | `/v1/usage/summary` | Get aggregated usage    |
| POST   | `/v1/token`         | Generate access token   |
| POST   | `/v1/token/verify`  | Verify access token     |

## Response Format

All parsing endpoints return a unified JSON structure:

```json theme={null}
{
  "meta": {
    "cas_type": "CDSL",
    "statement_period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "generated_at": "2024-02-01T10:30:00Z"
  },
  "investor": {
    "name": "John Doe",
    "pan": "ABCDE1234F"
  },
  "summary": {
    "total_value": 2500000.00,
    "accounts": {
      "demat": { "count": 2, "total_value": 1500000.00 },
      "mutual_funds": { "count": 5, "total_value": 1000000.00 }
    }
  },
  "demat_accounts": [...],
  "mutual_funds": [...],
  "insurance": {...},
  "nps": [...]
}
```

## Error Handling

```json theme={null}
{
  "status": "failed",
  "msg": "Invalid password for PDF"
}
```

| Status | Meaning              | Retry?                    |
| ------ | -------------------- | ------------------------- |
| 400    | Bad request          | No — fix request          |
| 401    | Invalid API key      | No — check key            |
| 402    | Insufficient credits | No — upgrade plan         |
| 500    | Server error         | Yes — exponential backoff |

## Request ID

Every response includes `X-Request-ID`:

```
X-Request-ID: req_2xYz7KpL8mN3Ab
```

Include this when contacting support.