This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content
Proto — A Small API Design Research Agent
We're all building software faster now.
With AI coding tools, it's easy to describe something, get working code, fix a few things, and move on. I do this too.
But when we're moving fast, we often take the easiest path. API design is a good example. There are standards, guidelines, HTTP semantics, and API documentation available for free, but realistically, we're not going through the documentation for every endpoint or every pull request.
So I wanted to try something small.
What if an agent could do that research for us before we make the decision?
That's Proto.
What I Built
Proto is a small terminal-based API design research agent.
You can ask it questions like:
Should I use PUT or PATCH when updating a user's email?
or:
Is POST /getUser a reasonable API design?
or even give it an actual curl request:
proto review 'curl -X POST https://api.example.com/getUser -d "{\"id\":\"123\"}"'
Instead of immediately answering from the LLM's existing knowledge, Proto first creates a small research plan.
For example:
PUT semantics
PATCH semantics
Partial updates
Idempotency
POST semantics
It then queries a Sanity Knowledge Base through Sanity Context MCP, collects the relevant source-linked material, and gives that evidence to the LLM for reasoning.
The basic flow is:
Question
↓
Research plan
↓
Sanity Context MCP
↓
Knowledge Base
↓
Retrieved evidence
↓
OpenRouter reasoning
↓
Answer + sources
The goal was deliberately small: make researching an API decision easier.
How I Used Sanity
Sanity is the knowledge layer behind Proto.
I created a Knowledge Base containing API-related documentation and standards, including HTTP semantics, REST/API design, Google AIPs, resource naming, CRUD operations, status codes, error handling, idempotency, pagination, authentication, versioning, and other API guidance.
Proto connects to that Knowledge Base through Sanity Context MCP.
The interesting part isn't just that Sanity contains the documents. Proto uses the content as part of a research process.
For example, if I ask:
I need to update only a user's email address.
Should my API use PUT, PATCH, or POST?
Proto doesn't just search for the words "email" or "PATCH."
It breaks the problem down into questions such as:
What are the semantics of PUT?
What are the semantics of PATCH?
How are partial updates represented?
What are the idempotency implications?
What guidance applies to updating a single resource field?
The retrieved content stays connected to its sources, and Proto reasons across the evidence before producing the answer.
That was the part I wanted to explore with this challenge:
problem
↓
research
↓
real content
↓
evidence
↓
reasoning
rather than simply:
keyword search → LLM summary
Proto is also instructed not to invent citations or treat every unusual API design as automatically wrong. It tries to separate documented guidance from its own interpretation and from normal design trade-offs.
Demo
Demo:
The demo shows Proto researching an API design question through Sanity Context and then reviewing an actual request.
The terminal also shows the different stages of the agent so it's clear when Proto is researching versus reasoning over the retrieved content.
Code
Repository:
Proto — API Design Research Agent
"Build anything that needs an answer it can't afford to get wrong."
APIs are public contracts. Once an endpoint is published to mobile apps, SDKs, and third-party developers, design mistakes are prohibitively expensive to fix. Proto is an AI API design research agent powered by Sanity Context MCP. Instead of relying purely on an LLM's pretrained memory or hallucinations, Proto dynamically formulates a research plan, queries the Sanity Knowledge Base (containing authoritative Google AIPs, RFC 9110 HTTP semantics, and Zalando guidelines), and synthesizes source-grounded answers directly in your terminal.
📖 Full Technical Documentation: See DOCUMENTATION.md for detailed Phase 1 & Phase 2 architecture, MCP tool orchestration, and prompt engineering.
USER
│
▼
Natural language (or curl)
│
▼
┌──────────────┐
│ PROTO │
│ Agent │
└──────┬───────┘
│
▼
Understand question
│
▼
Research plan
│
▼
Sanity Context MCP
│
▼
Knowledge BaseProto is written in Go and intentionally stays small.
There is no frontend, database, vector database, or custom RAG system.
The pieces are simply:
Proto CLI
↓
Go Agent
├── Sanity Context MCP
└── OpenRouter
↓
Source-backed answer
Sanity Project Details
Sanity Org ID: od9ex4ma5 (Knowledge Base ID: kbzijGjZZuE3)
Dataset / Project: https://www.sanity.io/manage/organizations/od9ex4ma5/context
The Sanity project contains the Knowledge Base and the source material Proto uses during its research.
Agent Session
Proto — API Design Research Agent
The session shows the development of Proto and the evolution from an initial curl reviewer into a broader API design research agent.
Final Thoughts
Proto is a small change with a simple intention.
When we're moving fast, it's easy to take the first solution that works. I wanted to see if an agent could make it a little easier to pause, look at the actual documentation and standards, and make a more informed choice.
That's it.
Not replacing developers. Not replacing documentation.
Just making the better path a little easier to take.
Top comments (0)