> ## Documentation Index
> Fetch the complete documentation index at: https://octo-98895abd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# For agents

> How an agent uses this site and the Data API. You cannot generate an API key.

The procedure for coding agents and the docs assistant: follow it in order. The contract itself (row caps, tier ceilings, null semantics, regime breaks) is written once on [Conventions & limits](/api-docs/conventions) and served as JSON by `POST /rpc/catalog`.

### 1. Read the published site

| What | URL |
| - | - |
| Page index | [llms.txt](https://octo-98895abd.mintlify.site/llms.txt) |
| This skill | [skill.md](https://octo-98895abd.mintlify.site/skill.md) |
| Docs MCP (search + read, no login) | `https://octo-98895abd.mintlify.site/mcp` |
| Data API | `https://zcjbtpxuhdekpwcxmepn.supabase.co/rest/v1` |
| Data MCP (read-only, no login) | `https://zcjbtpxuhdekpwcxmepn.supabase.co/functions/v1/silo-mcp` ([MCP server](/api-docs/mcp)) |
| Runnable notebooks | [`notebooks/`](https://github.com/PedroDnT/SILO-BZ/tree/main/notebooks) |

Prefer MCP search or `llms.txt` over training data. The Evidence dashboards and the repository's `docs/` notes are **not** the read contract: `docs/reference/API.md` documents the local Flask adapter, not this API.

### 2. Auth

The publishable key in [quickstart](/api-docs/quickstart) is shared, for testing. Anonymous access is free and small; signing in with GitHub raises four ceilings. There is no `createApiKey`; `service_role` / Secret is never a caller credential. Never mint or forge a key.

Sign in at [silo-bz-deloslabs.vercel.app/signin.html](https://silo-bz-deloslabs.vercel.app/signin.html) and send the token alongside the publishable key:

```bash theme={null}
curl -s -X POST "$SILO_URL/rpc/panel" \
  -H "apikey: $SILO_ANON_KEY" \
  -H "Authorization: Bearer $SILO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"p_ids":["PETR4","VALE3","ITUB4","BOVA11"],"p_metrics":["close"]}'
```

`SILO_URL` and `SILO_ANON_KEY` are set in [quickstart](/api-docs/quickstart).

Ceilings live in [Conventions & limits](/api-docs/conventions#authentication) and `catalog().limits`; never size a request from memory.

* **Rows per response never change with tier.**
* **Exceeding a ceiling is a `22023` error, never a silent trim.**
* **The token lasts about an hour and expiry is silent.** You drop to anonymous, so a four-id call starts raising `22023`. Durable per-user keys do not exist yet.
* Landing tables (`cvm_*`, `b3_cotahist`, `cia_*`, `bacen_*`) are closed to both tiers.

### 3. First live call is `coverage`

`POST $SILO_URL/rpc/coverage` with body `{}` (example in [quickstart](/api-docs/quickstart)).

| Column | Use |
| - | - |
| `as_of` | freshness |
| `complete_through` | what the default windows serve |
| `notes` | a caveat the dates cannot carry |

Column meanings: [Freshness](/api-docs/conventions#freshness). A `401` is missing or wrong headers. An empty or error body is a failed fetch: **raise**, do not invent a last date.

### 4. Discover the data for the question

Start from the research question, not a preselected endpoint.

1. Read the catalog: `POST $SILO_URL/rpc/catalog` with `apikey`, `Content-Type: application/json`, `Content-Profile: api` and body `{}`.
2. Find candidates from its endpoint and metric descriptions, then search the docs MCP for grain, identifiers, date meaning, units, limits and caveats.
3. Check `coverage` for the actual observation window.
4. Resolve fund and company ids with `lookup` or `search_funds`; join only on published keys.
5. Record why each source was selected. If the data cannot support the question or the periods do not align, say so.

The workflows below are examples of what to do **after** discovery, not a fixed dataset list.

### 5. Example: does equity stress show up in FIDC credit?

1. `lookup` (`p_query`) / `search_funds` for FIDC CNPJs. Do not invent a ticker-to-fund join.
2. `panel` with `p_ids: ["PETR4", "<cnpj>", …]`, `p_metrics: ["close_return","delinquency","nav"]`, `p_freq: "month"`.
3. Pivot locally keeping `asset_class` in the key. Correlate pairwise-complete. **No ffill.**
4. `delinquency` is BRL outstanding, not a rate: divide by `nav` (both are in the same call). For a FIDC the series starts at 2013-01 and is on every row from 2020-11 ([regime break](/api-docs/conventions#regime-breaks)).
5. `close` is unadjusted (a split reads as a jump in `quotes`; `panel`'s `close_return` adjusts the previous close across it); `quote_history`'s `close_adj`, its default field, is continuous across splits and is refused where unproven. A missing month is not a two-month return.
6. Before reading a null as a gap, call `coverage` and `metric_coverage`.

There is no server-side `corr`; the catalog lists those as `notebook_reducers`. No RPC returns a truncated result: functions page or refuse.

### 6. Example: screening a whole family

*Rank every FIDC by how much its delinquency worsened* is one paged `panel` call when signed in. Anonymous callers cannot use universe mode: enumerate from the `funds` **view** and batch ids within the ceiling.

<Steps>
  <Step title="Check the family is complete through your window">
    Require `complete_through >= ` your end month on the `funds_fidc` row. Read `as_of`, not `newest_period`.
  </Step>

  <Step title="Enumerate the family from the funds view, paging">
    ```bash theme={null}
    curl -s "$SILO_URL/funds?select=cnpj,fund_name,first_period,last_period\
    &entity_type=eq.fidc&order=cnpj.asc&limit=1000&offset=0" \
      -H "apikey: $SILO_ANON_KEY" -H "Accept-Profile: api" -H "Prefer: count=exact"
    ```

    `Content-Range` carries the total. Keep funds whose `first_period` / `last_period` span your window.
  </Step>

  <Step title="Signed in: walk the family with p_after">
    ```json theme={null}
    {"p_ids": [], "p_metrics": ["delinquency", "nav"], "p_entity_type": "fidc",
     "p_from": "2025-09-01", "p_min_nav": 10000000, "p_min_months": 12, "p_after": ""}
    ```

    Next page: `p_after` = the last row's `"<date>|<id>|<metric>|<asset_class>"`. The SDK's `panel_all(...)` does the loop.
  </Step>

  <Step title="Keep asset_class in the key">
    The grain is `(id, asset_class, date, metric)`. A CNPJ that also files as an FI comes back twice per month.
  </Step>

  <Step title="Reduce locally">
    Compute `delinquency / nav` per fund-month (guard `nav` of zero), rank on the change, require a minimum of non-null months. No ffill.
  </Step>
</Steps>

Notebook [`04_fidc_credit`](https://github.com/PedroDnT/SILO-BZ/blob/main/notebooks/04_fidc_credit.ipynb) is this walkthrough as code.

### Notes

<Warning>
  Never fabricate a price, NAV, fill, ranking, or ticker-to-CNPJ match. Null stays null. Unknown id returns no row. Known id with an empty window returns an empty series, not a guessed last close.
</Warning>

* A fund's **name** is never a taxonomy. For "FIDCs exposed to sector X" use `fidc_portfolio` (sector and SCR ladders), `fidc_cedentes` (named originators) or `fidc_sacados` (anonymized top-25 debtors): [FIDC concentration](/api-docs/fidc).
* Ingest (`run_daily`, landing tables) is out of scope for this API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.