# Awesome Agent APIs — agent onboarding

One fetch teaches an agent the whole catalog. No install, no auth, no service —
this repo is plain data in git.

## What this is

A catalog of API tools an agent can call, split into two kinds of entry:

- `models/<slug>.yaml` — one of muapi's 660+ hosted generative-media models.
  Call it through your own muapi API key (https://muapi.ai/access-keys).
  Auto-generated from muapi's live catalog; not editable by PR.
- `providers/<slug>.yaml` — a third-party API tool a contributor already uses
  (SEO, enrichment, social, scraping, ads, market data, ...). Call it through
  *your own* account/key with that provider. Community-submitted via PR.

Nothing in this repo is a live proxy. Every entry is documentation only — you
call the tool directly, with your own credential.

## How to browse

1. Read `capabilities.yaml` for the full taxonomy (`media.*` for models,
   `seo.*`/`people.*`/`company.*`/`social.*`/`scraping.*`/`ads.*`/`market_data.*`
   for third-party tools). Pick the closest capability to what you need.
2. List `models/` or `providers/` and grep filenames, or read one entry
   directly — each file is self-contained.
3. A `providers/*.yaml` entry with `status: verified` has a matching
   `examples/<id>.json` with a real captured response — read that first if you
   want to see the actual shape of a response before calling anything.

## Entry shape

`models/<slug>.yaml`: `id`, `capability`, `via: muapi`, `title`, `description`,
`cost`, `docs_url` (a real `muapi.ai/playground/<slug>` page), `status: live`.
Never contains `base_url`, `auth`, or any internal routing detail — that's
intentional, not missing data.

`providers/<slug>.yaml`: `provider`, `docs_url`, `status` (`draft`/`verified`),
`auth` (`location`/`format`/`bad_key_behavior`), `pricing` (`model`/`amount`/
`source_url`/`checked`), `endpoints` (list of `id`/`method`/`path`/`params`),
`base_url`. Everything needed to call the tool directly is here — no need to
open the provider's own docs first, though `docs_url` is there if you want them.

## Contributing (agents welcome)

See CONTRIBUTING.md. The short version for `providers/*.yaml`: copy
`providers/_TEMPLATE.yaml`, fill it from the provider's real docs, get a real
key, actually call at least one endpoint, capture the response into
`examples/<id>.json`, run `python3 scripts/catalog_validate.py providers/<file>.yaml`,
open a PR. `models/*.yaml` is not a PR target — open an issue instead.
