Analyze Brazil CVM Filings in Jupyter

Need Jupyter CVM filings cells for research prototypes? apicvm is a Bearer-auth JSON API. Put APICVM_URL and APICVM_KEY in your notebook environment, then resolve → list → download (or queue extract) cell by cell.

The problem

Notebooks are great for exploratory Brazil equity research, but:

Portal downloads break reproducibility across machines
Hard-coded local PDF paths do not travel with the .ipynb
Agents and humans both need document UUIDs in the cell output

apicvm keeps each step as an HTTP call you can re-run.

Setup cell

import os, requests

BASE = os.environ["APICVM_URL"]  # https://apicvm.dev
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}

Get a key at /signup. Prefer env vars or a secrets manager over pasting keys into committed notebooks.

Resolve + list cells

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

docs = requests.get(
    f"{BASE}/v1/documents",
    headers=H,
    params={"ticker": "VALE3", "type": "FRE", "year": 2024, "name": "Risco", "perPage": 20},
).json()

for d in docs["data"]:
    print(d["id"], d["name"])

perPage max is 50. Paginate with page. For DataFrame-heavy transforms, see pandas; for columnar analytics after export, see DuckDB.

Download cell

doc_id = docs["data"][0]["id"]
pdf = requests.get(f"{BASE}/v1/documents/{doc_id}/file", headers=H)
open(f"{doc_id}.pdf", "wb").write(pdf.content)
len(pdf.content)

File download does not consume extraction credits.

Optional: queue text extraction

On Pro, extraction is async via HTTPS callback — not a sync notebook return value:

# Requires a public HTTPS callback URL your notebook stack can receive
# Student keys receive 403 FORBIDDEN
job = requests.post(
    f"{BASE}/v1/document-text-extractions",
    headers={**H, "Content-Type": "application/json"},
    json={"document_id": doc_id, "callback_url": "https://example.com/hooks/apicvm"},
).json()
job

Details: Async PDF extraction.

curl cross-check

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=DFP&year=2024&perPage=5"

Current limitations

No job-status polling endpoint beyond the initial 202 response shape for extraction
Callback URL must be HTTPS in production
Corpus coverage depends on ingestion; empty data means not ingested yet
Do not commit real API keys inside .ipynb JSON

Next steps

Ready to integrate?

Get an API key and start querying Brazilian CVM filings programmatically.

Read the API docs Get API key