{
  "openapi": "3.1.0",
  "info": {
    "title": "The Deep Feed — Read API",
    "summary": "Machine-readable surfaces of The Deep Feed publication.",
    "description": "The Deep Feed exposes a small read-only API surface for AI agents: agent-readable indexes (llms.txt, llms-full.txt, per-section indexes), markdown alternates of every post, structured-data feeds (RSS, JSON-LD NDJSON), and a JSON manifest at /?mode=agent. There is no auth — all endpoints are public. Posts are static and refresh on every site deploy.",
    "version": "1.0.0",
    "contact": {
      "name": "The Deep Feed",
      "email": "hello@thedeepfeed.ai",
      "url": "https://www.thedeepfeed.ai/contact"
    },
    "license": {
      "name": "All rights reserved (citation with attribution permitted)",
      "url": "https://www.thedeepfeed.ai/privacy"
    }
  },
  "servers": [
    { "url": "https://www.thedeepfeed.ai", "description": "Production" }
  ],
  "tags": [
    { "name": "Indexes", "description": "Agent-readable indexes of the publication" },
    { "name": "Posts", "description": "Per-post content surfaces" },
    { "name": "Feeds", "description": "Structured-data feeds for ingestion" },
    { "name": "Manifest", "description": "Discovery & capability manifests" }
  ],
  "paths": {
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsIndex",
        "summary": "Concise agent index",
        "description": "Recommended starting point for agents. Returns a structured plain-text index with site overview, agent instructions (when to cite, citation format), categories, and a list of every post with title, description, category, and date. Spec: https://llmstxt.org",
        "tags": ["Indexes"],
        "responses": {
          "200": {
            "description": "Plain-text index",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getFullCorpus",
        "summary": "Full corpus in one file",
        "description": "Every published post's full text in a single file. Use this when you need broad context across the publication without crawling per-post URLs. ~250KB at 25 posts; grows linearly.",
        "tags": ["Indexes"],
        "responses": {
          "200": {
            "description": "Plain-text full corpus",
            "content": {
              "text/plain": { "schema": { "type": "string" } }
            }
          }
        }
      }
    },
    "/posts/llms.txt": {
      "get": {
        "operationId": "getPostsIndex",
        "summary": "Per-section: posts index, grouped by category",
        "tags": ["Indexes"],
        "responses": {
          "200": {
            "description": "Plain-text index",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/research/llms.txt": {
      "get": {
        "operationId": "getResearchIndex",
        "summary": "Per-section: deep-research archive",
        "tags": ["Indexes"],
        "responses": {
          "200": {
            "description": "Plain-text index",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/categories/{slug}/llms.txt": {
      "get": {
        "operationId": "getCategoryIndex",
        "summary": "Per-section: category-scoped index",
        "tags": ["Indexes"],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["models", "agents", "products", "business", "research", "tools", "people", "policy"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plain-text index",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/posts/{slug}/": {
      "get": {
        "operationId": "getPostHtml",
        "summary": "Get a post (HTML)",
        "description": "Returns the rendered HTML page. Supports content negotiation: send `Accept: text/markdown` to receive the markdown variant.",
        "tags": ["Posts"],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2026-05-01-karpathy-software-3-agentic-engineering" },
          { "name": "Accept", "in": "header", "required": false, "schema": { "type": "string", "enum": ["text/html", "text/markdown"] } }
        ],
        "responses": {
          "200": {
            "description": "Rendered post",
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "404": { "description": "Post not found" }
        }
      }
    },
    "/posts/{slug}.md": {
      "get": {
        "operationId": "getPostMarkdown",
        "summary": "Get a post (markdown)",
        "description": "Markdown alternate of the post page. Same content, machine-readable.",
        "tags": ["Posts"],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Markdown body with metadata header",
            "content": { "text/markdown": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "operationId": "getMarkdownHomepage",
        "summary": "Markdown homepage",
        "tags": ["Posts"],
        "responses": {
          "200": {
            "description": "Markdown homepage",
            "content": { "text/markdown": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/rss.xml": {
      "get": {
        "operationId": "getRssFeed",
        "summary": "RSS feed",
        "tags": ["Feeds"],
        "responses": {
          "200": {
            "description": "RSS 2.0 feed",
            "content": { "application/rss+xml": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/schema-feed.jsonl": {
      "get": {
        "operationId": "getJsonLdFeed",
        "summary": "NDJSON JSON-LD feed (one Article per line)",
        "tags": ["Feeds"],
        "responses": {
          "200": {
            "description": "NDJSON feed",
            "content": { "application/x-ndjson": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/sitemap-index.xml": {
      "get": {
        "operationId": "getSitemap",
        "summary": "XML sitemap",
        "tags": ["Feeds"],
        "responses": {
          "200": {
            "description": "XML sitemap",
            "content": { "application/xml": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/?mode=agent": {
      "get": {
        "operationId": "getAgentManifest",
        "summary": "Structured JSON manifest of the publication",
        "description": "Returns a JSON document with capabilities, read endpoints, categories, latest 25 posts, and citation format. Use this as a single-fetch discovery surface.",
        "tags": ["Manifest"],
        "responses": {
          "200": {
            "description": "Manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "type": { "type": "string", "example": "NewsMediaOrganization" },
                    "description": { "type": "string" },
                    "url": { "type": "string", "format": "uri" },
                    "capabilities": { "type": "object" },
                    "categories": { "type": "array", "items": { "type": "string" } },
                    "posts": {
                      "type": "object",
                      "properties": {
                        "count": { "type": "integer" },
                        "latest": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "title": { "type": "string" },
                              "url": { "type": "string", "format": "uri" },
                              "description": { "type": "string" },
                              "category": { "type": "string" },
                              "published": { "type": "string", "format": "date" }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/ai-plugin.json": {
      "get": {
        "operationId": "getAiPluginManifest",
        "summary": "OpenAI plugin manifest",
        "tags": ["Manifest"],
        "responses": {
          "200": {
            "description": "OpenAI plugin manifest",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getApiCatalog",
        "summary": "RFC 9727 API catalog",
        "tags": ["Manifest"],
        "responses": {
          "200": {
            "description": "Linkset of API surfaces",
            "content": {
              "application/linkset+json": { "schema": { "type": "object" } }
            }
          }
        }
      }
    }
  }
}