{
  "openapi": "3.1.0",
  "info": {
    "title": "Articles API — articles.santismm.com",
    "version": "1.0",
    "summary": "Read-only access to Santiago Santa María's essays on AI and autonomous agents.",
    "description": "Static, unauthenticated, read-only JSON and text resources generated from the essays on disk. Only GET (and HEAD/OPTIONS) is served; there is no query language, pagination, search or write operation. The contract is additive: new fields and new essays may appear at any time, and a breaking change would ship under a new path rather than change these in place. No rate limit is enforced by this site. Human-readable documentation: https://articles.santismm.com/api/",
    "contact": {
      "name": "Santiago Santa María",
      "url": "https://articles.santismm.com/contact/"
    },
    "license": {
      "name": "CC BY 4.0 (essay text)",
      "identifier": "CC-BY-4.0"
    }
  },
  "externalDocs": {
    "description": "Articles API documentation",
    "url": "https://articles.santismm.com/api/"
  },
  "servers": [
    {
      "url": "https://articles.santismm.com"
    }
  ],
  "tags": [
    {
      "name": "articles",
      "description": "The structured essays."
    },
    {
      "name": "discovery",
      "description": "Catalogues, feeds and agent discovery files."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getHome",
        "tags": [
          "discovery"
        ],
        "summary": "Site index, as HTML or Markdown",
        "description": "Content-negotiated. `Accept: text/markdown` (preferred at least as highly as `text/html`) returns a Markdown rendition of the index; anything else returns the HTML page. Both carry `Vary: Accept`.",
        "responses": {
          "200": {
            "description": "The index of every essay.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "Vary": {
                "$ref": "#/components/headers/Vary"
              }
            }
          }
        }
      }
    },
    "/api/articles.json": {
      "get": {
        "operationId": "listArticles",
        "tags": [
          "articles"
        ],
        "summary": "Every essay with its full text",
        "responses": {
          "200": {
            "description": "The full catalogue, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleCatalogue"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/articles/{slug}.json": {
      "get": {
        "operationId": "getArticle",
        "tags": [
          "articles"
        ],
        "summary": "One essay with its full text",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The essay's slug. Listed here as of this document's generation; new slugs are additive.",
            "schema": {
              "type": "string",
              "enum": [
                "a-empresa-agentica-precisa-de-um-sistema-imunologico",
                "cognitive-architecture-and-emergent-phenomena",
                "el-auge-de-la-ia-agentica",
                "el-cronometro-y-el-examen",
                "la-arquitectura-cognitiva",
                "la-empresa-agentica-necesita-un-sistema-inmunitario",
                "la-proxima-generacion-de-ia",
                "o-cronometro-e-o-exame",
                "self-improvement-and-autonomous-learning",
                "the-agentic-enterprise-needs-an-immune-system",
                "the-rise-of-agentic-ai",
                "the-stopwatch-and-the-exam",
                "vibe-coding-en-el-software-empresarial",
                "vibe-coding-in-enterprise-software"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The essay.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleResource"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/ai-index.json": {
      "get": {
        "operationId": "getAiIndex",
        "tags": [
          "discovery"
        ],
        "summary": "Metadata catalogue and discovery map",
        "responses": {
          "200": {
            "description": "Every essay's metadata, without text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiIndex"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/feed.json": {
      "get": {
        "operationId": "getFeed",
        "tags": [
          "discovery"
        ],
        "summary": "JSON Feed of every essay, all languages",
        "responses": {
          "200": {
            "description": "JSON Feed 1.1.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonFeed"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/feed.{locale}.json": {
      "get": {
        "operationId": "getLocaleFeed",
        "tags": [
          "discovery"
        ],
        "summary": "JSON Feed of the essays in one language",
        "parameters": [
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "description": "`en` (English), `es` (es-ES) or `pt` (pt-BR).",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "pt"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON Feed 1.1 for one locale.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonFeed"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": [
          "discovery"
        ],
        "summary": "Agent index (llms.txt)",
        "responses": {
          "200": {
            "description": "Markdown-formatted index with usage guidance.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getLlmsFullTxt",
        "tags": [
          "discovery"
        ],
        "summary": "Full text of every essay (llms-full.txt)",
        "responses": {
          "200": {
            "description": "Every essay's full text in one document.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "License": {
        "type": "object",
        "description": "Licence of the essays' text.",
        "required": [
          "name",
          "spdx",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "const": "CC BY 4.0"
          },
          "spdx": {
            "type": "string",
            "const": "CC-BY-4.0"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "attribution": {
            "type": "string",
            "description": "The name to attribute."
          }
        }
      },
      "Article": {
        "type": "object",
        "description": "One essay, including its full text.",
        "required": [
          "slug",
          "title",
          "summary",
          "language",
          "published",
          "modified",
          "topics",
          "canonical_url",
          "api_url",
          "body"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "description": "Stable essay identifier. Also the essay's path: the canonical page is `/<slug>/`."
          },
          "title": {
            "type": "string",
            "description": "The essay's headline."
          },
          "summary": {
            "type": "string",
            "description": "One-paragraph summary written by the author."
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "es-ES",
              "pt-BR"
            ],
            "description": "BCP 47 language tag of the essay."
          },
          "published": {
            "type": "string",
            "format": "date",
            "description": "First publication date, `YYYY-MM-DD`."
          },
          "modified": {
            "type": "string",
            "format": "date",
            "description": "Last substantive revision, `YYYY-MM-DD`. Equals `published` when never revised."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Editorial section(s) of the essay."
          },
          "translation_key": {
            "type": "string",
            "description": "Shared by every language edition of the same essay. Absent when the essay has no translation."
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "description": "The URL to cite."
          },
          "api_url": {
            "type": "string",
            "format": "uri",
            "description": "This essay's own resource in the Articles API."
          },
          "body": {
            "type": "string",
            "description": "Full text as Markdown-like plain text derived from the authored HTML: `#` headings, `-` list items, links as `text (url)`."
          }
        }
      },
      "ArticleCatalogue": {
        "type": "object",
        "description": "Every essay with its full text, newest first.",
        "required": [
          "schema_version",
          "source",
          "canonical_url",
          "count",
          "license",
          "articles"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0"
          },
          "source": {
            "type": "string"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri"
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of items in `articles`."
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "articles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          }
        }
      },
      "ArticleResource": {
        "type": "object",
        "description": "One essay. `article` is identical to its entry in the catalogue.",
        "required": [
          "schema_version",
          "source",
          "license",
          "article"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0"
          },
          "source": {
            "type": "string"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "article": {
            "$ref": "#/components/schemas/Article"
          }
        }
      },
      "AiIndexArticle": {
        "type": "object",
        "description": "An essay's metadata, without its text.",
        "required": [
          "slug",
          "title",
          "summary",
          "language",
          "published",
          "modified",
          "topics",
          "canonical_url",
          "api_url"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "description": "Stable essay identifier. Also the essay's path: the canonical page is `/<slug>/`."
          },
          "title": {
            "type": "string",
            "description": "The essay's headline."
          },
          "summary": {
            "type": "string",
            "description": "One-paragraph summary written by the author."
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "es-ES",
              "pt-BR"
            ],
            "description": "BCP 47 language tag of the essay."
          },
          "published": {
            "type": "string",
            "format": "date",
            "description": "First publication date, `YYYY-MM-DD`."
          },
          "modified": {
            "type": "string",
            "format": "date",
            "description": "Last substantive revision, `YYYY-MM-DD`. Equals `published` when never revised."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Editorial section(s) of the essay."
          },
          "translation_key": {
            "type": "string",
            "description": "Shared by every language edition of the same essay. Absent when the essay has no translation."
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "description": "The URL to cite."
          },
          "api_url": {
            "type": "string",
            "format": "uri",
            "description": "This essay's own resource in the Articles API."
          }
        }
      },
      "AiIndex": {
        "type": "object",
        "description": "Machine-readable catalogue and discovery map.",
        "required": [
          "schema_version",
          "source",
          "canonical_url",
          "languages",
          "license",
          "discovery",
          "articles"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0"
          },
          "source": {
            "type": "string"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri"
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "en",
                "es-ES",
                "pt-BR"
              ],
              "description": "BCP 47 language tag of the essay."
            }
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "discovery": {
            "type": "object",
            "description": "Absolute URLs of every discovery surface.",
            "required": [
              "robots",
              "sitemap",
              "llms_txt",
              "llms_full_txt",
              "articles_api",
              "openapi",
              "api_docs",
              "rss",
              "json_feed"
            ],
            "properties": {
              "robots": {
                "type": "string",
                "format": "uri"
              },
              "sitemap": {
                "type": "string",
                "format": "uri"
              },
              "llms_txt": {
                "type": "string",
                "format": "uri"
              },
              "llms_full_txt": {
                "type": "string",
                "format": "uri"
              },
              "articles_api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "api_docs": {
                "type": "string",
                "format": "uri"
              },
              "rss": {
                "type": "string",
                "format": "uri"
              },
              "json_feed": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "articles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AiIndexArticle"
            }
          }
        }
      },
      "JsonFeedAuthor": {
        "type": "object",
        "required": [
          "name",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "JsonFeedItem": {
        "type": "object",
        "required": [
          "id",
          "url",
          "title",
          "summary",
          "image",
          "date_published",
          "date_modified",
          "language",
          "authors"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uri",
            "description": "The essay's canonical URL."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "1200x630 Open Graph card."
          },
          "date_published": {
            "type": "string",
            "format": "date-time"
          },
          "date_modified": {
            "type": "string",
            "format": "date-time"
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "es-ES",
              "pt-BR"
            ],
            "description": "BCP 47 language tag of the essay."
          },
          "authors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonFeedAuthor"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Absent when the essay has no section."
          }
        }
      },
      "JsonFeed": {
        "type": "object",
        "description": "A JSON Feed 1.1 document (https://www.jsonfeed.org/version/1.1/).",
        "required": [
          "version",
          "title",
          "home_page_url",
          "feed_url",
          "description",
          "language",
          "authors",
          "items"
        ],
        "properties": {
          "version": {
            "type": "string",
            "const": "https://jsonfeed.org/version/1.1"
          },
          "title": {
            "type": "string"
          },
          "home_page_url": {
            "type": "string",
            "format": "uri"
          },
          "feed_url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          },
          "language": {
            "type": "string",
            "enum": [
              "mul",
              "en",
              "es-ES",
              "pt-BR"
            ],
            "description": "`mul` for the multilingual feed, otherwise the locale's tag."
          },
          "authors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonFeedAuthor"
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonFeedItem"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "The JSON error body. The hosting platform emits `{\"error\":{\"code\",\"message\"}}`; responses produced by this site's own negotiation add `path` and `documentation_url` inside `error`.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "The HTTP status code, as a string (for example `\"404\"`)."
              },
              "message": {
                "type": "string"
              },
              "path": {
                "type": "string",
                "description": "The path that was requested."
              },
              "documentation_url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Nothing exists at this path. The body is JSON (`Error`) when the request accepts `application/json`, and for any unknown path under `/api/` unless the client prefers HTML or Markdown; it is Markdown when the request prefers `text/markdown`. Otherwise the hosting platform answers with its own plain-text or HTML page.",
        "headers": {
          "Vary": {
            "$ref": "#/components/headers/Vary"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          },
          "text/markdown": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    },
    "headers": {
      "Vary": {
        "description": "`Accept` on responses whose representation depends on the Accept header.",
        "schema": {
          "type": "string"
        }
      }
    }
  }
}
