What is API.md?

API.md meaning

`API.md` is a lightweight, Markdown-based API reference. It documents the endpoints a service exposes, the data they accept and return, and how to authenticate. For small or internal APIs, a single API.md is often enough, and because it lives in the repository it stays close to the code and versions with it.

What to document

• Each endpoint, method, and path
• Required and optional parameters
• Request and response examples
• Status codes and error formats
• Authentication and rate limits

# API

## GET /users/{id}
Returns a single user.

**Response 200**
```json
{ "id": 1, "name": "Alice" }
```

## Auth
Send `Authorization: Bearer <token>`.

API.md vs OpenAPI

For large or public APIs, a machine-readable spec like OpenAPI is better because it powers generated clients and interactive docs. API.md is the simpler choice for small services, internal tools, or a quick human-readable reference. Many projects start with API.md and adopt OpenAPI as the API grows.

How AI tools use API.md

AI coding agents read API.md to generate correct integration code, write client functions, and answer questions about endpoints and payloads. Clear examples in API.md reduce wrong guesses about field names, methods, and auth, which makes generated code work on the first try more often. It complements a clear README.md and DESIGN.md.

Edit API.md with a preview

API docs rely on code blocks and tables, so a live preview helps. Draft API.md in the Markdown Docs online editor, or download Markdown Docs to edit it on Windows. See more common .md files for AI projects.

Related references

• OpenAPI Specification for machine-readable API specs.
• GitHub Markdown syntax for formatting code and tables.