ApiPad: From guessing correct apis to semntaically determining them.

ApiPAD came from a very simple problem. At one point we had more than 100 APIs and WebSocket endpoints spread across multiple teams. Different teams named things differently, many APIs overlapped in functionality, and some endpoints looked completely unrelated despite doing almost the same thing. As the number of tools grew, agent accuracy started falling apart. In some workflows we were seeing tool selection accuracy drop close to 30% because the agents simply didn't know what to use.

The Obvious Approach

The obvious solution was to let the LLM search API definitions directly.

The problem is that users do not think in API URLs.

Nobody asks:

Use /api/v2/trades/limit

Instead they ask:

Place a BTC limit order using the current market price.

Users describe outcomes, not implementation details. Yet we were forcing the model to search implementation details and somehow infer the desired outcome from them.

The Contrarian Idea

Instead of embedding API URLs, we embedded intent.

For every API we generated questions, use cases, and capability descriptions.

An endpoint might look like this:

{
  "endpoint": "/api/v2/trades/limit",

  "questions": [
    "how to place limit order",
    "buy bitcoin at target price",
    "create pending order"
  ],

  "usecases": [
    "placing limit order",
    "placing limit order with custom price",
    "automated trading workflows"
  ]
}

The questions and use cases were embedded into a vector database while the endpoint itself was stored as metadata.

Now when an LLM searched for:

placing limit order with current price of BTC

it wasn't matching against URLs. It was matching against intent. Semantic search would retrieve the relevant capability, and the attached metadata would provide the actual API endpoint.

The Pipeline

The entire pipeline was surprisingly simple and mostly a one-time setup process.

Once indexed, agents could retrieve APIs based on capabilities rather than endpoint names.

Keeping the Index Updated

The next challenge was keeping the index synchronized with OpenAPI changes.

We used two approaches.

Hash-Based Detection

For deployments, GitHub Actions generated hashes of OpenAPI specifications. If a hash changed, the indexing pipeline was triggered automatically.

Event-Driven Updates

For faster propagation, OpenAPI updates could also emit events.

Whenever a specification changed:

1. An event triggered the pipeline.
2. The latest OpenAPI definitions were pulled from GitHub.
3. Questions and use cases were regenerated.
4. Embeddings were rebuilt.
5. The index was updated.

This ensured ApiPAD stayed synchronized without requiring manual intervention.

The Realization

The interesting part wasn't vector search, embeddings, or retrieval. The realization was much simpler:

APIs are implementation details.

Capabilities are what agents actually search for.

Humans think in outcomes. Agents think in outcomes. API URLs are merely one possible implementation of those outcomes. Once we stopped indexing endpoints and started indexing capabilities, tool retrieval became significantly more reliable.