# Narrative disclosures

The figures on a financial statement are only part of what a filer tags. The
rest is narrative: accounting policies, commitments, segment tables, the notes
that explain how a number was arrived at. Arche extracts these as individual
disclosures, each tied to the filing it came from.

## What a disclosure is

One XBRL text block from one filing. The `concept` names which block it is,
using the filer's own taxonomy, and `char_count` says how large the text is
without making you fetch it.

## List a company

```bash
curl -X GET "https://api.arche.fi/v1/edgar/companies/0000789019/disclosures?page_size=50" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

Representative response:

```json
{
  "page": 1,
  "page_size": 50,
  "total": 3457,
  "items": [
    {
      "disclosure_id": "e5107ac3-978a-4630-84d9-1f7e569f9722",
      "accession_id": "0001193125-26-027207",
      "cik": "0000789019",
      "period_of_report": "2025-12-31",
      "concept": "src:ContractWithCustomerLiabilityBySegmentTableTextBlock",
      "title": "Contract With Customer Liability By Segment Table",
      "char_count": 235
    }
  ]
}
```

Narrow with `period_of_report` for one reporting period, or `accession_id` for
one filing.

## Read one disclosure

```bash
curl -X GET "https://api.arche.fi/v1/edgar/disclosures/e5107ac3-978a-4630-84d9-1f7e569f9722" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

The detail response adds two fields to the listing shape:

- `disclosure_text` (string): The narrative text itself. Note the field name — it is
  `disclosure_text`, not `text`.
- `extracted_at` (timestamp): When Arche extracted the block from the filing.

## Listings omit the text

A listing returns metadata only. This is deliberate: one filing can carry
hundreds of kilobytes across its text blocks, and a page of 50 disclosures with
full text would be a very large response for a browsing request.

`char_count` is there so you can decide what is worth fetching before you fetch
it. Filter on it to skip the boilerplate and pull the substantial notes.

> **Warning:** Fetch disclosure text one record at a time, and let
> `char_count` drive the decision. Looping the detail route across
> a whole listing is the most reliable way to exhaust a
> [read budget](https://docs.arche.fi/rate-limits) on this API.

## Finding what you want

`concept` is the filer's own tag, so it is the precise handle but not a
consistent one across companies — different filers use different taxonomies, and
a `src:` prefix means a filing-specific extension rather than a standard
`us-gaap:` concept. `title` is the human-readable rendering of the same thing.

Match on `concept` when you are working within one filer's history, and expect
to match on `title` or text when you are comparing across filers.

## Next steps

- [Company identity](https://docs.arche.fi/identity): Resolve tickers to full issuer records, search by name, and read mapping validity.
- [Time series](https://docs.arche.fi/time-series): Pull a metric across a whole reporting history, point-in-time or as-reported.
- [Metric catalog](https://docs.arche.fi/metrics): Look up canonical and derived metric names, formulas, bundles and segments.