Debt profiles treat the latest processed 10-K as the annual baseline, then apply later 10-Q and relevant 8-K updates by their actual dates to stable issuer-scoped agreements and instruments. Company totals are authoritative issuer-reported amounts, never sums manufactured from an incomplete instrument set.

Both endpoints preserve provenance. Dates use `YYYY-MM-DD`, amounts remain numeric in their stated currency, and exact SEC filing or artifact links travel with the observations, covenants, and documents they support. No response sample is shown before a verified production debt profile exists.

## /v1/stocks/{ticker}/debt-profile

Returns the company's reported total-debt history and identified instruments in independent pages. `reportedTotalsMeta` and `instrumentsMeta` carry `limit`, `offset`, `count`, `hasMore`, and `total`. Pages are read in the database, so `total` is the counted number of matching rows. `total` is omitted when a defensive read boundary meant the rows could only be bounded rather than counted; `hasMore` is still authoritative, so page by `hasMore` and never treat a missing `total` as zero. Each profile instrument contains three-row previews of history, covenants, and documents; use the instrument-detail endpoint for independently paged complete collections. `coverage.filingStartDate` is the earliest eligible filing with a current-version terminal extraction result. `coverage.examinedThrough` is the latest safe completed date that does not cross an eligible filing without a current-version terminal result; it is `null` when the first processed date itself is incomplete or a failed filing cannot be dated. `coverage.latestProcessedFilingDate` separately reports the newest terminal result, which can be later than `examinedThrough` when an untouched or failed filing interrupts the window. `coverage.annualBaselineAsOf` is the debt as-of date from the latest approved 10-K baseline.

`coverage.unprocessedFilingCount` and `coverage.unprocessedCovenantArtifactCount` report the complete eligible current-version backlog, including untouched sources and retry failures. `coverage.pendingFilingFailureCount` and `coverage.pendingCovenantFailureCount` report current-version sources awaiting retry. `coverage.parkedFilingFailureCount` and `coverage.parkedCovenantFailureCount` report sources still unresolved after the bounded retry ladder. `coverage.unresolvedObservationCount` reports approved observations excluded because they could not be matched exactly to a stable instrument. `coverage.incompleteEvidenceFilingCount` and `coverage.incompleteLegalArtifactCount` disclose terminal filing results whose SEC artifact inventory or legal exhibits could not be read safely; their figures may still be available, but covenant coverage is incomplete.

`coverage.readLimitReached` is normally `false`. When `true`, a defensive provider boundary was reached and the returned counts and history are explicitly incomplete; clients must not treat the response as full coverage.

Each `reportedTotals` row carries the issuer's label, currency, amount, as-of date, form, filed date, exact `filingUrl`, and `reconciliationStatus`: `Reconciled`, `Difference`, `Incomplete`, or `NotAvailable`. The amount remains authoritative even when reconciliation is incomplete or differs; clients must not replace it with a sum of `instruments`.

Each instrument has a stable `id`, type, status, legal issuer, agreement and series identity, current balance fields and their `balanceAsOf`, aliases, filing `history`, current `covenants`, and linked `documents`. History rows retain the parent `filingUrl` and return the exact evidence artifact as `sourceUrl`, falling back to the filing only when no separate artifact exists. They also include the exact `sourceQuote`, `legalIssuerQuote`, and `contextQuotes`; document `sourceUrl` points to the exact SEC artifact when available.

`covenants` contains only verified terms operative today. An amendment closes the exact prior agreement-and-instrument provision it expressly supersedes; ambiguous or overlapping active versions are withheld. Each covenant returns its exact `provisionReference`, source-backed `categoryText`, `summary`, metric/operator/threshold/unit, testing frequency, springing trigger, exceptions, effective interval, required `definedTerms`, supersession reference, `sourceQuote`, and `sourceUrl`. `isSpringing` is `true` only when the source states and quotes a trigger; otherwise it is `null`, not an inferred `false`.

**Parameters:** `{ticker}` (path); `instrumentLimit` (default 25, max 100), `instrumentOffset`, `reportedTotalLimit` (default 25, max 100), and `reportedTotalOffset`. Offsets are zero-based and must be non-negative; unknown query names return `400` with `invalid_parameter`.

```bash
curl "https://api.equibles.com/v1/stocks/NVDA/debt-profile" \
  -H "Authorization: Bearer eq_your_api_key"
```

```python
import requests
r = requests.get(
    "https://api.equibles.com/v1/stocks/NVDA/debt-profile",
    headers={"Authorization": "Bearer eq_your_api_key"},
)
print(r.json())
```

```javascript
const res = await fetch("https://api.equibles.com/v1/stocks/NVDA/debt-profile", {
  headers: { Authorization: "Bearer eq_your_api_key" },
});
console.log(await res.json());
```

## /v1/stocks/{ticker}/debt-instruments/{instrumentId}

Returns one instrument by the stable UUID supplied in the profile's `instruments[].id`. The envelope contains `ticker`, `companyName`, `coverage`, and `data`. `coverage` is the same profile-level coverage and unresolved-failure block returned by the company profile, so instrument detail never hides filing or covenant gaps. `data.historyMeta`, `data.covenantsMeta`, and `data.documentsMeta` describe the independent pages; advance the matching offset until `hasMore` is false. Each page is read in the database, so an offset beyond the profile preview still returns rows, and `total` follows the same omitted-when-bounded rule as the profile. An ID that does not belong to the ticker returns `404`.

**Parameters:** `{ticker}` and `{instrumentId}` (path); `historyLimit`, `historyOffset`, `covenantLimit`, `covenantOffset`, `documentLimit`, and `documentOffset`. Limits default to 25 and clamp at 100; offsets are zero-based and must be non-negative.

```bash
profile=$(curl -sS "https://api.equibles.com/v1/stocks/NVDA/debt-profile" \
  -H "Authorization: Bearer eq_your_api_key")
instrument_id=$(jq -r '.instruments[0].id' <<<"$profile")
curl "https://api.equibles.com/v1/stocks/NVDA/debt-instruments/${instrument_id}" \
  -H "Authorization: Bearer eq_your_api_key"
```

```python
import requests
headers = {"Authorization": "Bearer eq_your_api_key"}
profile = requests.get(
    "https://api.equibles.com/v1/stocks/NVDA/debt-profile", headers=headers
).json()
instrument_id = profile["instruments"][0]["id"]
r = requests.get(
    f"https://api.equibles.com/v1/stocks/NVDA/debt-instruments/{instrument_id}",
    headers=headers,
)
print(r.json())
```

```javascript
const headers = { Authorization: "Bearer eq_your_api_key" };
const profile = await fetch(
  "https://api.equibles.com/v1/stocks/NVDA/debt-profile",
  { headers },
).then((r) => r.json());
const instrumentId = profile.instruments[0].id;
const res = await fetch(
  `https://api.equibles.com/v1/stocks/NVDA/debt-instruments/${instrumentId}`,
  { headers },
);
console.log(await res.json());
```