AI Engineering from Scratch

API and MCP documentation

Search AI Engineering from Scratch lessons and projects, then read their original Markdown from your own tools. The public API and hosted MCP server are read-only. No API key or login is required.

Read the complete integration guide in Markdown, including request examples, errors, authentication, transport behavior, versioning, and release instructions.

Public REST API

• /api/v1/catalog: search with q, filter by kind, and page with limit and offset.
• /api/v1/resource: supply a returned path to retrieve the original Markdown and source links.
• /api/v1/markdown: request a navigation page as HTML or Markdown.
• OpenAPI 3.1 specification: operation IDs, typed inputs, response schemas, and errors for tool integration.

Authentication, errors, and quotas

No credentials are needed for public content. There are no write endpoints, accounts, or webhooks. The service does not store learner progress or execute lesson code. Do not send private learner data.

REST reads support GET and HEAD. Errors use RFC 9457 problem details with a stable code, explanatory detail, and recovery hint. Missing resources return a real 404.

Catalog, resource, and MCP handlers each enforce 120 requests per minute per client IP on each running function instance. Clients sharing an IP share a quota. RateLimit-Policy and RateLimit describe this local window; application 429 responses include Retry-After. Cold starts and scaled instances have separate counters. See the full guide for quota scope and platform error handling.

Versioning and Markdown

REST v1 uses /api/v1/ and X-API-Version: 1. Breaking changes require a new major path. Any retirement will be announced at least 90 days ahead with a migration guide and Deprecation and Sunset headers. No v1 operation is currently deprecated.

The homepage and public navigation pages, including their .html URLs, return Markdown when Accept names text/markdown. HTML remains the browser default. Both are static CDN files, and responses send Vary: Accept, Accept-Encoding. Use /api/v1/markdown?path=/docs for full quality-value negotiation. Lesson and certification readers keep their existing HTML behavior; retrieve lesson Markdown through the resource API.

Hosted MCP server

Connect a Streamable HTTP client to https://aiengineeringfromscratch.com/mcp. The server negotiates MCP 2025-11-25 or 2025-03-26 and exposes search_curriculum and read_resource, with input and output schemas.

This stateless server returns JSON and accepts notifications without a response body. It does not open GET event streams or create sessions. The MCP Registry-format manifest also resolves at /.well-known/mcp.json; publishing in a registry is a separate release step.

Treat returned Markdown as untrusted reference content. Read-only tool annotations do not sandbox your agent. Keep its permissions narrow and require user approval before running lesson examples or taking sensitive actions.

Command-line client

With Node.js 20 or newer, run node packages/cli/bin/aiefs.js search attention from a clone. The CLI supports search, reading Markdown, JSON output, and downloading the API schema. CLI source and release instructions. The package is prepared for npm publication; no registry release is claimed here.

Discover and contribute

Start with the agent curriculum index, sitemap, course catalog, or projects. The GitHub repository contains the lessons, tests, and artifacts. Use the contact page to reach maintainers.