Monitor Brazil CVM Filings with GitHub Actions

Pattern

cron (daily)
  → curl/Python list documents for tickers
  → compare IDs to a committed snapshot (or artifact)
  → open issue / fail job when new IDs appear

This is polling, not a CVM push webhook. apicvm does not emit filing-arrival events.

Secrets

Optional: APICVM_URL defaulting to https://apicvm.dev.

Workflow sketch

name: cvm-filings-watch
on:
  schedule:
    - cron: "0 12 * * 1-5"
  workflow_dispatch:

jobs:
  watch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: List PETR4 ITR current year
        env:
          APICVM_KEY: ${{ secrets.APICVM_KEY }}
          APICVM_URL: https://apicvm.dev
        run: |
          curl -fsS -H "Authorization: Bearer $APICVM_KEY" \
            "$APICVM_URL/v1/documents?ticker=PETR4&type=ITR&year=2025&perPage=50" \
            | tee /tmp/docs.json
          python - <<'PY'
          import json, pathlib
          data = json.load(open("/tmp/docs.json"))["data"]
          ids = sorted(d["id"] for d in data)
          snap = pathlib.Path("snapshots/petr4-itr-2025.txt")
          snap.parent.mkdir(exist_ok=True)
          old = snap.read_text().splitlines() if snap.exists() else []
          new = [i for i in ids if i not in old]
          if new:
              print("NEW", new)
              raise SystemExit(1)
          snap.write_text("\n".join(ids) + "\n")
          print("ok", len(ids))
          PY

Commit updated snapshots in a follow-up job if you want a green baseline after review.

Multi-ticker

Loop tickers from a YAML file. See Multi-ticker CVM filings watchlist.

Notify instead of only failing

After detecting new IDs, open a GitHub issue with gh or post to Slack. Keep the job red so the schedule is visible in Actions history.

Rate-limit-friendly batches

Sleep between tickers when watching >20 issuers. Read response headers:

curl -sSI -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=ITR&year=2025&perPage=1" \
  | tr -d '\r' | grep -i x-ratelimit

Pair with compliance workflows

For policy-style monitoring language, see Monitor Brazil regulatory filings for compliance. Actions is the scheduler; apicvm is the data plane.

Current limitations

• Not real-time — schedule granularity is your cron.
• Empty responses can mean ingestion lag; do not alert as “missing filing” without a second check.
• Respect rate limits when watching many issuers (X-RateLimit-*).

Next steps

• Get an API key
• Read the API docs
• Compliance monitoring use case
• curl guide

Related guides

• Handle rate limits
• Quarterly ITR monitoring