Proposal: Adding /do-list and /do/ Endpoints to NLWeb #350
Description
Context
NLWeb today has two core primitives:
- /who → Directory of authorities for a given capability
- /ask → Natural language interface for querying structured knowledge
This is a major step toward a natural-language compatible web. But there’s a missing piece: interaction. Right now, NLWeb is excellent at asking and finding, but not at doing.
The Proposal
Add two new REST API endpoints to NLWeb: /do-list and /do
1. GET /do-list
Returns a list of actions a website is capable of performing.
Example response:
{
"capabilities": [
{
"action": "place-order",
"description": "Submit a new order for a product",
"inputSchema": {
"productId": "string",
"quantity": "number",
"paymentMethod": "string"
}
},
{
"action": "check-availability",
"description": "Check inventory for a given product",
"inputSchema": {
"productId": "string"
}
},
{
"action": "book-reservation",
"description": "Reserve a table or service slot",
"inputSchema": {
"date": "string",
"time": "string",
"partySize": "number"
}
}
]
}2. POST /do
Executes specific actions supported in the /do-list.
The action is defined in the query argument, with an optional argument, site, specifying subdomain if any,
Example request:
POST /do
Content-Type: application/json
{
"query": "Order two green tea",
"site": "https://green-tea-nicaragua.com"
}The request is fulfilled by a series of requests to the endpoints defined in /do-list:
POST /do/place-order
Content-Type: application/json
{
"productId": "green-tea-nicaragua-001",
"quantity": 2,
"paymentMethod": "${credit-card}"
}Example response:
{
"status": "success",
"orderId": "ORD-12345",
"estimatedDelivery": "2025-09-20"
}Why This Matters
Completes the NLWeb primitive set: not just who and ask, but also do.
Scales inclusion: Websites get to partake in the world of Agentic NL Web without rewriting their stack.
Improves determinism: bounded, closed-ended actions reduce LLM hallucination and increase reliability.
Shifts focus to outcomes: an outcome-driven web aligns with user intent, instead of optimizing for blue links or GEO hacks.
Conclusion
Adding /do-list and /do brings NLWeb closer to its vision: a web that is universally natural-language compatible, outcome-driven, and accessible to all participants, not just the most technically advanced.