> ## 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.

# Quickstart

> Get started with the DebtStack API in 5 minutes

## Prerequisites

You'll need:

* A DebtStack account ([sign up free](https://debtstack.ai))
* Your API key from the [dashboard](https://debtstack.ai/dashboard)

## Make Your First Request

### Using curl

```bash theme={null}
# Set your API key
export DEBTSTACK_API_KEY="ds_your_api_key_here"

# Search companies with field selection
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/companies?ticker=AAPL,MSFT,GOOGL&fields=ticker,name,net_leverage_ratio"
```

### Using Python

```python theme={null}
import requests

API_KEY = "ds_xxxxx"
BASE_URL = "https://api.debtstack.ai/v1"

response = requests.get(
    f"{BASE_URL}/companies",
    params={
        "ticker": "AAPL",
        "fields": "ticker,name,total_debt,net_leverage_ratio"
    },
    headers={"X-API-Key": API_KEY}
)

data = response.json()
print(data)
```

### Using JavaScript

```javascript theme={null}
const API_KEY = "ds_xxxxx";
const BASE_URL = "https://api.debtstack.ai/v1";

const params = new URLSearchParams({
  ticker: "AAPL",
  fields: "ticker,name,total_debt,net_leverage_ratio"
});

const response = await fetch(`${BASE_URL}/companies?${params}`, {
  headers: { "X-API-Key": API_KEY }
});

const data = await response.json();
console.log(data);
```

### Response

```json theme={null}
{
  "data": [
    {
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "total_debt": 10650000000000,
      "net_leverage_ratio": 0.8
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

<Note>
  All monetary amounts are in **cents** to avoid floating-point issues.
  \$106.5 billion = 10,650,000,000,000 cents.
</Note>

## Common Queries

### Find High-Yield Bonds

```bash theme={null}
# Find high-yield senior unsecured bonds with pricing data
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/bonds?seniority=senior_unsecured&min_ytm=8.0&has_pricing=true"
```

```python theme={null}
# Bonds yielding more than 8%
response = requests.get(
    f"{BASE_URL}/bonds",
    params={
        "min_ytm": 8.0,
        "has_pricing": True,
        "seniority": "senior_unsecured",
        "fields": "name,cusip,company_ticker,coupon_rate,pricing",
        "sort": "-pricing.ytm"
    },
    headers={"X-API-Key": API_KEY}
)
```

### Resolve Bond Identifiers

```bash theme={null}
# Map trader shorthand to CUSIP
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/bonds/resolve?q=RIG%208%25%202027"

# Lookup by CUSIP
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/bonds/resolve?cusip=89157VAG8"
```

### Get Financials (TTM)

```bash theme={null}
# Get trailing twelve months financials for AAPL
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/financials?ticker=AAPL&period=TTM"

# Get all Q3 2025 financials for comparison
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/financials?fiscal_year=2025&fiscal_quarter=3&format=csv"
```

### Find Collateral

```bash theme={null}
# Find all first-lien collateral for RIG
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/collateral?ticker=RIG&priority=first_lien"

# Get collateral with valuations
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/collateral?has_valuation=true&collateral_type=equipment"
```

### Search SEC Documents

```bash theme={null}
# Find covenant language in credit agreements
curl -H "X-API-Key: $DEBTSTACK_API_KEY" \
  "https://api.debtstack.ai/v1/documents/search?q=event+of+default&ticker=RIG&section_type=indenture"
```

```python theme={null}
# Find covenant language in credit agreements
response = requests.get(
    f"{BASE_URL}/documents/search",
    params={
        "q": "restricted payment dividend",
        "section_type": "indenture",
        "ticker": "RIG"
    },
    headers={"X-API-Key": API_KEY}
)
```

### Get Bond Guarantors

```bash theme={null}
curl -X POST "https://api.debtstack.ai/v1/entities/traverse" \
  -H "X-API-Key: $DEBTSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":{"type":"bond","id":"893830AK8"},"relationships":["guarantees"]}'
```

```python theme={null}
# Who guarantees this bond?
response = requests.post(
    f"{BASE_URL}/entities/traverse",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "start": {"type": "bond", "id": "893830AK8"},
        "relationships": ["guarantees"],
        "direction": "inbound"
    }
)
```

## Response Format

All API responses follow this structure:

```json theme={null}
{
  "data": [...],  // The requested data
  "meta": {
    "total": 100,     // Total matching records
    "limit": 50,      // Page size
    "offset": 0,      // Current offset
    "request_id": "req_abc123"
  }
}
```

## Error Handling

Errors return a consistent format:

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

| HTTP Status | Error Code          | Description                |
| ----------- | ------------------- | -------------------------- |
| 400         | `INVALID_PARAMETER` | Invalid query parameter    |
| 401         | `UNAUTHORIZED`      | Invalid or missing API key |
| 404         | `INVALID_TICKER`    | Company not found          |
| 429         | `RATE_LIMITED`      | Too many requests          |
| 500         | `INTERNAL_ERROR`    | Server error               |

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API keys and rate limits
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Explore all available endpoints
  </Card>

  <Card title="AI Agent Guide" icon="robot" href="/guides/ai-agents">
    Build AI agents with DebtStack
  </Card>

  <Card title="Data Model" icon="sitemap" href="/concepts/data-model">
    Understand the data structure
  </Card>
</CardGroup>