HTTP API, MCP and CLI

Everything this site shows, programs get over HTTP, agents over MCP and people at a terminal from the CLI, in the same words. Answers from the Index are open to anyone; Discovery needs a key.

HTTP API

JSON over HTTPS at https://swaggerbot.dev. Every route but GET /api/health counts against the per-IP limit; a method a route doesn't take is a 405 with an Allow header, and a path no route serves is a JSON 404.

The routes

Route	Gives	Key
POST/api/lookup	The Outcome.	Key: For Discovery and fresh
GET/api/vendors[?query=&cursor=&limit=]	The Vendors with at least one API in the Index, by name, 50 a page (`limit` at most 200).	Key: No
GET/api/vendors/{vendor}/apis	A Vendor's APIs in the Index, each with its Current Spec.	Key: No
GET/api/apis/{apiId}/outline	The Spec Outline, paged with `tag`, `query`, `cursor` and `limit`, with the tag list.	Key: No
GET/api/apis/{apiId}/operation	One operation, with the references it reaches inlined.	Key: No
GET/api/apis/{apiId}/schema	One component schema.	Key: No
GET/api/specs/{specId}/published, …/normalized	The Spec's Published Form or Normalized Form.	Key: No
GET/api/key	The key the bearer names: its `id`, and today's credits `remaining`, the `limit` and when they reset (`resetsAt`) as far as the key store knows them. Verifies the key without spending a credit.	Key: Yes (costs nothing)
GET/api/health	`{"ok":true}`	Key: No

Each example is a real call to https://swaggerbot.dev and the answer it gave on 26 Sept 2026, for Val Town's API. Ids and dates change as the Index verifies Specs again; the shape of each answer doesn't.

POST/api/lookup

Takes { name, apiVersion?, allowCommunity?, fresh? } and answers with exactly one Outcome: Resolved, Ambiguous, Unconfirmed, No Spec or Unknown. A name the Index already answers needs no key.

curl -X POST https://swaggerbot.dev/api/lookup -H "Content-Type: application/json" -d '{"name":"Val Town"}'

{
  "outcome": "Resolved",
  "api": { "id": "val.town/api", "vendorId": "val.town", "name": "Val API" },
  "vendor": { "id": "val.town", "name": "val.town", "domain": "val.town" },
  "currentSpec": {
    "id": "4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df",
    "apiId": "val.town/api",
    "specVersion": "3.1.0",
    "apiVersion": "1",
    "isPreview": false,
    "supersededAt": null,
    "format": "json",
    "byteLength": 72545,
    "downloads": {
      "published": "https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/published",
      "normalized": "https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/normalized"
    },
    "normalized": "ready"
  },
  "alternateSpecs": [],
  "provenance": "Official",
  "sources": [
    {
      "id": 29,
      "specId": "4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df",
      "url": "https://api.val.town/openapi.json",
      "provenance": "Official",
      "firstSeenAt": "2026-09-23T07:42:46.292Z",
      "lastVerifiedAt": "2026-09-24T00:07:16.403Z"
    }
  ],
  "verifiedAt": "2026-09-24T00:07:16.403Z",
  "validityIssues": [],
  "validityIssueCount": 0
}

POST/api/lookupa name the Index doesn't know

Finding it on the live web is Discovery, which needs a key: send the same request with Authorization: Bearer <key>. So does fresh: true.

curl -X POST https://swaggerbot.dev/api/lookup -H "Content-Type: application/json" -d '{"name":"Not Yet Indexed"}'

HTTP 401
{
  "error": "Discovery needs an API key.",
  "hint": "Send it as `Authorization: Bearer <key>`. Get a key at https://swaggerbot.dev/keys."
}

GET/api/vendors

The Vendors with at least one API in the Index, ordered by name. query is a substring of the id or name, ignoring case; nextCursor is null on the last page. A bad limit or cursor is a 400.

curl "https://swaggerbot.dev/api/vendors?query=val"

{
  "vendors": [{ "id": "val.town", "name": "val.town", "apiCount": 1 }],
  "total": 1,
  "nextCursor": null
}

GET/api/vendors/{vendor}/apis

A Vendor's APIs in the Index, each with its Current Spec, Provenance and verifiedAt.

curl https://swaggerbot.dev/api/vendors/val.town/apis

{
  "vendor": { "id": "val.town", "name": "val.town", "domain": "val.town" },
  "apis": [
    {
      "api": { "id": "val.town/api", "vendorId": "val.town", "name": "Val API" },
      "currentSpec": {
        "id": "4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df",
        "apiId": "val.town/api",
        "specVersion": "3.1.0",
        "apiVersion": "1",
        "isPreview": false,
        "supersededAt": null,
        "format": "json",
        "byteLength": 72545,
        "downloads": {
          "published": "https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/published",
          "normalized": "https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/normalized"
        },
        "normalized": "ready"
      },
      "alternateSpecs": [],
      "provenance": "Official",
      "verifiedAt": "2026-09-24T00:07:16.403Z"
    }
  ]
}

GET/api/apis/{apiId}/outline

The Current Spec's operations, 100 a page by default (limit up to 500), filtered by tag or by query (a word of the path, operationId or summary), with the tag list. The API id keeps its slash.

curl "https://swaggerbot.dev/api/apis/val.town/api/outline?tag=me"

{
  "apiId": "val.town/api",
  "specId": "4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df",
  "title": "Val Town API",
  "apiVersion": "1",
  "servers": ["https://api.val.town"],
  "securitySchemes": [{ "name": "bearerAuth", "type": "http", "scheme": "bearer" }],
  "tags": [
    { "name": "vals", "operationCount": 20 },
    { "name": "alias", "operationCount": 2 },
    { "name": "me", "operationCount": 2 },
    …
  ],
  "operations": [
    { "method": "get", "path": "/v1/me", "operationId": "meGet", "tags": ["me"] },
    { "method": "get", "path": "/v2/me/vals", "operationId": "meVals2", "tags": ["me"] }
  ],
  "totalOperations": 52,
  "matchedOperations": 2,
  "nextCursor": null,
  "specVersion": "3.1.0",
  "normalized": "ready",
  "downloads": {
    "published": "https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/published",
    "normalized": "https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/normalized"
  }
}

Abridged: … stands for the other eleven tags.

GET/api/apis/{apiId}/operation

One operation of the Current Spec (or of specId): method in any case, path exactly as the Spec writes it, URL-encoded. Its parameters, effective security and every $ref it reaches are inlined, to 1 MB. 404 for an unknown operation, 409 while the Spec's forms are still being built.

curl "https://swaggerbot.dev/api/apis/val.town/api/operation?method=delete&path=/v1/blob/%7Bkey%7D"

{
  "apiId": "val.town/api",
  "specId": "4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df",
  "method": "delete",
  "path": "/v1/blob/{key}",
  "operation": {
    "operationId": "v1blobsDelete",
    "tags": ["blobs"],
    "description": "Delete a blob",
    "parameters": [
      {
        "schema": { "type": "string", "minLength": 1, "maxLength": 512 },
        "in": "path",
        "name": "key",
        "required": true,
        "description": "Key that uniquely identifies this blob"
      }
    ],
    "security": [{ "bearerAuth": [] }],
    "responses": { "204": { "description": "Blob successfully deleted" } }
  },
  "circular": {},
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "description": "Endpoints that support authorization expect Bearer authentication, using an API token provided from Val Town."
    }
  },
  "truncated": false
}

GET/api/apis/{apiId}/schema

One component schema by name, to follow a reference an operation left.

curl "https://swaggerbot.dev/api/apis/val.town/api/schema?name=PaginationLinks"

{
  "apiId": "val.town/api",
  "specId": "4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df",
  "name": "PaginationLinks",
  "schema": {
    "type": "object",
    "required": ["self"],
    "properties": {
      "self": { "type": "string", "format": "uri", "description": "URL of this page" },
      "prev": { "type": "string", "format": "uri", "description": "URL of the previous page, if any" },
      "next": { "type": "string", "format": "uri", "description": "URL of the next page, if any" }
    },
    "description": "Links to use for pagination"
  },
  "circular": {},
  "truncated": false
}

GET/api/specs/{specId}/published

The Spec's Published Form, byte for byte as the Vendor serves it, so its sha256 is the Spec id.

curl -s https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/published | sha256sum

4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df  -

GET/api/specs/{specId}/normalized

The Spec's Normalized Form: bundled and converted to OpenAPI 3.1, JSON. 409 while it is still being built.

curl -s https://swaggerbot.dev/api/specs/4b446f57c9327311b6b68ad0a0e53b19341971a436cd9f0fda2630e3445483df/normalized | head -c 19

{"openapi":"3.1.0",

GET/api/key

The key the bearer names, verified at no cost to its credits: its id, today's remaining credits and limit, and resetsAt, when they refill (midnight UTC). 400 without a bearer, 401 for a key that isn't live. The CLI's login and key call it.

curl https://swaggerbot.dev/api/key -H "Authorization: Bearer <key>"

{
  "id": "key_6n4y7w33",
  "remaining": 100,
  "limit": 100,
  "resetsAt": "2026-10-17T00:00:00.000Z"
}

Recorded on 2026-10-16 against a build of the service on a copy of the Index, with a key issued by hand (scripts/keys.ts create): the id and figures are that key's, which had spent nothing that day.

GET/api/health

Whether the service is up. Not rate-limited.

curl https://swaggerbot.dev/api/health

{"ok":true}

MCP

For agents: an MCP server over Streamable HTTP, stateless, with five tools that answer as the HTTP API does. Each result carries its JSON as structuredContent and a text that starts with a sentence for the agent and the next call to make.

The endpoint

https://swaggerbot.dev/mcp

Add it to Claude Code

claude mcp add --transport http swaggerbot https://swaggerbot.dev/mcp

With a key, for Discovery and fresh:

claude mcp add --transport http swaggerbot https://swaggerbot.dev/mcp --header "Authorization: Bearer <key>"

The five tools

Tool	Gives	Over
lookup_api{ name, apiVersion?, allowCommunity?, fresh? }	The Outcome, with the Spec's download URLs (the Spec itself is never returned inline).	Over: POST/api/lookup
list_vendor_apis{ vendor }	A Vendor's APIs in the Index, each with its Current Spec.	Over: GET/api/vendors/{vendor}/apis
get_spec_outline{ apiId, specId?, tag?, query?, cursor? }	One page (at most 100) of the Spec Outline's operations, with the tag list and `nextCursor`.	Over: GET/api/apis/{apiId}/outline
get_operation{ apiId, method, path, specId? }	One operation with the references it reaches inlined; a path that isn't in the Spec gets the nearest ones.	Over: GET/api/apis/{apiId}/operation
get_schema{ apiId, name, specId? }	One component schema, to follow a reference `get_operation` or `get_schema` left.	Over: GET/api/apis/{apiId}/schema

Result sizes

Every result stays under 30 kB, its structuredContent as JSON and its text together: below Claude Code's 10,000-token warning.
get_spec_outline gives at most 100 operations a page. On a Spec of more than 100 without a filter, it gives the tag list and the first page, and says to filter by tag or query.
get_operation and get_schema inline references breadth-first up to 24 kB. Past that a reference stays { "$ref", "x-truncated": true }, which get_schema follows; a schema that recurs within itself is { "$ref", "x-circular": true }.
The Spec itself never comes back inline: lookup_api gives its download URLs.

CLI

For people at a terminal: swaggerbot, a client of the HTTP API above. It needs Node 20 or later.

Install

npx swaggerbot lookup "Val Town"

Or install it, to run it as plain swaggerbot:

npm install -g swaggerbot

A name the Index answers needs no key. For Discovery and --fresh, get a key on the keys page, then store it:

swaggerbot login

It asks for the key, hidden, checks it at no cost to its credits and keeps it in a file only you can read: ~/.config/swaggerbot/config.json, or %APPDATA%\swaggerbot\config.json on Windows. --key or SWAGGERBOT_API_KEY sends another key for one command.

The commands

swaggerbot lookup <name> [--api-version V] [--community] [--fresh]
The Outcome in one line: the API, its Spec's URL and Provenance, or why there is none.
```
swaggerbot lookup "Val Town"
```
swaggerbot login [--key K]
Checks a key at no cost to its credits and stores it for this swagger.bot; asked for, hidden, when --key isn't given.
```
swaggerbot login
```
swaggerbot logout
Forgets the stored key.
```
swaggerbot logout
```
swaggerbot key
The key in use: its id, credits left today, when they reset.
```
swaggerbot key
```
swaggerbot spec <name | apiId | specId> [--form published|normalized] [--api-version V] [-o FILE] [--force] [--no-wait]
Downloads the Spec, by name (a Lookup, Resolved only), API id or Spec id, and checks its sha256 is its Spec id.
```
swaggerbot spec "Val Town" -o openapi.json
```
swaggerbot outline <name | apiId> [--tag T] [--query Q] [--spec-id S] [--limit N] [--all]
The Spec Outline: title, servers, security schemes, tags, then the operations, filtered by tag or a word.
```
swaggerbot outline val.town/api --tag me
```
swaggerbot operation <name | apiId> <method> <path> [--spec-id S]
One operation, every reference inlined, as JSON.
```
swaggerbot operation val.town/api delete /v1/blob/{key}
```
swaggerbot schema <name | apiId> <schemaName> [--spec-id S]
One component schema, as JSON.
```
swaggerbot schema val.town/api PaginationLinks
```
swaggerbot vendors [<query>] [--all]
The Vendors in the Index, 50 a page: id, name and API count.
```
swaggerbot vendors val
```
swaggerbot vendor <vendor>
A Vendor's APIs in the Index, each with its Current Spec, Provenance and download URLs.
```
swaggerbot vendor val.town
```

JSON

Every command takes --json: it prints the same JSON as the HTTP API, so the answers above apply. On a failed request it prints the error body too.

Exit codes

Code	When
0	Resolved, or the command did what it was asked.
3	Ambiguous.
4	Unconfirmed.
5	No Spec.
6	Unknown.
1	Refused or failed: no key, the quota used, the service unreachable, a download that isn't its Spec.
2	A usage error.

A self-hosted swagger.bot

--url <origin> (or SWAGGERBOT_URL) points the CLI at another swagger.bot than https://swaggerbot.dev. A key login stored is sent only to the origin it was checked with.

Keys and limits

The same rules hold over HTTP and MCP. A key is sent as Authorization: Bearer <key>.

A key is optional for anything the Index answers: a Lookup of a name it knows, the outline, operations, schemas, Vendor lists and downloads. They use no quota.
Discovery (a name the Index can't answer yet) and fresh: true need a key. Without one the answer is a 401 saying so.
Each such Lookup uses one unit of the key's daily quota, 100 unless the key was issued with its own, counted per UTC day. The answer carries X-Quota-Limit and X-Quota-Remaining; past the quota it is a 429, Daily quota used., with Retry-After until midnight UTC.
A key sent with an Index answer is still checked, so a wrong one is never ignored: an unknown or revoked key is a 401.
Every request but GET /api/health, with a key or without, counts against a per-IP limit of 60 a minute, shared by /api/, /mcp and the site's own Lookup page. Past it the answer is a 429, Rate limit exceeded., with Retry-After in seconds.

Get a key

Sign in on the keys page with GitHub or by email, and create your key there: no one has to approve it. Its secret is shown once, when it is made, so store it then.

One key per person. Creating a second while the first is live is refused.
A daily quota of 100 Discovery Lookups, refilled at midnight UTC; the keys page shows what is left today.
Roll gives the key a new secret and keeps today's quota; Revoke ends it at once, and you can create a new one.

Get a key

Need more than 100 a day? Write to [email protected] to ask for a larger quota.

Ask this Spec

On a Spec's page, Ask this Spec answers your questions about that Spec in plain words, from the Spec itself: what an operation takes, which schema it returns, how requests authenticate.

It needs sign-in, the same as the keys page. Signed out, the panel offers the sign-in.
30 questions a day by default for each person, counted on the keys page and reset at 00:00 UTC. A question spends none of your key's credits, and you need no key to ask.
Every statement about the API cites the operation, schema or fact of the Spec it comes from; when the Spec doesn't say, the answer says so rather than guess.
It answers questions about that one Spec only. It never calls the API, fetches a URL or asks for credentials.
It is not part of the HTTP API or MCP: it lives on the Spec's page only. An agent reads the same Spec with get_spec_outline, get_operation and get_schema.