APIs were not designed to understand intent.
They were designed to expose capability.
A client connects. The system responds with endpoints, schemas, and methods. From there, the burden shifts entirely to the client: learn what exists, understand how it fits together, orchestrate the correct sequence of calls, handle edge cases, and reconstruct meaning from low-level operations.
This model works, but it is procedural, brittle, and inefficient. It assumes that the caller already understands the system.
The Gap
There are two persistent problems.
1. Discovery Gap
Clients do not know what is possible or where to begin.
2. Execution Gap
Clients know what they want, but not how to achieve it.
Human engineers bridge this gap manually. They observe how clients use the system. They notice repeated patterns. They introduce new abstractions: wrappers, workflows, helper endpoints.
Over time, the API evolves toward intent.
But this process is slow, inconsistent, and reactive.
A Different Model
What if the system participated in this process directly?
What if an API could:
- reveal itself through interaction
- interpret objectives
- map intent to capability
- compose workflows when none exist
- adapt its interface in response to use
Not by replacing its core logic, but by shaping how that logic is accessed.
Two Complementary Patterns
This model emerges from two interacting ideas.
Progressive Capability
The system should not expose everything at once.
It should be discoverable through use.
A client connects and receives a high-level map: domains, resources, capability families.
As the client explores, the system reveals related operations, adjacent capabilities, and deeper context.
The interface is not static. It is progressively disclosed.
Intent Responsiveness
The system should not require the client to translate intent into procedure.
A client should be able to say:
“Here is what I want to accomplish.”
The system responds by identifying relevant capabilities, selecting existing workflows when available, and composing new workflows when necessary.
If no suitable abstraction exists, the system constructs one from trusted primitives and exposes it as a usable function.
The system does not just execute. It aligns itself to the objective.
An Example
A client connects to a commerce system.
Instead of a full endpoint catalog, it sees:
orders
customers
shipments
refundsThe client declares:
“Resolve delayed orders for premium customers and notify them.”
The system evaluates:
- delayed shipments
- customer tier
- refund eligibility
- communication channels
If no predefined workflow exists, it composes one:
resolve_delayed_premium_orders(order_id)Derived from:
- search_orders
- identify_delays
- filter_premium_customers
- evaluate_refund_options
- generate_notification
- send_message
The function is not invented arbitrarily. It is composed from existing, trusted capabilities.
It is inspectable. It is explainable. It can be reused.
Design Philosophy
This approach follows a broader philosophy of system design:
- interaction
- discovered
- interface
- transient
- behavior
- emergent
- signal
- continuous
- control
- system-led
interaction: discovered
Capabilities are revealed through context, not memorized in advance.
interface: transient
The visible surface adapts based on state, intent, and exploration.
behavior: emergent
Higher-level functionality is composed from simpler primitives.
signal: continuous
The system is always interpreting input and refining its response.
control: system-led
The system guides the interaction, reducing procedural burden on the client.
What This Is Not
This is not a replacement for existing APIs.
It does not discard REST, RPC, or GraphQL.
It builds on them.
The underlying primitives remain stable, explicit, and governed.
What changes is the layer above: how capability is exposed, how intent is interpreted, and how workflows are formed.
Why Now
This pattern becomes more relevant as systems interact with AI agents.
Agents do not struggle with syntax. They struggle with mapping intent to action.
A system that can expose capability clearly, guide discovery, and compose workflows becomes significantly more usable, not just for machines, but for humans.
Working Definition
An Adaptive Capability API is a system in which:
- capabilities are progressively discoverable
- intent is treated as a first-class input
- workflows are selected or composed dynamically
- new abstractions emerge from trusted primitives
- the interface adapts without compromising core stability
Status
This is an early exploration.
The goal is not completeness, but clarity.
If this resonates, it is likely because the pattern already exists, informally, in how systems evolve.
This is an attempt to make it explicit.