Complete apicvm API documentation

Overview

All business routes use the prefix /v1. The base URL in production is https://apicvm.dev. Authenticate with an API key on every business route except GET /v1/health-check and the public demo routes under /v1/demo/*.

Authentication

Send your API key on every business route. Prefer Bearer auth. Sign up at /signup to get a free 3-day API key after email verification, or upgrade to Student ($3/month) or Pro ($9/month).

Authorization: Bearer apicvm_...
# or
X-API-Key: apicvm_...

Errors

All errors follow a consistent envelope:

{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "Documento não encontrado",
    "details": {}
  }
}

Ambiguous company resolve returns 409 with a candidates array instead of picking a match silently.

Pagination and sorting

List endpoints accept these shared query parameters:

Paginated responses use Lucid-style meta + data:

{
  "meta": {
    "total": 120,
    "perPage": 10,
    "currentPage": 1,
    "lastPage": 12,
    "firstPage": 1,
    "firstPageUrl": "...",
    "lastPageUrl": "...",
    "nextPageUrl": "...",
    "previousPageUrl": null
  },
  "data": [ ... ]
}

Default sort for companies: name asc. Default sort for documents: year desc, then dateRef desc, then name asc.

Rate limits

When authentication and rate limiting are enabled, limits apply per API key. Free and paid plans include a global limit of 60 requests per 60-second window.

Markdown extraction (POST /v1/document-text-extractions) is available on Pro and Scale only. Free and Student plan requests receive 403 FORBIDDEN. Usage is billed in page credits (1 credit = 1 page).

Extraction credits

Pro includes 1000 credits/month that do not roll over. Prepaid packs: 1000 ($10) / 5000 ($50) / 10000 ($100) — packs do not expire. The POST returns 202 immediately; the prepare job counts pages (N) and checks balance. If balance < N, your callback receives status: "error" with error_code: EXTRACTION_CREDITS_EXCEEDED, balance, and required — nothing is debited and pages are not processed. Cache hits also consume N credits.

Health check

Public endpoint. No authentication required.

Response 200

{ "status": "ok" }

Public demo (VALE3)

Try Vale (VALE3) without an API key. The landing page includes a live runner, or call these routes directly. You can download the Vale FRE 2025 risk factors demo file (DescricaoFatoresRisco) or fetch its cached page markdown. Async extraction of other filings requires a paid plan.

Scope: CNPJ 33592510000154 only. File download and cached markdown are limited to FRE 2025 section DescricaoFatoresRisco. Rate limit by IP (30 req/min, 200 req/day). perPage on document list is capped at 20.

GET /v1/demo/companies/resolve?query=VALE3&by=ticker
GET /v1/demo/documents?ticker=VALE3&type=FRE&year=2025&name=DescricaoFatoresRisco&perPage=5
GET /v1/demo/documents/{id}/file
GET /v1/demo/documents/{id}/markdown
GET /v1/demo/document-prefixes?type=FRE

List companies

Returns a paginated list of Brazilian public companies with tickers.

Query parameters

Response fields (data[])

Example

GET /v1/companies?search=Petrobras&perPage=5

{
  "meta": { "total": 1, "perPage": 5, "currentPage": 1, "lastPage": 1 },
  "data": [
    {
      "id": 42,
      "name": "Petróleo Brasileiro S.A. - Petrobras",
      "cnpj": "33000167000101",
      "sector": "Petróleo, Gás e Biocombustíveis",
      "tickers": [
        { "id": 1, "idCompany": 42, "ticker": "PETR4", "tickerClass": "ON" }
      ]
    }
  ]
}

Resolve company

Find a single company by ticker, CNPJ, or name. Returns one match or an ambiguity error with candidates.

Query parameters

Resolution order (by=auto)

1. Exact ticker match (case-insensitive).
2. CNPJ match (formatted or digits-only).
3. Exact name match (case-insensitive).
4. Partial name match.

Response fields

Same shape as a single company object from the list endpoint.

Example — success

GET /v1/companies/resolve?query=PETR4&by=ticker

{
  "id": 42,
  "name": "Petróleo Brasileiro S.A. - Petrobras",
  "cnpj": "33000167000101",
  "sector": "Petróleo, Gás e Biocombustíveis",
  "tickers": [
    { "id": 1, "idCompany": 42, "ticker": "PETR4", "tickerClass": "ON" }
  ]
}

Example — ambiguous (409)

{
  "error": {
    "code": "AMBIGUOUS_RESULT",
    "message": "Mais de uma empresa corresponde à busca",
    "details": {
      "candidates": [
        { "id": 10, "name": "...", "cnpj": "...", "sector": null, "tickers": ["ABC3"] },
        { "id": 11, "name": "...", "cnpj": "...", "sector": null, "tickers": ["ABC4"] }
      ]
    }
  }
}

List documents

Returns a paginated list of CVM filings. Filter by company, ticker, type, year, and more. Each item includes nested company with tickers.

Query parameters

Response fields (data[])

Example

GET /v1/documents?ticker=PETR4&type=DFP&year=2024&perPage=20

GET /v1/documents?ticker=VALE3&type=FATO_RELEVANTE&year=2025&perPage=20

Document types

GET /v1/documents accepts all document types below. IPE documents are single PDFs from RAD: the document name comes from the filing subject/protocol, and dateRef is the delivery date.

Get document

Returns metadata for a single document, including nested company and tickers.

Path parameters

Example

GET /v1/documents/550e8400-e29b-41d4-a716-446655440000

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "DFP",
  "dateRef": "2024-12-31",
  "idCompany": 42,
  "year": 2024,
  "name": "DFP 2024",
  "hash": null,
  "company": {
    "id": 42,
    "name": "Petróleo Brasileiro S.A. - Petrobras",
    "cnpj": "33000167000101",
    "sector": "Petróleo, Gás e Biocombustíveis",
    "tickers": [
      { "id": 1, "idCompany": 42, "ticker": "PETR4", "tickerClass": "ON" }
    ]
  }
}

Document prefixes

Returns the catalog of distinct section-level name prefixes for DFP, ITR, and FRE. Use this when you need to discover which FRE/DFP/ITR sections exist before filtering GET /v1/documents with the name parameter.

Prefixes are derived from document names: the segment before the first -, with digits and underscores removed. For example, DescricaoFatoresRisco-4_1 becomes DescricaoFatoresRisco.

IPE document types such as FATO_RELEVANTE are single PDFs and do not have prefixes.

Query parameters

Response

{
  "data": [
    "DescricaoControlesInternos",
    "DescricaoFatoresRisco",
    "DescricaoGerenciamentoRiscos",
    "DescricaoRiscosMercado",
    "PoliticaPraticaRemuneracao"
  ]
}

Example

GET /v1/document-prefixes?type=FRE

Then filter documents with a prefix:

GET /v1/documents?ticker=PETR4&type=FRE&year=2024&name=DescricaoFatoresRisco

Download file

Streams the original CVM filing file from storage. Useful when you need the source PDF, not just metadata or extracted text.

Response headers

Example

curl -OJ -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/550e8400-e29b-41d4-a716-446655440000/file"

Text extraction

Accepts the request with 202 immediately. Page count, credit gate, and debit run in a prepare job; pages are then delivered to your callback_url as markdown. There is no job status endpoint — progress arrives only via callbacks. Pro plan only. Debits N page credits in prepare (cache hits included). Insufficient balance is reported via callback error_code: EXTRACTION_CREDITS_EXCEEDED. Free and Student plans receive 403 FORBIDDEN.

Request body

Example request

POST /v1/document-text-extractions
Content-Type: application/json

{
  "callback_url": "https://you.example.com/callbacks/apicvm",
  "document": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Response 202

{
  "id": "job-uuid",
  "status": "queued",
  "document_id": "550e8400-e29b-41d4-a716-446655440000"
}

If the document was already fully extracted and cached, the worker reuses existing page text and sends callbacks from cache.

Examples

Recommended agent flow: resolve company → list section prefixes (optional) → list documents → pick an explicit id → download file or enqueue extraction.

cURL

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

# List FRE section prefixes
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/document-prefixes?type=FRE"

# List FRE risk-factor sections for 2024
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=FRE&year=2024&name=DescricaoFatoresRisco"

# List material facts
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=FATO_RELEVANTE&year=2025"

# Download original file
curl -OJ -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents/$DOCUMENT_ID/file"

# Queue text extraction
curl -X POST -H "Authorization: Bearer $APICVM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"https://you.example.com/cb","document":{"id":"'"$DOCUMENT_ID"'"}}' \
  "$APICVM_URL/v1/document-text-extractions"

Python

import os
import requests

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

# Resolve company
company = requests.get(
    f"{BASE_URL}/v1/companies/resolve",
    params={"query": "PETR4", "by": "ticker"},
    headers=HEADERS,
).json()

# Discover FRE section prefixes, then filter risk-factor documents
prefixes = requests.get(
    f"{BASE_URL}/v1/document-prefixes",
    params={"type": "FRE"},
    headers=HEADERS,
).json()
print(prefixes["data"][:5])

documents = requests.get(
    f"{BASE_URL}/v1/documents",
    params={
        "ticker": "PETR4",
        "type": "FRE",
        "year": 2024,
        "name": "DescricaoFatoresRisco",
    },
    headers=HEADERS,
).json()

document_id = documents["data"][0]["id"]

# Download original PDF
pdf = requests.get(
    f"{BASE_URL}/v1/documents/{document_id}/file",
    headers=HEADERS,
)
pdf.raise_for_status()

# Queue text extraction
job = requests.post(
    f"{BASE_URL}/v1/document-text-extractions",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "callback_url": "https://you.example.com/callbacks/apicvm",
        "document": {"id": document_id},
    },
)
job.raise_for_status()
print(job.json())  # {"id": "...", "status": "queued", "document_id": "..."}

TypeScript

const baseUrl = process.env.APICVM_URL!
const apiKey = process.env.APICVM_KEY!

async function apicvmGet(path: string) {
  const response = await fetch(`${baseUrl}${path}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  })
  if (!response.ok) throw new Error(await response.text())
  return response.json()
}

const company = await apicvmGet('/v1/companies/resolve?query=PETR4&by=ticker')
const documents = await apicvmGet('/v1/documents?ticker=PETR4&type=DFP&year=2024')
const documentId = documents.data[0].id

const extraction = await fetch(`${baseUrl}/v1/document-text-extractions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    callback_url: 'https://you.example.com/callbacks/apicvm',
    document: { id: documentId },
  }),
})

Extraction callbacks

After a successful POST /v1/document-text-extractions, page workers send one callback per page (possibly out of order). When all pages finish, the parent job sends status: "completed". Callbacks have retry logic (up to 3 attempts). Your endpoint should be idempotent.

Page callback (success)

{
  "status": "success",
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "job-uuid",
  "page": {
    "number": 1,
    "markdown": "# Demonstrações Financeiras\n\n..."
  },
  "total_pages": 120
}

Document completed

{
  "status": "completed",
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "job-uuid",
  "total_pages": 120
}

Error callback

{
  "status": "error",
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "job-uuid",
  "error_message": "Description of the error"
}

Insufficient credits (from the prepare job):

{
  "status": "error",
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "job-uuid",
  "error_code": "EXTRACTION_CREDITS_EXCEEDED",
  "error_message": "Créditos de extração insuficientes",
  "balance": 12,
  "required": 120
}

For AI agents

Download llms.txt for a plain-text summary of this API — endpoints, filters, examples, and limitations — optimized for LLM and agent consumption without parsing HTML.