Most search APIs follow a familiar pattern: you send a query, you get back a structured list of results. Each result is a record — fields, values, maybe some nested objects. It's designed to be consumed by code that knows what it's looking for and knows how to render it.
Recently we built a new search endpoint with a different consumer in mind: an AI assistant. The response it needs isn't a result set. It's something the assistant can reason about and articulate in natural language.
Why the response shape matters
When a UI component consumes a search API, it knows exactly which fields to read. The price goes in this column. The departure time goes there. Any ambiguity in the response structure is a bug to be fixed in the mapping layer.
When an AI assistant consumes a search API, the situation is more interesting. The assistant has to understand the results, decide what's relevant to say about them, and express that in a coherent response to the user. If you hand it a dense structured result set, it can technically work with it — but you're asking it to do a lot of implicit inference about what the data means and how the fields relate to each other.
A response designed for conversational consumption makes that easier. You surface the information the assistant actually needs, organised in a way that corresponds to how a human would think about it, rather than in the schema optimised for data storage or rendering. The distinction is between a response that answers "what are these records?" and one that answers "what should I know about these options?"
Building it without duplicating the core logic
The practical challenge is that the new endpoint still needs to run the same underlying search — the same pricing logic, the same availability checks, the same filtering. You don't want two separate implementations of that. What changes is the shape of the output, not the logic that produces it.
The implementation threads a new output path through the existing search pipeline: the core logic runs as before, but there's a step at the end that transforms the results into the conversational response format before returning them. This keeps the business logic in one place while allowing the presentation layer to vary by consumer type.
It's a pattern that shows up a lot in API design — the same underlying operation exposed through different interfaces for different consumers. The tricky part is getting the boundaries right so that the shared logic stays coherent and the per-consumer transformation doesn't start leaking back into it.
Conversational APIs as a distinct design problem
There's a broader point worth making here. As AI assistants become a first-class consumer of backend APIs, the assumptions baked into standard API design start to matter in different ways.
Traditional API design treats the consumer as code: deterministic, explicit, able to handle any well-formed response. AI consumers are more like people: they interpret, infer, and sometimes get confused by responses that are technically complete but not easy to reason about. Designing for them means thinking about meaning and context, not just schema validity.
That's a different skill than standard API design, and I suspect it's going to become more important as more systems start exposing AI-facing interfaces alongside their traditional ones.