Travessia em CADEIA: A → B → C, com o meio invisível
Para pergunta de dois ou três saltos, onde o objeto do meio existe só para ligar as pontas. Também responde SUPERLATIVO sobre relação — 'qual X tem mais Y' — porque a lista já vem ordenada por `reached_count` decrescente — objetos DISTINTOS alcançados, não caminhos: a resposta é a primeira linha. TRÊS EXEMPLOS COMPLETOS, com os parâmetros exatos: - 'qual auditor audita mais fundos que detêm papel emitido' → `steps=audits:out,holds:out,issued:in&count_at=1&total=true`. `count_at=1` porque a contagem pedida é de FUNDOS (posição 1); sem ele contaria PAPÉIS (a ponta) e daria outro número, maior e plausível. - 'qual índice tem mais empresas emissoras de debênture' → `steps=exposed_to_issuer:out,issued:out&count_at=1&total=true`. `exposed_to_issuer` salta detentor→papel→emissora de uma vez. - 'quais empresas têm debênture indexada ao IPCA' → `steps=issued:out,indexed_to:out&start_kind=company&end_id=<id do ipca>&total=true`. O alvo é o CONCEITO (`ipca`), não a série que o publica (`bcb_sgs:433`). **O ÍNDICE CONTÉM O PAPEL, NÃO A COMPANHIA** (desde 16/08/2026, quando PETR3 e PETR4 deixaram de ser a mesma coisa). Toda cadeia que sai de um índice e quer chegar na emissora paga um salto a mais: `contains:out` traz papéis e `issued:in` traz quem os emitiu, e cadeias que cabiam em três passaram a exigir quatro. O quarto NÃO existe: medido em produção, uma travessia de quatro saltos leva 86 segundos. Por isso existe **`exposed_to_issuer`**, que faz detentor→papel→emissora em UM salto. Use-a sempre que a pergunta for sobre exposição à EMPRESA. Ela NÃO tem `magnitude`, de propósito: tamanho é do papel, e agregar tamanho por emissora foi o que apagava R$ 4,54 bilhões antes da separação. Para valores, atravesse `holds` até o papel. POSIÇÕES: 0 é a partida, 1 é depois do primeiro salto, e assim por diante. `return_at` escolhe quem é LISTADO (default 0); `count_at` escolhe quem é CONTADO (default: a ponta). `end_id` prende a ponta final a um objeto; `end_kind` prende o tipo dela. O TOTAL É `meta.total` com `?total=true` — nunca conte as linhas da página, que são no máximo `limit`. A direção é obrigatória em cada passo: `holds:out` é 'este detém aquele' e `holds:in` é o inverso. O recorte temporal é POR PASSO, cada verbo pela sua forma; passar `at` força a mesma data em todos, o que só serve para pergunta datada.
In: header
Query Parameters
1001 <= value <= 1000true = inclui meta.total (contagem do universo filtrado). Custa uma consulta a mais.
Cadeia verbo:direção separada por vírgula, 1 a 3 passos. Ex.: contains:out,issued:out
O que a coisa É. Papel (emissor, cedente, administrador) NÃO é kind — é aresta. equity_security é a ação (PETR4), distinta da companhia que a emitiu.
offering é a oferta pública, e é o único que não é uma COISA: é uma RELAÇÃO que virou objeto. Ela liga emissor, instrumento e tempo, e carrega atributos próprios (volume, rito, status, quantidade, preço) que não cabem numa aresta. Atravesse issued na direção in para chegar ao emissor.
market_event é o segundo do mesmo feitio: um ACONTECIMENTO que virou objeto. Ele existe porque aresta liga dois objetos, e sem nó do lado do evento não havia como compor — getObjectEvents responde 'o que aconteceu com este objeto' e nunca 'quais empresas foram citadas nos mesmos eventos que esta'. Atravesse mentions na direção in para ir do objeto aos eventos que falam dele, e out para ir do evento aos objetos citados. Só o evento com objeto carimbado vira nó: os demais seguem legíveis por getObjectEvents e não viram ilha no censo.
fund_share_class é a SUBCLASSE de fundo da RCVM 175 — o que o investidor efetivamente subscreve, distinto da classe que tem o CNPJ. Mesma separação de equity_security × company: o que se compra não é o veículo. Atravesse contains na direção in para chegar à classe. Ela nasce sem medidas: os atributos (situação, público-alvo) ainda não são servidos, e ausência aqui é isso, não 'a subclasse não tem'.
indicator × data_series, a regra, porque a pergunta se repete. indicator é o CONCEITO — existe fora do DataBolsa, tem nome próprio no mercado e é o que um contrato cita: IPCA, Selic, CDI, TR, IGP-M, INPC, dólar PTAX. data_series é uma PUBLICAÇÃO numerada: uma fonte, uma unidade, uma transformação, um calendário — bcb_sgs:433 é a variação mensal do IPCA e bcb_sgs:13522 é o acumulado em 12 meses do MESMO conceito. O conceito tem uma série headline e quantas variantes a fonte publicar; a série nunca tem conceito além do que ela mede.
Daí a consequência que surpreende: o que o DataBolsa CALCULA é data_series, não indicator, mesmo quando tem nome de conceito. juro_real_ex_ante, earnings_yield_agregado e os escores de regime são receitas nossas — a linhagem sai em lineage — e não coisas que uma escritura possa citar. São 7 conceitos e centenas de séries, e isso é o desenho, não cobertura faltando. Resolva pelo NOME e leia o kind que voltar, em vez de filtrar por kind=indicator esperando encontrar tudo.
"company" | "equity_security" | "fund" | "service_provider" | "instrument" | "index" | "crypto_asset" | "commodity" | "country" | "indicator" | "data_series" | "offering" | "fund_share_class" | "market_event"Recorte DENTRO do tipo na partida: fidc em vez de fund.
Prende a ponta final a um objeto específico.
O que a coisa É. Papel (emissor, cedente, administrador) NÃO é kind — é aresta. equity_security é a ação (PETR4), distinta da companhia que a emitiu.
offering é a oferta pública, e é o único que não é uma COISA: é uma RELAÇÃO que virou objeto. Ela liga emissor, instrumento e tempo, e carrega atributos próprios (volume, rito, status, quantidade, preço) que não cabem numa aresta. Atravesse issued na direção in para chegar ao emissor.
market_event é o segundo do mesmo feitio: um ACONTECIMENTO que virou objeto. Ele existe porque aresta liga dois objetos, e sem nó do lado do evento não havia como compor — getObjectEvents responde 'o que aconteceu com este objeto' e nunca 'quais empresas foram citadas nos mesmos eventos que esta'. Atravesse mentions na direção in para ir do objeto aos eventos que falam dele, e out para ir do evento aos objetos citados. Só o evento com objeto carimbado vira nó: os demais seguem legíveis por getObjectEvents e não viram ilha no censo.
fund_share_class é a SUBCLASSE de fundo da RCVM 175 — o que o investidor efetivamente subscreve, distinto da classe que tem o CNPJ. Mesma separação de equity_security × company: o que se compra não é o veículo. Atravesse contains na direção in para chegar à classe. Ela nasce sem medidas: os atributos (situação, público-alvo) ainda não são servidos, e ausência aqui é isso, não 'a subclasse não tem'.
indicator × data_series, a regra, porque a pergunta se repete. indicator é o CONCEITO — existe fora do DataBolsa, tem nome próprio no mercado e é o que um contrato cita: IPCA, Selic, CDI, TR, IGP-M, INPC, dólar PTAX. data_series é uma PUBLICAÇÃO numerada: uma fonte, uma unidade, uma transformação, um calendário — bcb_sgs:433 é a variação mensal do IPCA e bcb_sgs:13522 é o acumulado em 12 meses do MESMO conceito. O conceito tem uma série headline e quantas variantes a fonte publicar; a série nunca tem conceito além do que ela mede.
Daí a consequência que surpreende: o que o DataBolsa CALCULA é data_series, não indicator, mesmo quando tem nome de conceito. juro_real_ex_ante, earnings_yield_agregado e os escores de regime são receitas nossas — a linhagem sai em lineage — e não coisas que uma escritura possa citar. São 7 conceitos e centenas de séries, e isso é o desenho, não cobertura faltando. Resolva pelo NOME e leia o kind que voltar, em vez de filtrar por kind=indicator esperando encontrar tudo.
"company" | "equity_security" | "fund" | "service_provider" | "instrument" | "index" | "crypto_asset" | "commodity" | "country" | "indicator" | "data_series" | "offering" | "fund_share_class" | "market_event"O mesmo recorte na ponta: debenture em vez de instrument.
0 <= value <= 3Posição LISTADA. 0 = a partida (default); use o meio quando a pergunta for sobre ele.
0 <= value <= 3Corte temporal (AAAA-MM-DD), aplicado a TODOS os saltos. Default DIFERENTE de listObjectLinks: SEM at, cada salto de forma snapshot atravessa o retrato VIGENTE do PRÓPRIO SUJEITO da aresta — fundo cuja última CDA está uma competência atrás continua no caminho, com o retrato dele (o recuo pela competência GLOBAL do verbo o apagava em silêncio: medido em 23/08/2026, uma cadeia com 66 emissores respondia vazio). static atravessa o vigente; event conta tudo que aconteceu. Para 'quem JÁ se relacionou' use listObjectLinks ou findObjectPaths sem at. COM at, vale a mesma regra por sujeito na data pedida.
^\d{4}-\d{2}-\d{2}$Response Body
curl -X GET "https://api.databolsa.com/v1/objects/path?cursor=string&limit=100&total=string&steps=string&start_id=string&start_kind=company&start_subkind=string&end_id=string&end_kind=company&end_subkind=string&count_at=3&return_at=3&at=string"{
"data": [
{
"id": "string",
"kind": "string",
"name": "string",
"reached_count": 0,
"count": 0
}
],
"meta": {
"next_cursor": "string",
"count": 0,
"total": 0,
"subject": {
"property1": "string",
"property2": "string"
},
"as_of": "string",
"as_of_by_rel": {
"property1": "string",
"property2": "string"
},
"excluded_shapes": [
"event"
]
}
}{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string"
}De um texto para o objeto — ticker, CNPJ, ISIN, código ou nome
Devolve CANDIDATOS, no plural e de propósito: 'Itaú' e 'BTG' são várias pessoas jurídicas distintas, e escolher uma em silêncio é o erro que o grafo existe para impedir. `confidence: low` marca chave ambígua (código reaproveitado após encerramento). **`match_kind` diz COMO casou**, e é por ele que se decide o quanto confiar. `exact_key` é o único em que o candidato foi identificado — e o único em que `matched_key_type`/`matched_key_value` significam alguma coisa. Os outros três são palpite ordenado do melhor para o pior: nome idêntico, nome que começa com o termo, e o resto. Trate `fuzzy_name` como candidato a confirmar, nunca como resposta. Buscar por NOME pode trazer o objeto certo fora da primeira posição (`Petrobras` casa a controlada Petroquisa e a própria companhia), então quem busca por nome deve olhar a lista. Quando existir identificador, use-o. **A AÇÃO É OBJETO SEPARADO DA COMPANHIA desde 16/08/2026.** `PETR4` resolve para o PAPEL (`kind: equity_security`), não para a Petrobras: preço, indicador e provento são dele e são diferentes dos de PETR3. Para chegar à emissora, atravesse `issued` na direção `in`; a companhia continua publicando `tickers` e `share_classes`. Código antigo do mesmo papel continua resolvendo — `VVAR3` e `VIIA3` chegam em `BHIA3`. Do mesmo jeito, o INDICADOR é o conceito (`ipca`) e a SÉRIE é a publicação dele (`bcb_sgs:433`, `kind: data_series`), ligados por `measures` — e por `forecasts` quando a série PROJETA o conceito em vez de medi-lo, como o Focus e o breakeven da curva. Código de série é MINÚSCULO e é encontrado como está — até 16/08/2026 a busca normalizava tudo para maiúscula e as 183 séries eram inalcançáveis por chave, sem erro nenhum.
Taxonomia e cobertura de documentos
Descobre as facetas aceitas por searchDocuments: document_kind estável com contagem e seus rótulos brutos category/doc_type, entity_type, asset_family e intervalo válido de anos. Cada categoria declara `shape` — o que um SEGUNDO documento dela significa: `event` (nada substitui nada), `superseding` (o último é o vigente), `amending` (o vigente é o original mais os aditamentos) ou `periodic` (chaveado por competência). Leia isso ANTES de concluir qual documento vale: sete estatutos são um vigente e seis históricos, mas trinta e três fatos relevantes são trinta e três fatos. Para crédito privado, comece aqui quando não souber o rótulo da fonte; prefira document_kind e asset_family aos rótulos brutos. As contagens são por documento, não por trecho.