{
  "openapi": "3.1.0",
  "info": {
    "title": "4M Labs Site Content API",
    "version": "1.0.0",
    "summary": "Machine-readable surface of 4mlabs.io",
    "description": "4mlabs.io is a statically rendered marketing site for an applied-AI engineering firm in Guadalajara, Mexico. This specification documents its machine-facing content surface: every page is available as HTML and as markdown (Accept: text/markdown negotiation, or append .md). Structured discovery files are listed under paths below. There is no authenticated API on this host; product APIs live on api.4mlabs.cloud.\n\nVersioning policy: this document describes API version 1 (info.version). Backwards-compatible additions (new optional fields, new discovery files) ship without a version bump; breaking changes will mint info.version 2.x and be announced via llms.txt for at least 90 days before removal. No deprecations are currently scheduled.",
    "x-api-versioning-policy": {
      "current": "1",
      "scheme": "spec-version",
      "breakingChanges": "Announced via https://4mlabs.io/llms.txt at least 90 days ahead",
      "deprecationsScheduled": []
    },
    "contact": {
      "name": "4M Labs",
      "email": "hello@4mlabs.io",
      "url": "https://4mlabs.io/en/contact/"
    },
    "license": { "name": "Content is copyrighted; crawling for AI indexing permitted per robots.txt" }
  },
  "servers": [
    { "url": "https://4mlabs.io", "description": "Production" }
  ],
  "tags": [
    { "name": "discovery", "description": "Files that describe the site to machines" },
    { "name": "content", "description": "Human pages, also served as markdown" }
  ],
  "paths": {
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": ["discovery"],
        "summary": "Site overview formatted for LLM consumption",
        "responses": {
          "200": {
            "description": "Markdown-formatted site index",
            "content": { "text/markdown": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getLlmsFullTxt",
        "tags": ["discovery"],
        "summary": "Extended LLM-ready site content",
        "responses": {
          "200": { "description": "Full-text LLM index", "content": { "text/markdown": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemapIndex",
        "tags": ["discovery"],
        "summary": "XML sitemap index of all indexable URLs",
        "responses": {
          "200": { "description": "Sitemap index XML", "content": { "application/xml": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/feed.xml": {
      "get": {
        "operationId": "getRssFeed",
        "tags": ["discovery"],
        "summary": "RSS feed of blog posts",
        "responses": {
          "200": { "description": "RSS 2.0 XML", "content": { "application/xml": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/.well-known/agents.json": {
      "get": {
        "operationId": "getAgentsManifest",
        "tags": ["discovery"],
        "summary": "Agent-facing capability manifest including when-to-use guidance",
        "responses": {
          "200": { "description": "Agent manifest JSON", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/.well-known/security.txt": {
      "get": {
        "operationId": "getSecurityTxt",
        "tags": ["discovery"],
        "summary": "Security research contact policy (RFC 9116)",
        "responses": {
          "200": { "description": "security.txt body", "content": { "text/plain": { "schema": { "type": "string" } } } }
        }
      }
    },
    "/.well-known/mcp/server-card.json": {
      "get": {
        "operationId": "getMcpServerCard",
        "tags": ["discovery"],
        "summary": "MCP Server Card for agent discovery (SEP-1649)",
        "responses": {
          "200": { "description": "MCP Server Card JSON", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/.well-known/ai-catalog.json": {
      "get": {
        "operationId": "getArdManifest",
        "tags": ["discovery"],
        "summary": "ARD capability manifest for agent discovery",
        "responses": {
          "200": { "description": "ARD manifest JSON", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getApiCatalog",
        "tags": ["discovery"],
        "summary": "RFC 9727 API catalog for automated discovery",
        "responses": {
          "200": { "description": "Linkset JSON", "content": { "application/linkset+json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "tags": ["discovery"],
        "summary": "This specification",
        "responses": {
          "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/{locale}/case-studies/{slug}": {
      "get": {
        "operationId": "getCaseStudy",
        "tags": ["content"],
        "summary": "A production system case study (results-first writeup)",
        "parameters": [
          { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": ["en", "es"] } },
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "examples": ["platia", "globalfit", "squish", "gasgo"] } },
          { "name": "Accept", "in": "header", "required": false, "description": "Send text/markdown to receive the markdown twin instead of HTML.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Case study page",
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/{locale}/blogs/{slug}": {
      "get": {
        "operationId": "getBlogPost",
        "tags": ["content"],
        "summary": "Blog article from the 4M Labs engineering journal",
        "parameters": [
          { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": ["en", "es"] } },
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "Accept", "in": "header", "required": false, "description": "text/markdown returns the markdown twin.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Blog post page",
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/{locale}/{path}": {
      "get": {
        "operationId": "getPage",
        "tags": ["content"],
        "summary": "Any site page (services, pricing, about, contact, book, developers)",
        "description": "Canonical URLs carry a locale prefix and trailing slash (/en/pricing/). All routes enumerate in /sitemap.xml.",
        "parameters": [
          { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": ["en", "es"] } },
          { "name": "path", "in": "path", "required": true, "allowReserved": true, "schema": { "type": "string" }, "examples": { "pricing": { "value": "pricing/" }, "about": { "value": "about/" }, "book": { "value": "book/" } } },
          { "name": "Accept", "in": "header", "required": false, "description": "text/markdown returns the markdown twin of any page.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Rendered page (HTML) or markdown twin depending on Accept header",
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "RFC 9457-aligned problem detail. Returned as application/json (or text/markdown recovery page when the client requests markdown).",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "const": "not_found", "description": "Stable machine-readable error code" },
              "message": { "type": "string", "description": "Human-readable summary" },
              "resolution": { "type": "string", "description": "Concrete next step for an agent: URLs to recover with" },
              "links": {
                "type": "array",
                "description": "Recovery targets",
                "items": {
                  "type": "object",
                  "properties": {
                    "rel": { "type": "string" },
                    "href": { "type": "string", "format": "uri" }
                  },
                  "required": ["rel", "href"]
                }
              }
            },
            "required": ["code", "message", "resolution"]
          }
        },
        "required": ["error"]
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found. Machines receive structured JSON unless they request HTML or markdown.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Resource not found",
                "resolution": "Browse https://4mlabs.io/sitemap.xml or see https://4mlabs.io/openapi.json",
                "links": [
                  { "rel": "sitemap", "href": "https://4mlabs.io/sitemap.xml" },
                  { "rel": "llms", "href": "https://4mlabs.io/llms.txt" },
                  { "rel": "developers", "href": "https://4mlabs.io/en/developers/" }
                ]
              }
            }
          },
          "application/problem+json": {
            "schema": {
              "type": "object",
              "properties": {
                "type": { "const": "about:blank" },
                "title": { "const": "Not Found" },
                "status": { "const": 404 },
                "detail": { "type": "string" },
                "instance": { "type": "string", "format": "uri-reference" }
              },
              "required": ["type", "title", "status"]
            }
          },
          "text/markdown": {
            "schema": { "type": "string" },
            "description": "Markdown recovery page with sitemap and developer-resource links"
          }
        }
      }
    }
  },
  "x-rate-limit-convention": "Static content host: no rate limiting beyond standard Cloudflare protections. Product APIs at api.4mlabs.cloud document their own limits."
}