Akeem Jenkins - Security & Privacy Professional

As AI agents become increasingly capable of discovering and consuming APIs autonomously, we need to rethink how we design our web services. Traditional API documentation, meant for human developers, isn't enough anymore. Here's how I built an architecture specifically designed for AI discovery and consumption.

The Problem

AI agents like ChatGPT, Claude, and emerging autonomous systems need to:

Discover your API without human intervention
Understand how to use it appropriately and safely
Integrate with your endpoints seamlessly

But most APIs today are built with human developers in mind, not AI agents. I decided to change that.

My Three-Layer Architecture

Layer 1: The Discovery Layer

Implementation: .well-known/ai-plugin.json

I started with OpenAI's plugin specification, placing a manifest file at the standard .well-known endpoint. This lets AI agents discover my API the same way browsers discover security policies or RSS feeds.

The manifest includes:

Service metadata (name, description, version)
Authentication requirements
Links to my OpenAPI spec
Pointers to my AI-specific guidance

Why it matters: AI agents can now find and understand your API without requiring a human to write custom integration code.

Layer 2: The Guidance Layer

Implementation: ai-content-guide.json

This is where I go beyond traditional API docs. The guidance layer provides AI-specific instructions:

Usage policies: What the API should and shouldn't be used for
Rate limiting expectations: How agents should pace their requests
Data handling rules: Privacy and data retention guidelines
Output formatting: How to present location data to end users
Error handling: What to do when things go wrong

Think of it as "terms of service" and "best practices" rolled into one machine-readable format.

Why it matters: AI agents need context that goes beyond "here's how to call this endpoint." They need to understand intent, limitations, and ethical boundaries.

Layer 3: The API Layer

Implementation: OpenAPI 3.0 specification with 4 focused endpoints

I kept the API surface intentionally small:

Location search: Find places by query
Location details: Get comprehensive data about a specific location
Nearby search: Discover locations within a radius
Category browse: Filter locations by type

Each endpoint is fully documented with:

Request/response schemas
Example payloads
Error codes and meanings
Parameter validation rules

Why it matters: A clean, well-documented API is easier for AI agents to reason about and less prone to integration errors.

Testing in the Real World: What I Learned from Claude, ChatGPT, and Gemini

Here's where things got really interesting. I didn't just build this architecture and hope it worked. I actually sat down with Claude, ChatGPT, and Gemini and had them test my API directly.

The process was simple but eye-opening: I gave each AI the link to my .well-known/ai-plugin.json file and asked them to explore my API, make requests, and tell me about their experience.

ChatGPT's Approach: The Eager Explorer

ChatGPT dove right in. I gave it the link and said, "Can you explore this API and tell me what you find?"

It immediately fetched my plugin manifest, parsed the OpenAPI spec, and started making test queries. But here's what surprised me: ChatGPT tried to use all four endpoints in rapid succession without reading the guidance layer first. It was like a kid in a candy store, enthusiastic but not always following the instructions.

The lesson: I realized my guidance layer needed to be referenced directly in the OpenAPI spec itself, not just linked from the manifest. AI agents sometimes skip straight to the endpoints without reading the "terms of use."

Claude's Approach: The Careful Analyst

When I gave Claude the same task, it took a completely different approach. It read through the entire guidance layer before making a single API call. It asked clarifying questions about rate limits and wanted to understand the intended use cases before proceeding.

Claude actually caught an ambiguity in my error handling documentation. My guide said "retry on 429 errors," but didn't specify the backoff strategy. Claude asked, "Should I use exponential backoff? What's the recommended wait time?" That gap in my documentation would have caused issues for any AI agent trying to be respectful of my rate limits.

The lesson: Different AI models have different "personalities" when consuming APIs. Claude's cautious approach revealed gaps that ChatGPT's enthusiasm glossed over.

Gemini's Approach: The Pattern Matcher

Gemini surprised me the most. It looked at my location search endpoint and immediately started asking about edge cases I hadn't documented. "What happens if I search for a location that spans multiple time zones? How do you handle coordinates near the international date line?"

These were scenarios I knew my API handled, but hadn't explicitly documented anywhere. Gemini was pattern-matching against common API pitfalls and wanted confirmation that I'd thought through these cases.

The lesson: AI agents are incredibly good at finding documentation gaps by reasoning about what should be there, even if they haven't encountered an error yet.

The Meta-Learning Process

By having these AI models actually use my API in real-time conversations, I learned something crucial: you can use AI agents as free QA testers for your AI-native architecture.

Here's my testing workflow now:

Build or update a feature
Give the API link to multiple AI models
Ask them to explore and report issues
Watch how they interpret your documentation
Identify patterns in their confusion or misuse
Iterate on the guidance layer

This process revealed critical patterns:

Pattern 1: AI agents assume consistency

If your first endpoint returns data in one format, they'll assume all endpoints follow the same pattern. When my location details endpoint had a slightly different response structure, all three AI models stumbled initially.

Pattern 2: Error messages are teaching moments

The error messages I returned became documentation in themselves. When Claude hit a validation error, it read my error message and adjusted its next request accordingly. I started writing error messages specifically for AI consumption, with machine-readable error codes and suggested fixes.

Pattern 3: Examples are worth a thousand words

ChatGPT and Gemini both performed dramatically better after I added example request/response pairs to every endpoint. They pattern-matched against the examples rather than trying to interpret my prose documentation.

How This Changes Everything

Understanding how AI agents actually consume your API changes your entire development mindset. You're not just building for developers anymore. You're building for machines that will interpret your work and present it to millions of end users.

When I give my API link to ChatGPT and watch it successfully help a user find nearby restaurants, I'm seeing my data flow through an AI intermediary. The better my API speaks "AI language," the better the end-user experience becomes.

This isn't theoretical. Right now, you can open a conversation with any major AI model, give it a link to your API documentation, and watch it try to use your service. The question is: will it succeed, or will it fumble through unclear documentation and poor error messages?

Key Lessons Learned

1. AI agents are literal

Unlike human developers who can infer context, AI agents need explicit instructions. Vague documentation leads to creative but incorrect API usage.

2. Versioning is critical

When an AI agent learns your API, it caches that knowledge. Breaking changes can break thousands of agent integrations silently. Semantic versioning and deprecation notices in your discovery layer are essential.

3. Rate limiting needs rethinking

Traditional per-IP rate limiting doesn't work well when a single AI service makes requests on behalf of millions of users. We need per-agent authentication and quotas.

4. Machine-readable guidance is non-negotiable

Human-readable API docs aren't enough. AI agents need structured, programmatic access to your usage policies and best practices. The guidance layer is just as important as the API specification itself.

5. Test with actual AI agents

Don't guess how AI will use your API. Sit down with Claude, ChatGPT, and Gemini and watch them try. Their approaches will reveal blind spots you never considered.

What's Next

I'm continuing to refine this architecture and exploring:

Agent authentication tokens for better access control
Real-time feedback mechanisms so agents can report integration issues
A playground environment where new agents can test without affecting production
Semantic versioning in the guidance layer itself
Enhanced error responses that help agents self-correct

The Bigger Picture

Building AI-native APIs isn't just about adding a manifest file. It's about recognizing that AI agents are a fundamentally new category of API consumer, one that requires thoughtful architecture, clear communication, and explicit guidance at every layer.

As we move into an era where agents might generate more API traffic than human developers, the APIs that thrive will be those designed from the ground up for AI discovery and consumption.

And here's the beautiful part: you can start testing this today. Open a chat with an AI model, give it your API link, and see what happens. You'll learn more in 30 minutes of conversation than in weeks of traditional user testing.