Brazil Debt and Covenant Disclosures API: Track Refinancing and Leverage Notices from CVM Filings

The problem

Fixed-income and credit teams track three stacks that English search results often merge:

1. Market data terminals — prices, spreads, and ratings. They summarize market views; they are not the issuer’s regulatory filing.
2. Periodic packages — DFP, ITR, and FRE with debt schedules, covenant tables, and liquidity discussion. Essential for headroom math, but they refresh on a calendar — not the day a company prices a new debenture tranche.
3. Event disclosures — fatos relevantes when issuers announce bond pricing, tender offers on existing debt, liability-management exercises, or other financing events that can move credit spreads before the next quarterly filing.

Scraping the CVM portal works for one ticker and breaks on a multi-name watchlist. Bulk open-data ZIPs are dataset-oriented, not ticker-first. You want GET /v1/documents with stable document.id, then GET /v1/documents/:id/file for the original PDF — scoped to debt, refinancing, and covenant-related notices.

For deep FRE-only covenant tables (mining or agribusiness), see use cases such as VALE3 debt and covenants in FRE. This guide focuses on the event API layer plus how to bridge into periodic footnotes.

Which filing type carries debt and covenant updates?

Brazilian issuers do not expose a dedicated type=DEBT in the apicvm document list. Financing events usually surface under:

Practical rule: poll FATO_RELEVANTE on credit watchlists, add COMUNICADO_AO_MERCADO when you expect liability-management news, then filter rows by name keywords (debenture, debênture, titulo, título, nota, bond, emissao, emissão, precifica, oferta, refinanc, captacao, captação, covenant, alavancagem, endividamento, divida, dívida, subordinad, credito, crédito) before downloading PDFs. After download, search PDF text for índice financeiro, net debt, covenant, or vencimento.

Issuer titles vary: miners file precifica + titulos_subordinados while banks may use captacao in a market communication. Zero rows in a given year does not prove the issuer never issued debt — see limitations below.

Concrete examples (demo corpus): VALE3 listed 2025 material facts whose name includes precifica for subordinated notes (2025-11-19) and debentures for liability-management steps (2025-11-05, 2025-10-06) — debt events, not dividend or M&A notices (demo API, queried 2026-09-22).

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List event filings — GET /v1/documents with type=FATO_RELEVANTE (optionally add COMUNICADO_AO_MERCADO)
3. Scope with year and optional dateRef; sort with field=dateRef&order=desc
4. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
5. Optional (Pro): page-level markdown — POST /v1/document-text-extractions with async callback
6. Bridge to covenants — list latest ITR or DFP for the same ticker and extract footnotes (see DFP footnotes guide)

Auth: Authorization: Bearer or X-API-Key. Try VALE3 without a key via the demo API.

Setup

export APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'

Step 1: List material facts for one ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=FATO_RELEVANTE&year=2025&perPage=50&field=dateRef&order=desc"

Response rows include stable id, dateRef, name, and nested company metadata. Use id as your cache key — not name, which can be long and encoding-sensitive.

Paginate with page= when meta.lastPage > 1. perPage maxes at 50.

Step 2: Narrow to debt-related rows

Filename tokens on the CVM IPE feed are predictable enough for a first-pass filter:

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("debenture|titulo|título|precifica|emissao|emissão|refinanc|endividamento|divida|dívida|subordinad|captacao|captação|covenant|alavancagem"; "i")) | {id, type, dateRef, name}'

On the public demo (no key), swap the host path to /v1/demo/documents with the same query parameters for VALE3-only smoke tests.

After download, search PDF text for índice financeiro, covenant, or maturity tables to validate the row. Extraction credits apply only if you use the text-extraction endpoint.

Step 3: Download a debt notice PDF

curl -H "Authorization: Bearer $APICVM_KEY" \
  -o debt-notice.pdf \
  "$APICVM_URL/v1/documents/<document-id>/file"

Download does not consume extraction credits.

Example: Python watchlist for debt filings

Poll material facts across a credit watchlist. Persist seen in your database in production.

import os, time, requests, re
from datetime import datetime

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}
WATCH = ["PETR4", "VALE3", "BBAS3", "ITUB4", "SUZB3"]
YEAR = datetime.utcnow().year
DEBT_RE = re.compile(
    r"debenture|titulo|título|precifica|emissao|emissão|refinanc|"
    r"endividamento|divida|dívida|subordinad|captacao|captação|"
    r"covenant|alavancagem|nota|bond",
    re.I,
)
seen = set()  # load from your store on startup

def list_events(ticker):
    r = requests.get(
        f"{BASE}/v1/documents",
        headers=H,
        params={
            "ticker": ticker,
            "types": "FATO_RELEVANTE,COMUNICADO_AO_MERCADO",
            "year": YEAR,
            "perPage": 50,
            "field": "dateRef",
            "order": "desc",
        },
    )
    if r.status_code == 429:
        time.sleep(5)
        return list_events(ticker)
    r.raise_for_status()
    return r.json()["data"]

for ticker in WATCH:
    for doc in list_events(ticker):
        if doc["id"] in seen:
            continue
        if not DEBT_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"DEBT {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions or extend the diff pattern from Brazil material facts monitoring API. For NLP over downloaded PDFs, see extract text from CVM PDFs for AI agents.

Where debt notices sit in the filings stack

Brazil regulatory filings API explains the full layer map. Pair event polling with quarterly ITR monitoring for interim covenant math. For operational projection updates on the same event layer, see Brazil guidance outlook disclosures API. For legal contingencies that affect recovery, cross-check Brazil litigation disclosures API.

Current limitations

• Documents, not loan tapes — apicvm does not store facility agreements, lender names, or automated covenant breach scores.
• Keyword filters are heuristic — name tokens help; false negatives are possible if issuers use unusual titles.
• Polling, not push — no webhook when CVM publishes a new fact. Schedule polls and diff document.id.
• Ingestion lag — sync is not real-time. A notice may appear on the portal before it is in the corpus.
• Corpus coverage — not every issuer or period is present. Validate against the portal for production compliance use cases.
• Demo scope — /v1/demo/* is limited to VALE3. Other tickers need a production key.

Next steps

• Read the API docs
• Get an API key
• Extract CVM financial footnotes from DFP — periodic covenant tables

Related guides

• Brazil guidance outlook disclosures API — projection updates on the event layer
• Brazil material facts monitoring API — generic fato relevante poll loop
• Brazil follow-on offering disclosures API — equity capital increases
• Extract text from CVM PDFs for AI agents — async markdown extraction