explore-api

Explore an API

Step 1: Get the high-level overview

Call parse to understand the API at a glance:

{"spec": {"file": "<path>"}}

Report:

• API title and version
• OAS version (2.0, 3.0, 3.1)
• Number of paths, operations, and schemas
• Server URLs
• Tags (these organize operations into groups)

Handling Large APIs

If parse shows 100+ operations or 200+ schemas, adjust your strategy:

• ⚠️ Filter first, page second. Use tag, method, or path filters on walk tools rather than paging through all results.
• ✅ Use component: true for schemas. Without it, walk_schemas returns ALL schemas including inline ones (request bodies, response wrappers, etc.), which can be 3-5x the number of named component schemas. Start with component: true to see the data model, then omit it only when hunting for inline schema issues.
• ✅ Walk by tag. If the API has tags, use them. walk_operations with tag filter is the fastest way to understand a specific area.
• ❌ Avoid detail: true on unfiltered walks. Full operation objects can be very large. Get summaries first, then drill into specific operations.

Step 2: List endpoints

Call walk_operations to list all API endpoints:

{"spec": {"file": "<path>"}}

Present them grouped by tag or by path prefix. For each operation show the method, path, and summary.

For a quick overview of a large API, use group_by first:

{"spec": {"file": "<path>"}, "group_by": "tag"}

This returns operation counts per tag — the fastest way to understand API scope.

{"spec": {"file": "<path>"}, "group_by": "method"}

This shows the HTTP method distribution (e.g., 60% GET, 25% POST, etc.).

⚠️ If the API is large (more endpoints than the default page of 100), prefer filtering over paging:

{"spec": {"file": "<path>"}, "tag": "Users"}

{"spec": {"file": "<path>"}, "path": "/users/*"}

For deeply nested APIs, use ** to match across path depths: