# List your API in the treg catalog — instructions for a coding agent

You are helping an API vendor get listed in treg's tool catalog (https://treg.wrldwide.agency). The deliverable is a
**pull request to https://github.com/superdesigndev/treg** containing the listing, plus a way for
the maintainers to reach your team.

## Before you write anything

Clone the repo and read these two files — they are the authority, this page is only the summary:

- `docs/VENDORS.md` — eligibility rules, the vendor checklist, and a complete worked example
  (a fictional provider "Acme SEO" showing every file a listing needs).
- `.claude/skills/vendor-listing/SKILL.md` — the exact review pipeline your PR will be run
  through, including the live bogus-key test.

Confirm eligibility first. Hard requirements: self-serve API keys (no sales call), the key rides
in a **header or query param** (never the URL path), a free or near-free probe endpoint that
**rejects an invalid key** with a distinguishable response, a published pricing page, and docs
with example parameter values. If any of these fail, stop and tell your user which one — a PR
that fails them will be declined.

## What the PR contains

1. **Registry entry** — an `OAuthProvider(auth_kind="key", …)` in `src/treg/oauth_providers.py`,
   appended to `REGISTRY`: service slug, display name, `base_url`, auth mechanics
   (`token_header`/`token_format` or `token_location="query"`+`token_param`), `category`,
   one-line `summary`, `docs_url`, `probe_path`, and `setup_url`/`setup_steps` so users can find
   their key. Copy the shape of the `HUNTER` entry.
2. **Logo** — `src/treg/web/logos/<service>.svg`, a **neutral lettermark** (do not reproduce the
   real brand mark).
3. **Tests** — add the service id to `test_every_provider_is_registered`
   (tests/test_oauth_providers_m3.py) and the offerable loop in tests/test_key_providers.py.
4. **Core catalog file** — `src/treg/catalog/<service>.yaml` with the 8–15 endpoints an agent
   would actually reach for, each with: a `capability` from `src/treg/catalog/capabilities.yaml`
   (propose missing ones under `proposed_capabilities:`), typed `input` params, a **cheap**
   `test_request` (smallest limit, public well-known target), and a `cost` block with provenance
   (`value`, `currency`, `type`, `source`, `source_url`, `checked`, `confidence`). Follow the
   schema in the worked example.

## Verify before opening the PR

```bash
uv run --frozen python scripts/catalog_validate.py   # must exit 0
uv run --frozen python -m pytest -q                  # must pass
```

Do NOT stamp `verified:` on any endpoint and do NOT commit example responses — live verification
runs on the maintainers' side with a test credential. And **never put a credential value anywhere
in the diff**: no API keys in the YAML, the tests, the PR description, or commit messages.

## The PR description — required

- **A contact email** for your team, stated plainly (e.g. `Contact: partnerships@yourapi.com`).
  The maintainers reach out on this address to arrange a test credential for live verification —
  a PR without it cannot be verified or merged.
- Your probe endpoint's exact bad-key behavior (status code, or the JSON field that flips).
- Your pricing page URL and billing model; a machine-readable rate-card endpoint if you have one
  (that is the fastest path to treg serving your endpoints on its own key, metered).
- Whether you publish an OpenAPI spec at a stable URL (enables a machine-generated "extended
  tier" listing of your full endpoint surface).

## What happens next

Maintainers run the live checks: a garbage key POSTed at your probe must come back rejected, and
every endpoint's `test_request` is called with the test credential you arrange over email.
Endpoints that pass get `verified:` stamps and captured example responses; then the PR merges and
your API is discoverable by every agent using the catalog — compared side by side with other
providers on price, measured success rate, and speed.