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

# API Overview

> DebtStack REST API reference

## Base URL

```
https://api.debtstack.ai/v1
```

## Authentication

All requests require an API key in the `X-API-Key` header:

```bash theme={null}
curl "https://api.debtstack.ai/v1/companies" \
  -H "X-API-Key: ds_xxxxx"
```

## Endpoints

DebtStack provides 14 core primitives for corporate debt analysis:

### Companies

| Method | Endpoint                         | Description                      | Cost   |
| ------ | -------------------------------- | -------------------------------- | ------ |
| GET    | `/v1/companies`                  | Search and filter companies      | \$0.05 |
| GET    | `/v1/companies/{ticker}/changes` | Get recent changes for a company | \$0.10 |

### Bonds

| Method | Endpoint            | Description                        | Cost   |
| ------ | ------------------- | ---------------------------------- | ------ |
| GET    | `/v1/bonds`         | Search and filter bonds            | \$0.05 |
| GET    | `/v1/bonds/resolve` | Resolve CUSIP/ISIN to bond details | \$0.05 |

### Financials

| Method | Endpoint         | Description                      | Cost   |
| ------ | ---------------- | -------------------------------- | ------ |
| GET    | `/v1/financials` | Get financial metrics and ratios | \$0.05 |

### Collateral

| Method | Endpoint         | Description                         | Cost   |
| ------ | ---------------- | ----------------------------------- | ------ |
| GET    | `/v1/collateral` | Get collateral and security details | \$0.05 |

### Covenants

| Method | Endpoint                | Description                        | Cost          |
| ------ | ----------------------- | ---------------------------------- | ------------- |
| GET    | `/v1/covenants`         | Search covenant terms              | \$0.05        |
| GET    | `/v1/covenants/compare` | Compare covenants across companies | Business only |

### Ratings

| Method | Endpoint      | Description                                         | Cost   |
| ------ | ------------- | --------------------------------------------------- | ------ |
| GET    | `/v1/ratings` | Search credit rating history (S\&P, Moody's, Fitch) | \$0.05 |

### Market Data

| Method | Endpoint         | Description                                            | Cost   |
| ------ | ---------------- | ------------------------------------------------------ | ------ |
| GET    | `/v1/market/cds` | CDS spread time series (bond spread-to-treasury proxy) | \$0.05 |

### Entities

| Method | Endpoint                | Description                   | Cost   |
| ------ | ----------------------- | ----------------------------- | ------ |
| POST   | `/v1/entities/traverse` | Traverse entity relationships | \$0.15 |

### Documents

| Method | Endpoint               | Description                                    | Cost   |
| ------ | ---------------------- | ---------------------------------------------- | ------ |
| GET    | `/v1/documents/search` | Search SEC filings (keyword, semantic, hybrid) | \$0.15 |

### Batch

| Method | Endpoint    | Description                 | Cost              |
| ------ | ----------- | --------------------------- | ----------------- |
| POST   | `/v1/batch` | Execute multiple operations | Sum of operations |

### Coverage

| Method | Endpoint               | Description                                | Cost |
| ------ | ---------------------- | ------------------------------------------ | ---- |
| POST   | `/v1/coverage/request` | Request coverage for non-covered companies | Free |

### Business-Only Endpoints

| Method | Endpoint                            | Description                             |
| ------ | ----------------------------------- | --------------------------------------- |
| GET    | `/v1/bonds/{cusip}/pricing/history` | Historical bond pricing (up to 2 years) |
| GET    | `/v1/export`                        | Bulk data export (up to 50,000 records) |
| GET    | `/v1/usage/analytics`               | Detailed usage analytics                |

## Response Format

### Success

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "request_id": "req_abc123"
  }
}
```

### Error

```json theme={null}
{
  "error": {
    "code": "INVALID_TICKER",
    "message": "Company ticker 'XYZ' not found",
    "details": {
      "suggestion": "Did you mean 'XOM'?"
    }
  }
}
```

## Common Parameters

These parameters are available on most list endpoints:

| Parameter | Type    | Description                                |
| --------- | ------- | ------------------------------------------ |
| `fields`  | string  | Comma-separated list of fields to return   |
| `sort`    | string  | Sort field (prefix `-` for descending)     |
| `limit`   | integer | Results per page (max 100)                 |
| `offset`  | integer | Pagination offset                          |
| `format`  | string  | Response format: `json` (default) or `csv` |

## Rate Limits

| Tier          | Limit               | Queries      |
| ------------- | ------------------- | ------------ |
| Pay-as-You-Go | 60 requests/minute  | Pay per call |
| Pro           | 100 requests/minute | Unlimited    |
| Business      | 500 requests/minute | Unlimited    |

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706140800
```

## Credit Usage (Pay-as-You-Go)

Each endpoint consumes credits based on complexity:

| Endpoint Type | Cost   | Endpoints                                                                         |
| ------------- | ------ | --------------------------------------------------------------------------------- |
| Simple        | \$0.05 | Companies, Bonds, Resolve, Financials, Collateral, Covenants, Ratings, Market/CDS |
| Complex       | \$0.10 | Company Changes                                                                   |
| Advanced      | \$0.15 | Traverse, Documents, Batch (per operation)                                        |

Pro and Business tiers have unlimited queries included.