AGENTS.md for API Providers: Teach AI Coding Tools to Use Your API

About the author: Brett Calloway is a Developer Advocate and AI Integration Specialist with 12 years of experience in API development. He has led developer relations at two Series B SaaS companies and spoken at PyCon and JSConf on building context-rich AI agents using Model Context Protocol.

Every API SDK gets used wrong by AI coding tools the first time. A developer opens Cursor, Claude Code, or Windsurf, types "add daily horoscopes to my app," and the model invents a request body that does not exist, a header that has not been valid since 2019, or an endpoint that returns a 404. The model is guessing because no source of truth lives next to the code it is about to write. AGENTS.md is the fix: a small Markdown file at the root of your SDK that every modern AI coding tool reads first. This post shows what to put in one, with the real file we ship in @roxyapi/sdk as the worked example.

Why AGENTS.md exists and what it actually is

AGENTS.md is a plain Markdown file placed at the root of a repository or package. It tells AI coding tools how to use the code in that package. The standard originated at OpenAI, and per our SDK reference it is now used by 60,000+ open-source projects and read automatically by GitHub Copilot, Windsurf, Cline, Aider, and Claude Code. No plugin. No registry. No config flag.

That last point is what API providers usually miss. AGENTS.md is not a README. README.md is for a human skimming GitHub trying to decide if your library is worth installing. AGENTS.md is for a machine deciding which method to call. A README that buries the auth header in paragraph six is fine for humans. The same content in AGENTS.md produces hours of broken code generated by AI assistants that gave up reading after paragraph two.

Ready to test this against a real multi-domain API? Pick up an API key and point your AI coding tool at our API reference to see how AGENTS.md plus a typed SDK closes the gap between "the model wrote code" and "the code runs."

What goes in AGENTS.md and what does not

The file is short on purpose. AI coding tools read it before every meaningful generation. Bury the install command on line 200 and the tool may truncate before it gets there. The whole document should fit in a single context pass and answer: how to install, how to authenticate, what the request shape is, what an error looks like, and what changes between domains.

Sections that change behavior most: auth, endpoint path conventions, request and response shape (especially POST body fields), and the error contract. These four are where models hallucinate hardest without grounding. Marketing copy, release notes, contributor guides, and architecture diagrams do not belong here. The rule: if a sentence does not change the code the model writes, cut it.

The shipped file, annotated section by section

Here is the actual content from AGENTS.md in the @roxyapi/sdk TypeScript package, broken into the blocks that matter. This is the file Copilot and Claude Code read when a developer asks an AI tool to integrate Roxy.

Identity block

# @roxyapi/sdk Agent Guide

TypeScript SDK for RoxyAPI. Multi-domain spiritual and metaphysical
intelligence API. One API key, fully typed, zero runtime dependencies.

> Before writing any code with this SDK, read `docs/llms-full.txt` in
> this package for the complete method reference with examples.

The first paragraph tells the model what the package is in one sentence. The blockquote points to a deeper reference bundled in the npm package, so the agent can pull long-tail method docs from node_modules/ without internet access. This pattern keeps AGENTS.md small enough to stay inside a single context pass while giving the agent a clean path to deeper detail when it needs method-level examples. Bundle a long-form reference next to AGENTS.md and link them.

Install and initialize

## Install and initialize

npm install @roxyapi/sdk

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

This block answers two questions the model must resolve before any other code: which install command, and which factory call. We use createRoxy, not new Roxy(). Spelling that out kills the most common hallucination: new SDKName() syntax inherited from older Java-style SDKs.

Domains table

## Domains

| Namespace | Endpoints | What it covers |
|-----------|-----------|----------------|
| roxy.astrology | 22 | Western astrology: natal charts, horoscopes, transits |
| roxy.vedicAstrology | 42 | Vedic, Jyotish, KP, panchang, doshas, yogas |
| roxy.tarot | 10 | Spreads, daily pulls, yes/no, Celtic Cross |
| roxy.numerology | 16 | Life path, expression, soul urge, personal year |
| roxy.iching | 9 | Hexagrams, trigrams, coin casting, daily readings |

A domain table maps namespaces to endpoint counts and one-line descriptions. AI tools use this to decide whether your SDK can solve the request, and which namespace to autocomplete inside. Counts auto-sync from the OpenAPI spec at release time so the table cannot drift.

Critical patterns

### GET endpoints: use `path` for URL parameters

const { data } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

### POST endpoints: use `body` for request data

const { data } = await roxy.astrology.generateNatalChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude: 28.6139,
    longitude: 77.209,
  },
});

This is the highest information density section in the file. It tells the model the parameter shape contract, the thing models hallucinate hardest. Every method takes one of { path }, { body }, or { query }. Never positional arguments. Stating that explicitly removes the entire class of "I tried to call it like axios" errors.

Error contract

### Error handling

All errors return { error: string, code: string }. The error field is
human-readable. The code field is machine-readable and stable.

| Status | Code | When |
|--------|------|------|
| 400 | validation_error | Missing or invalid parameters |
| 401 | api_key_required | No API key provided |
| 401 | invalid_api_key | Key format invalid or tampered |
| 429 | rate_limit_exceeded | Monthly quota reached |
| 500 | internal_error | Server error |

Without this table, AI tools generate if (response.status === 401) { ... } branches based on whatever the model saw most often in training. With it, the model writes switch (error.code) against the stable codes, which is the integration pattern your support team wants in production.

Gotchas

## Gotchas

- Parameters are objects, not positional. Always { path }, { body }, or { query }.
- Do not guess method names. Type roxy.domain. and let autocomplete show methods.
- Do not use raw fetch. The SDK handles auth, base URL, and typed responses.
- Do not expose API keys client-side. Server code only.
- Date format is YYYY-MM-DD, time is HH:MM:SS. Both strings.
- data and error are mutually exclusive. If error is set, data is undefined.

A bulleted "do not" list catches the small mistakes that sum to most broken integrations. Models respect "do not" rules more reliably than "always do" rules, so phrase them as anti-patterns when possible.

How AGENTS.md differs from README.md in intent

A README answers "should I use this." It carries badges, a logo, a hero paragraph, and a learn-more link. Conversion is the job.

AGENTS.md answers "how do I call this correctly right now." It carries the install command, the auth contract, the parameter shape, the error format, and the gotchas. It must be short, literal, and contain runnable examples in every section. Correctness is the job. Both files can live at the package root without conflict. Humans skim README. Machines parse AGENTS.md.

Useful test: print both side by side. If a reader cannot tell within five seconds which is for the human and which is for the machine, the AGENTS.md is too narrative. Cut prose, add tables, add code blocks, add "do not" rules.

A minimum viable AGENTS.md template for API companies

Below is a copy-paste-ready skeleton tuned for an API company shipping an SDK, not a framework or CLI. Replace the bracketed placeholders, ship the file at the root of your SDK package, list it in your package.json files field, and your customers AI coding tools will start using your API correctly within hours of the next release.

# @your-org/sdk Agent Guide

[One sentence: what your API does and what makes the SDK different.]

## Install

npm install @your-org/sdk

import { createClient } from '@your-org/sdk';
const client = createClient(process.env.YOUR_API_KEY!);

## Auth

Pass the API key once at client creation. The SDK sends it as the
`X-API-Key` header on every request. Never expose the key client-side.
Server-side code only (Node, Bun, Deno, edge runtimes).

## Endpoints

| Namespace | Methods | Covers |
|-----------|---------|--------|
| client.users | 8 | User CRUD and profile |
| client.billing | 5 | Subscriptions and invoices |
| client.events | 3 | Webhook event listing |

Type client. to see all namespaces. Type client.users. to see all methods.

## Request shape

Every method takes one params object with named fields:

await client.users.create({
  body: { email: '[email protected]', name: 'Alice' },
});
await client.users.get({
  path: { id: 'usr_123' },
});
await client.events.list({
  query: { limit: 50 },
});

Never use positional arguments. Never call raw fetch.

## Errors

All errors return { error: string, code: string }.

| Status | Code | When |
|--------|------|------|
| 400 | validation_error | Bad request body or query |
| 401 | invalid_api_key | Missing or wrong key |
| 404 | not_found | Resource does not exist |
| 429 | rate_limit_exceeded | Quota hit |
| 500 | internal_error | Server fault |

Switch on code, not on error message text.

## Rate limits

Default tier: 60 requests per minute, 100,000 per month. Limits returned
in X-RateLimit-Remaining and X-RateLimit-Reset response headers.

## Examples

[2 to 4 of the most common end-to-end tasks. Each one runnable.]

## Gotchas

- [Top 3 to 6 traps that cause first-integration failure.]

Six sections, tables where useful, runnable examples in every block. Do not pad it. The file gets stronger as you remove words.

What not to put in AGENTS.md

The temptation is to make AGENTS.md the new README and stuff everything in. Resist it. The following content consumes context budget without changing generated code:

• Marketing copy. "Trusted by thousands of developers" is invisible to a model deciding which method to call.
• Release notes and changelogs. Version history belongs in CHANGELOG.md.
• Long narrative explainers. Tutorials live on a docs site. AGENTS.md is reference, not pedagogy.
• Internal implementation details. Library names, file paths, and build tools are noise to a consumer of your SDK.
• Logos, screenshots, and badges. Models cannot use them. Reserve images for the README.
• Contributor guidelines. PR templates and code style live in CONTRIBUTING.md.

For broader knowledge your AI customers need, ship a separate AI prompts page with use-case prompts, and a starters catalog with reference apps. AGENTS.md stays surgical.

Frequently Asked Questions

Q: What is the difference between AGENTS.md and llms.txt? A: AGENTS.md lives inside a repository or package and teaches AI coding tools how to use that specific code. llms.txt lives at the root of a website and tells web-crawling AI systems where to find your structured documentation. AGENTS.md is for the IDE agent, llms.txt is for the chatbot answering a search query. Ship both.

Q: Does AGENTS.md work with GitHub Copilot, Cursor, Claude Code, and Windsurf without configuration? A: Yes. All four read AGENTS.md automatically when present at the root of an open project or installed package. No plugin, no setting. Cursor and Claude Code also read project-level rules files like CLAUDE.md and .cursorrules, which are complementary, not a replacement.

Q: Should AGENTS.md live in the SDK package or the API server repository? A: Put it in the SDK package every time. Developers install your SDK from npm or PyPI and the file lands in node_modules/@your-org/sdk/AGENTS.md, where their agent reads it without an internet round trip. AGENTS.md in your server repo only helps contributors, not customers.

Q: How long should AGENTS.md be? A: Short enough to read in a single agent context pass. For a SaaS API, roughly 200 to 400 lines of Markdown. Above 500 lines, split the long-tail method reference into a separate docs/llms-full.txt.

Q: How do I keep AGENTS.md in sync with my API as it evolves? A: Generate the moving parts, like the namespace and endpoint table, from your OpenAPI spec at release time. Hand-write only the install, auth, error contract, and gotchas sections, which change rarely.

Conclusion

AGENTS.md is the smallest artifact that produces the largest improvement in how AI coding tools call your API. Ship one today, keep it short, lean on tables and runnable examples, and the next developer who opens Cursor or Claude Code with your package installed will get working code on the first try. The live file is in @roxyapi/sdk, and the pricing page gets you a key for the multi-domain API it documents.