# Skmtc

> A public catalog of thousands of OpenAPI schemas with generated, browsable API docs, plus code generators and generator stacks that turn any schema into production TypeScript. When a schema changes, subscriptions turn the diff into a pull request against your repo.

## Read the markdown, not the HTML

Every API page on this site has a plain-markdown twin at the same URL with
`.md` appended, and every HTML page that has one says so in a
`Link: rel="alternate"; type="text/markdown"` response header. Sending
`Accept: text/markdown` to the HTML URL returns the markdown directly. An
operation's HTML page is ~150 KB; its markdown is ~5 KB of the same content.

An operation's URL is its path followed by its method, with parameters as
`:name`: `GET /repos/{owner}` lives at `docs/repos/:owner/get`. The
unversioned form resolves to the API's latest version and is the URL to cite;
every path prefix also answers with an `llms.txt` listing its operations and
narrower prefixes, so any endpoint is reachable by narrowing from the root.

- https://skmtc.dev/{account}/apis/{api}/llms.txt: every operation in an API, each linked to its markdown. Start here: one fetch replaces crawling hundreds of pages
- https://skmtc.dev/{account}/apis/{api}.md: what the API is, its license and source, operation counts by tag
- https://skmtc.dev/{account}/apis/{api}/docs/{path}/{method}.md: one operation at the latest version, with its parameters, request body and responses
- https://skmtc.dev/{account}/apis/{api}/docs/{prefix}/llms.txt: one node of the path tree, with its operations and narrower prefixes. Operation responses point at their parent node with `Link: rel="up"`
- https://skmtc.dev/{account}/apis/{api}/revisions/{version}/docs/{path}/{method}.md: the same operation pinned to one version
- https://skmtc.dev/{account}.md: one publisher, with every API they publish linked to its markdown
- https://skmtc.dev/explore.md: every public API in the catalog, one page at a time, each page linking the next. It also lists the categories
- https://skmtc.dev/explore/{category}.md: the same list for one category, such as /explore/payments-finance.md

Version-pinned URLs change rarely (`{version}` is a content hash) and are
served with a one-month shared TTL. Safe to cache, but not indefinitely: the
schema at that version is fixed, the rendering of it is not. The unversioned
form is served with a short revalidating TTL instead, so it tracks the latest
version closely.

## What changed

Poll one of these instead of re-crawling. Both are ordered by when skmtc-hub
RECORDED each entry, not by when it happened, so a fact recovered from an
older date still arrives at the top where a poller will see it. Each entry
carries both instants.

- https://skmtc.dev/feed.atom, /feed.json, /feed.md: catalog-wide revisions that broke something. Deliberately not every revision; the catalog records thousands on a busy day
- https://skmtc.dev/{account}/feed.atom, /feed.json, /feed.md: one publisher, everything recorded across the APIs they own

## HTML pages

- https://skmtc.dev/explore: browse the catalog
- https://skmtc.dev/{account}/apis/{api}: an API's generated docs (per-operation pages under /revisions/{ref}/docs/)
- https://skmtc.dev/sitemap.xml: the full URL inventory, including every documented operation

## For programs: check a list of services in one call

`POST https://api.skmtc.dev/v1/apis/lookup` takes up to 25 service names and answers,
per name, found / ambiguous / not_found, with the matched API's freshness
(lastCheckedAt: when we last looked; lastUpdatedAt: when the schema last
changed), operation count, spec type, and the addresses above (markdown,
llms.txt, the `?raw` schema permalink pinned by content ref, the publisher's
feed). No credentials for public APIs.

```
curl -s https://api.skmtc.dev/v1/apis/lookup -H 'content-type: application/json' \
  -d '{"items":[{"name":"stripe"},{"name":"twilio","hint":"sms"},{"name":"github/rest"}]}'
```

A client that can only send GET uses
`GET https://api.skmtc.dev/v1/apis/lookup?names={name},{name}`: the same answer for up
to 25 comma-separated names, without hints.

```
curl -s 'https://api.skmtc.dev/v1/apis/lookup?names=stripe,twilio,github/rest'
```

## For programs: search the catalog

`GET https://api.skmtc.dev/v1/search?q={query}&type=api` ranks APIs by their name
and short description, for finding an API by what it does when you do not
know who publishes it. It answers one page of up to `limit` results (25 by
default, 50 at most) and has no next page. Each result carries `htmlUrl`;
append `.md` to it for the API's markdown. No credentials for public APIs.

Optional filters:

- `owner`: an account handle
- `auth`: `apiKey`, `http`, `oauth2`, `openIdConnect`, `mutualTLS`
- `webhooks`: `true` or `false`
- `pagination`: `cursor`, `page`, `offset`, `none`
- `specType`: `openapi`, `swagger`
- `minOperations`: a number

```
curl -s 'https://api.skmtc.dev/v1/search?q=send+sms&type=api&webhooks=true&limit=5'
```

The same tools over MCP, no auth: `https://mcp.skmtc.dev/mcp` (Streamable HTTP):
lookup_apis, search_apis, get_api, list_operations, get_operation,
ask_catalog. `claude mcp add --transport http skmtc https://mcp.skmtc.dev/mcp`.

The rest of the catalog is also served as JSON from https://api.skmtc.dev, and every
resource in a response carries `url` (its API location) and `htmlUrl` (its
page here). It is meant for programs written against the catalog, not for
crawling: https://api.skmtc.dev/robots.txt disallows it, except for the lookup and
the search above and the discovery paths `/.well-known/` and `/health`.
Everything it returns is published on this site as markdown, which is cheaper
to serve and cheaper to read.

## Skills for coding agents

These skills teach an agent to author Skmtc generators. They are installable
(`npx skills add skmtc/skmtc`, or `/plugin install skmtc@skmtc` in Claude Code),
and each page here renders the same bytes the install delivers.

- https://skmtc.dev/skills: the published set, in the order an agent loads them
- https://skmtc.dev/skills/skmtc-generator: Engine rules, load first
- https://skmtc.dev/skills/skmtc-lang-typescript: The emitted TypeScript
- https://skmtc.dev/skills/skmtc-model: One definition per component schema
- https://skmtc.dev/skills/skmtc-operation: One definition per (path, method)
- https://skmtc.dev/skills/skmtc-cli: Workspaces, config, the agent contract

An agent that would rather read the source than the page can fetch any skill
raw from
https://raw.githubusercontent.com/skmtc/skmtc/main/deno/docs/skills/{skill}/SKILL.md

## Documentation

- https://docs.skmtc.dev/docs/api-change-webhooks: API change webhooks — a signed CloudEvent to your HTTPS endpoint when an API changes
- https://docs.skmtc.dev/openapi/api-change-webhooks-v1.json: the webhook request as OpenAPI 3.1
- https://docs.skmtc.dev/llms.txt: docs index; every page is also served as plain markdown
- https://skmtc.dev/.well-known/api-catalog: machine-readable catalog of this publisher's own API (RFC 9727 linkset)