← Back to blog

OpenAPI Spec + Postman Collection: API Discovery for Agents

September 23, 2026 · Eric · 8 min read

Every integration starts with the same two questions: what is the exact endpoint, and what does it want in the body? You can read docs pages one at a time, or you can pull the four machine-readable surfaces that answer both questions in a single request each. None of them need an API key, and none of them are rate-limited the way the media tools are.

Everything in this post was checked live against https://agentmediatools.com on September 23, 2026. Counts move as tools ship, so the examples below show you how to re-derive them instead of asking you to trust a number in a blog post.

What you can discover without an API key

SurfaceEndpointWhat it gives you
OpenAPI specGET /openapi.jsonOpenAPI 3.1.0 document: 111 paths, 120 operations, security schemes
Postman collectionGET /api/postman-collectionPostman v2.1 collection: 37 folders, 132 ready-to-send requests
Tool catalogGET /api/tools104 catalog entries with id, category, tier, description
Catalog filtersGET /api/tools?category=&tier=Exact-match (case-insensitive) filtering on category and tier
Tool detailGET /api/tools/{id}One entry, plus /related for adjacent tools
Catalog statsGET /api/tools/statsTotals per tier and per category — the honest source for "how many tools"
Catalog searchGET /api/search?q=Ranked matches with a confidence score and the reason each matched
Agent docs JSONGET /api/agent-docsA curated 6-tool subset with auth_required flags and endpoint lists

1. Pull the spec and count what you actually got

The spec lives at the site root, not under /api — GET /api/openapi.json returns a 404. Grab it and summarize it locally:

curl -s https://agentmediatools.com/openapi.json -o openapi.json
curl -s https://agentmediatools.com/openapi.yaml -o openapi.yaml   # same spec, YAML flavor

Then walk it with plain Python. This is the snippet I keep in a scratch file whenever I want a real inventory instead of a marketing number:

Every Python example in this post is short enough to paste into a REPL. This one deliberately uses the standard library only, so it runs on a clean machine; the later snippets use requests because the JSON work reads better that way.

import json, urllib.request, collections

SPEC_URL = "https://agentmediatools.com/openapi.json"
with urllib.request.urlopen(SPEC_URL, timeout=30) as r:
    spec = json.load(r)

by_tag = collections.Counter()
for path, methods in spec["paths"].items():
    for method, op in methods.items():
        if method in ("get", "post", "put", "patch", "delete"):
            for tag in op.get("tags", ["Uncategorized"]):
                by_tag[tag] += 1

print("spec:", spec["openapi"], "| api version:", spec["info"]["version"])
print("paths:", len(spec["paths"]), "| operations:", sum(by_tag.values()))
print("top tags:", by_tag.most_common(5))

Run against production, that prints spec: 3.1.0 | api version: 2.0.0, paths: 111 | operations: 132 and a tag leaderboard headed by Agent API, Agent Relay, Agent Auth, and Agent Utilities. (Note the difference: 111 unique paths, 120 distinct operations, 132 operation-plus-tag pairs. The spec counts paths; the tag walk counts appearances.)

Two things in the document are worth knowing before you generate anything from it. First, it declares three security schemes — BearerAuth and bearerAuth (HTTP bearer API keys) and CookieAuth (the connect.sid session cookie for the web app). Second, it ships two servers: production, and http://localhost:3000 for local development. If you generate a client, point it at the production server entry; a generator that picks the first server will do the right thing, but plenty of generators ask you to choose.

2. Import the Postman collection

If you'd rather click than code, the same spec is exported as a Postman collection, grouped into folders by tag:

curl -s -OJ https://agentmediatools.com/api/postman-collection

The response sets Content-Disposition: attachment; filename="agent-media-tools-api.postman_collection.json", so a browser download and curl -OJ both name the file sensibly. The collection declares the Postman v2.1.0 schema and carries one collection variable, base_url, defaulted to https://agentmediatools.com.

Step 1
Import it. In Postman: Import → File → pick agent-media-tools-api.postman_collection.json. You should see 37 folders, from Agent API and Agent Relay through PDF Tools, Video Tools, and Webhooks.
Step 2
Know that the URLs are absolute. The collection declares a base_url variable set to production, but all 132 requests carry the full https://agentmediatools.com/... URL rather than {{base_url}} references. Testing against a local build therefore means editing the host — a find-and-replace, or a Postman environment with a pre-request script if you do it often.
Step 3
Fix the auth placeholders. Requests under /api/agent/ ship with an Authorization: Bearer YOUR_API_KEY header. Replace the placeholder — either per request, or once by adding a collection-level Authorization header with your real key.

You can verify what you imported without opening the app:

import requests

col = requests.get("https://agentmediatools.com/api/postman-collection", timeout=30).json()

def count(items):
    return sum(count(i["item"]) if "item" in i else 1 for i in items)

print(col["info"]["schema"])                       # .../v2.1.0/collection.json
print("folders:", sum(1 for i in col["item"] if "item" in i))
print("requests:", count(col["item"]))

That reports 37 folders and 132 request entries. The entry count is higher than the 120 distinct operations because a handful of operations carry more than one tag and therefore appear in more than one folder — convenient when you're browsing by topic, mildly confusing when you're counting.

3. Query the catalog instead of guessing tool ids

The catalog is the fastest way to answer "does this site do X, and what's it called?" It returns catalog entries, not endpoints — id, category, tier, description, and richer metadata on the entries that carry it:

curl -s "https://agentmediatools.com/api/tools/stats"
curl -s "https://agentmediatools.com/api/tools?tier=agent"
curl -s "https://agentmediatools.com/api/tools?category=Image%20Tools&tier=free"
curl -s "https://agentmediatools.com/api/tools/image-compress"

Live numbers from /api/tools/stats: 104 catalog entries across 12 categories, split into 66 free, 10 login-gated, 27 agent-tier, and 1 premium entry. Category and tier filters compose, and both are exact matches — ?category=Image%20Tools returns 10 entries while the same category narrowed to &tier=free returns 9. URL-encode the space; an unencoded space in the query string silently gives you nothing useful.

If you only remember an older name, try it anyway before assuming the tool is gone. An alias table resolves some of them: /api/tools/audio-extractor returns the canonical entry extract-audio-from-video, and /api/tools/trim-video returns video-trim. Coverage is partial, though — /api/tools/mailbox, /api/tools/zip, and /api/tools/image-compressor all return 404 with a JSON body naming the slug you asked for. So read the id field out of the response, and use the search endpoint below as your name resolver instead of hand-writing slugs.

4. Let your agent pick the tool at runtime

Catalog search is built for the case where an LLM decides what it needs but shouldn't invent which tool provides it. GET /api/search?q= returns count, top_tool, top_confidence, and a results array where every hit explains itself with a confidence score and a reason string like "tool ID contains query" or "tags match: compress".

import requests

BASE = "https://agentmediatools.com"

def find_tool(query):
    data = requests.get(f"{BASE}/api/search", params={"q": query}, timeout=15).json()
    return data.get("top_tool"), data.get("top_confidence")

tool, confidence = find_tool("base64 encode")
print("best match:", tool, confidence)      # base64 0.95

resp = requests.post(f"{BASE}/api/base64",
                     json={"text": "hello agent", "action": "encode"},
                     timeout=15)
print(resp.json()["output"])                # aGVsbG8gYWdlbnQ=

The reason strings are the part that matters for agents. A model that sees "reason": "description matches" at 0.65 confidence can decide to ask a clarifying question, while a 0.95 exact-ID match is safe to call directly. You can also gate on top_confidence in one line instead of parsing the whole result set.

5. Boundaries worth knowing before you wire this up

6. The five-minute setup loop

Step 1
Fetch /openapi.json, walk it with the snippet above, and write the operation list to a file you can grep. That file is your map.
Step 2
Import the Postman collection, set base_url, and add your key at the collection level.
Step 3
Smoke-test with two cheap anonymous calls — GET /api/health (returns {"ok":true}) and POST /api/uuid with {"version":4,"count":1}.
Step 4
Re-run /api/tools/stats before you ship and store the output next to your integration. When the catalog grows, the diff tells you which new tools you haven't wired up yet.

That last step is the one people skip. The discovery surfaces are only valuable if you re-read them — a four-line stats check in CI catches new tools and renamed ids before they turn into 404s in production.

Explore the API you just mapped

Browse the full endpoint reference, or open the toolbox and run any of the 104 catalog tools from the browser.

Open toolbox

Related reading: One API key, 70+ tools for the authentication flow that the Postman placeholders stand in for, structured scraping with CSS selectors for the request/response shapes these endpoints share, and the pipeline builder for chaining discovered tools into one call.