List Brazil Investor Presentations (Apresentações a Investidores) via API

The problem

Research and IR-monitoring workflows treat presentations as primary artifacts:

• Quarterly earnings and guidance decks
• Strategy / capital-markets day materials
• Cross-checks against material facts and DFP/ITR numbers

The portal can surface those filings. It does not give agents a stable typed filter and a per-document UUID. Bulk open-data dumps help offline ETL; they are awkward for “give me PETR4 investor presentations for 2024 over HTTP.”

What “investor presentation” means here

In the apicvm contract, presentations published as market communications are split out from generic comunicados:

This is not a literal SEC earnings-slide or 8-K exhibit clone. The analogy helps orientation; taxonomy and filing cadence are Brazilian.

IPE-style documents are single PDFs. Section prefixes (GET /v1/document-prefixes) still apply only to DFP, ITR, and FRE.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List presentations — GET /v1/documents?type=APRESENTACAO_INVESTIDORES
3. Download the PDF — GET /v1/documents/:id/file
4. Optional (Pro): enqueue page-level markdown — POST /v1/document-text-extractions

Auth: Authorization: Bearer or X-API-Key.

Setup

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

Prefer the demo API only for VALE3 evaluation — demo download/markdown scope is FRE risk factors, not IPE types. For investor presentations, use a real key.

Step 1: Resolve the company

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/companies/resolve?query=PETR4&by=ticker"

Confirm cnpj and tickers[]. Ambiguous name queries return 409 AMBIGUOUS_RESULT with candidates — tighten with by=ticker or by=cnpj.

Step 2: List apresentações a investidores

Filter by ticker, type, and year. perPage max is 50.

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=APRESENTACAO_INVESTIDORES&year=2024&perPage=20&field=dateRef&order=desc"

Each data[] item includes id (UUID), type, year, name, dateRef, and nested company. Store the UUID before downloading — display names are often long Portuguese titles from the feed.

Event + deck watchlist

Use types (comma-separated) when the agent should see material facts and presentations together:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&types=APRESENTACAO_INVESTIDORES,FATO_RELEVANTE&year=2024&perPage=50"

For pagination (page, field, order), see Paginate and filter CVM documents.

Step 3: Download the PDF

curl -OJ -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/<document-id>/file"

File download does not consume extraction credits. An empty list can mean a corpus gap for that issuer/year — not that APRESENTACAO_INVESTIDORES is unsupported.

Example: Python

import os
import requests

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}

company = requests.get(
    f"{BASE}/v1/companies/resolve",
    params={"query": "PETR4", "by": "ticker"},
    headers=H,
    timeout=60,
)
company.raise_for_status()

docs = requests.get(
    f"{BASE}/v1/documents",
    params={
        "ticker": "PETR4",
        "type": "APRESENTACAO_INVESTIDORES",
        "year": 2024,
        "perPage": 20,
        "field": "dateRef",
        "order": "desc",
    },
    headers=H,
    timeout=60,
)
docs.raise_for_status()

for row in docs.json()["data"]:
    print(row["id"], row.get("dateRef"), row.get("name"))

Optional: extract text for agents (Pro)

Presentations are PDFs (often slide decks). If an agent needs searchable markdown, enqueue async extraction with an HTTPS callback — same contract as DFP/FRE. There is no synchronous “return full text now” route, and Student keys get 403 on extraction. Details: Extract text from CVM PDFs and async callbacks.

Presentations vs comunicados vs material facts

Equity research workflows often pair decks with financial statements. See Brazil equity research with CVM filings.

Current limitations

• Coverage depends on the ingestion sync — empty results can be a gap, not an API error
• Not a push/webhook feed for “new presentation arrived”; clients poll GET /v1/documents
• Do not claim real-time delivery; latency follows the sync pipeline
• /v1/document-prefixes does not catalog IPE section trees — presentations are whole PDFs
• Demo routes do not expose IPE download/markdown beyond the VALE3 FRE demo scope

Next steps

• Read the API docs — full /v1 contract and error codes
• Get an API key — list and download across supported issuers
• IPE filing type overview — taxonomy and sibling types
• List Brazil material facts via API — event disclosures in the same IPE cluster

Related guides

• IPE: Brazil Periodic Disclosures and Material Facts
• List Brazil Material Facts (Fatos Relevantes) via API
• List Brazil Assembly Minutes (Atas de Assembleia) via API
• Brazil Equity Research with CVM Filings API
• Getting started with the CVM filings API