# How to check which APIs the catalog tracks



## When to use this [#when-to-use-this]

You plan to build against some third-party APIs. Before you start, you
want three facts for each one. Does skmtc-hub track it? How current is the
schema? Which addresses give an agent or a script the rest?

## Prerequisites [#prerequisites]

* A list of service names as a developer types them: `stripe`, `twilio`,
  `google sheets`. The hub reads an `owner/slug` such as `stripe/spec3`
  directly.
* No account. Public APIs answer without credentials. A personal access
  token adds the APIs your account can read.

## Steps [#steps]

### In a browser [#in-a-browser]

Open [skmtc.dev/lookup](https://skmtc.dev/lookup), paste the list with one
name on each line, and press Check. The list goes into the URL, so the result is a
link you can send.

### From a script [#from-a-script]

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

Up to 25 names for each call. Each result carries:

* `status`: `found`, `ambiguous` or `not_found`.
* `matchedBy`: how the name matched. `owner` means the name is a
  publisher's handle or display name, and the match is that publisher's
  API. `api` means the name appeared only in an API's own name, slug or
  provider name. That pass never claims a match; it offers candidates.
  `direct` means you gave `owner/slug`.
* `match` (for `found`) or `candidates` (up to five, ranked by size) with
  `candidateTotal`, the count before the cap.
* On each match: `lastCheckedAt` (when the hub last looked at a source)
  and `lastUpdatedAt` (when the schema last changed). Also
  `operationCount`, `specType`, `refetchEnabled`, `sourceUrl`, and `links`.

`links` are the addresses to use next:

| link           | what it serves                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `html`         | the API's page                                                                                               |
| `api`          | the API's JSON record                                                                                        |
| `markdown`     | the page as markdown: description, license, source, counts                                                   |
| `llmsTxt`      | every operation, one fetch, each linked to its markdown                                                      |
| `schema`       | the OpenAPI document pinned by content ref (stable bytes); absent when the latest revision holds no document |
| `schemaLatest` | the floating address; redirects to `schema`                                                                  |
| `feed`         | the publisher's change feed (JSON Feed)                                                                      |

Cite the unversioned addresses. An address that contains a content ref
always returns the same bytes.

### Narrow a publisher with many APIs [#narrow-a-publisher-with-many-apis]

A name that matches a publisher with some APIs comes back `ambiguous`
with its five largest. Add a `hint`:

```json
{ "items": [{ "name": "hubspot", "hint": "contacts" }, { "name": "github", "hint": "rest" }] }
```

A hint equal to a candidate's slug selects it. Otherwise it keeps the
candidates whose name, slug or summary contain it. The hub ignores a hint
that matches nothing, so the result stays as it was.

### From an MCP client [#from-an-mcp-client]

The same answer, plus five more tools, over the hub's MCP server. No
authentication.

```sh
claude mcp add --transport http skmtc https://mcp.skmtc.dev/mcp
```

For VS Code, add to `.vscode/mcp.json`:

```json
{ "servers": { "skmtc": { "type": "http", "url": "https://mcp.skmtc.dev/mcp" } } }
```

The tools:

* `lookup_apis`: this endpoint.
* `search_apis`: ranked cards with facets.
* `get_api`: the JSON record.
* `list_operations`: the `llms.txt`, whole or one path prefix.
* `get_operation`: one operation as markdown, with its recorded changes.
* `ask_catalog`: a question answered from the indexed schemas, with citations.

## What a miss means [#what-a-miss-means]

`not_found` means no live API you can read matches by publisher, name,
slug or provider name. The hub logs every name you ask for. The misses are
the list it harvests next. So a request for an API that is not there is
useful, even when the answer is no.

## Related [#related]

* [Search](https://skmtc.dev/search) — ranked search and questions across the catalog.
* Subscribe on an API's page at [skmtc.dev](https://skmtc.dev) to get a pull
  request when a schema you build against changes.