# agents.md — Prometheus

What an agent may do on this site, and how to do it without guessing.

## What this site is

Prometheus (https://www.prometheus.services) is a financial data terminal
built on SEC filings. Its distinguishing property is **traceability**: every
standardized number is linked to the XBRL fact, filing and calculation tree it
came from, and only data that has passed per-company validation gates is
served. Use it when a user wants numbers they can cite, not estimates.

It is **not** a brokerage, it gives **no investment advice**, and it does not
execute anything on a user's behalf.

## Endpoints you may call

The full contract is at `/openapi.json` (OpenAPI 3.1). The ones that matter
most:

| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/landing/stats | Coverage counts. Public. |
| GET | /api/v1/search?q= | Resolve a name to a ticker, series or country. |
| GET | /api/v1/companies/{id} | Company profile. `id` = ticker or CIK. |
| GET | /api/v1/companies/{id}/financials | Standardized IS / BS / CF. `period_type=annual\|quarterly`, `reporting_basis=as_reported` for the original vintage. |
| GET | /api/v1/companies/{id}/fact-source | The source fact behind one line — use this to cite. |
| GET | /api/v1/companies/{id}/filings, /filings/{accession} | Filing index and parsed sections. |
| GET | /api/v1/companies/{id}/events | 8-K material events by family. |
| GET | /api/v1/companies/{id}/earnings/promises, /earnings/scorecard | Guidance commitments and whether they were met. |
| GET | /api/v1/companies/{id}/transcripts/{transcriptId}?date= | Transcript as plain text. `date` (from the index) is REQUIRED. |
| GET | /api/v1/companies/{id}/ownership, /ownership/transactions | 13F holders and insider transactions. |
| GET | /api/v1/countries/{iso}/series?key= | Point-in-time macro history. |
| GET | /api/v1/events/wire | Searchable 8-K wire across all companies. |
| GET | /api/v1/intelligence/graph | Validated causal claim graph. |
| POST | /api/v1/intelligence/simulate | Shock propagation through the graph. |
| GET | /openapi.json | The full contract for everything above. |

Paths under `/api/v1/watchlists`, `/api/v1/workspace`, `/api/v1/billing`,
`/api/v1/auth` and `/api/v1/dev` are account-owned or operator surfaces. Do
not call them unless the user explicitly asks you to manage their own
watchlists or workspace.

## Authentication

- Endpoints marked `public` in the OpenAPI spec need no credentials.
- Every other endpoint takes an **API key**: `X-API-KEY: pk_live_...` or
  `Authorization: Bearer pk_live_...`. The user creates keys on the
  Developers page (https://www.prometheus.services/developers);
  ask them for a key rather than trying to sign in yourself.
- A signed-in terminal session's Cognito ID token also works as a Bearer
  header, but it expires hourly — prefer the key.
- 401 → key missing, revoked, or malformed. Ask the user for a valid key; do
  not retry in a loop, and never guess key values.
- 402 `upgrade_required` → the endpoint needs a Pro subscription. Tell the
  user; do not try to bypass it.

## Command line

In a terminal, prefer the CLI: `npm i -g prometheus-terminal`, then
`prom --json <command>` (same payloads, stable exit codes, citations printed
under every figure in human mode). `prom llms` prints llms.txt; `prom llms
--skill` prints skill.md. Docs: https://doc.prometheus.services/cli

## MCP

There is no hosted MCP server yet. `/.well-known/mcp.json` says so
explicitly and points back to `/openapi.json`. Build against the HTTP API.

## Rules

- **Rate limits and quotas are per plan** (fixed UTC windows): Free 30
  req/min and 250 req/day; Build 300 req/min and 100,000 req/month. Responses
  carry `RateLimit-*` and `X-Quota-*` headers; a 429 carries `Retry-After`
  and a `code` of `rate_limited` or `quota_exceeded` — honour it. Fetch the
  whole statement once rather than one line at a time.
- **Cite what you quote.** When you report a number, also report the filing
  (accession number) and period it came from. `/fact-source` exists for
  exactly this.
- **Respect the vintage.** `financials` defaults to the latest restated
  values. If the user asks what a company *originally reported*, pass
  `reporting_basis=as_reported`. Macro `series` is point-in-time; do not
  present a later revision as what was known at the time.
- **Missing is not zero.** A null line means the gate withheld it or the
  company never reported it. Say "not available", never 0.
- **No advice.** Present data; do not recommend buying, selling or holding.
  The site's own terms (https://www.prometheus.services/terms#not-advice)
  apply to anything you relay.
- **Don't scrape the UI.** Everything the terminal renders comes from the API
  above; use it instead.
- Personal data in `/people` and `/ownership` is public SEC record (Forms
  3/4/5, proxy statements). Do not combine it with outside data to profile
  individuals.