{
  "openapi": "3.1.0",
  "info": {
    "title": "Urizen public site API",
    "version": "1.0.0",
    "summary": "Read-only content API for urizen.ai.",
    "description": "A read-only, unauthenticated API describing the public website of Urizen Research Labs. It exists so AI agents and scripts can consume the site's content and surface list without scraping HTML. There is no public transactional API: the Nibiru engine, Baobab control layer, and Anansi harness are experimental research previews accessed per engagement. Nonexistent paths under /api/ return HTTP 404 with a structured JSON error body.",
    "contact": {
      "name": "Urizen Research Labs",
      "email": "hello@urizen.ai",
      "url": "https://urizen.ai/contact/"
    }
  },
  "servers": [
    { "url": "https://urizen.ai", "description": "Production" }
  ],
  "paths": {
    "/api/site.json": {
      "get": {
        "operationId": "getSiteIndex",
        "summary": "Get the site index",
        "description": "Returns the machine-readable index of urizen.ai: what the lab is, its systems with exact status notes, every public page, every machine surface, and how to make contact. This is the primary endpoint; fetch it first.",
        "tags": ["site"],
        "responses": {
          "200": {
            "description": "The site index.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SiteIndex" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getAgentIndex",
        "summary": "Get the llms.txt agent index",
        "description": "Returns the llms.txt markdown index: what the lab is, when to use the site, important honesty notes, and the main pages with one-line descriptions.",
        "tags": ["agent-surfaces"],
        "responses": {
          "200": {
            "description": "The agent index as markdown.",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/agents.md": {
      "get": {
        "operationId": "getAgentInstructions",
        "summary": "Get agent instructions",
        "description": "Returns when-to-use guidance for AI agents: the jobs urizen.ai is right for, the jobs it is not, and how to quote the lab's exact status labels.",
        "tags": ["agent-surfaces"],
        "responses": {
          "200": {
            "description": "Agent instructions as markdown.",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemap",
        "summary": "Get the sitemap",
        "description": "Returns the XML sitemap listing every public route on urizen.ai.",
        "tags": ["agent-surfaces"],
        "responses": {
          "200": {
            "description": "The sitemap.",
            "content": {
              "application/xml": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "The path does not exist. The body carries a structured error with recovery hints.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    },
    "schemas": {
      "SiteIndex": {
        "type": "object",
        "description": "Machine-readable index of the public urizen.ai site.",
        "required": ["schema_version", "name", "tagline", "description", "systems", "pages", "machine_surfaces", "contact"],
        "properties": {
          "schema_version": { "type": "string", "description": "Semantic version of this document's schema. Breaking changes bump the major version and are noted in /llms.txt." },
          "name": { "type": "string", "description": "Organization name." },
          "tagline": { "type": "string", "description": "One-sentence statement of what the lab does." },
          "description": { "type": "string", "description": "Short description including the current availability posture." },
          "systems": {
            "type": "array",
            "description": "The lab's systems with exact, non-upgraded status notes.",
            "items": { "$ref": "#/components/schemas/System" }
          },
          "pages": {
            "type": "array",
            "description": "Every public page.",
            "items": { "$ref": "#/components/schemas/Page" }
          },
          "machine_surfaces": {
            "type": "array",
            "description": "Every machine-readable surface the site serves.",
            "items": { "$ref": "#/components/schemas/MachineSurface" }
          },
          "contact": { "$ref": "#/components/schemas/Contact" },
          "notes": {
            "type": "array",
            "description": "Reading rules an agent should apply when summarizing this site.",
            "items": { "type": "string" }
          }
        }
      },
      "System": {
        "type": "object",
        "description": "One Urizen system.",
        "required": ["name", "role", "status_note"],
        "properties": {
          "name": { "type": "string", "description": "System name." },
          "role": { "type": "string", "description": "What the system is for." },
          "status_note": { "type": "string", "description": "Exact availability and evidence note. Quote without upgrading." }
        }
      },
      "Page": {
        "type": "object",
        "description": "One public page.",
        "required": ["title", "url", "description"],
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" }
        }
      },
      "MachineSurface": {
        "type": "object",
        "description": "One machine-readable surface.",
        "required": ["name", "url", "content_type", "description"],
        "properties": {
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "content_type": { "type": "string", "description": "Media type the surface is served with." },
          "description": { "type": "string" }
        }
      },
      "Contact": {
        "type": "object",
        "description": "How to reach the lab.",
        "required": ["email", "url"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "url": { "type": "string", "format": "uri", "description": "The contact page." }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Structured error body returned for 404s under /api/ and for JSON-accepting clients.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "hint"],
            "properties": {
              "code": { "type": "string", "description": "Stable machine-readable error code, e.g. not_found." },
              "message": { "type": "string", "description": "Human-readable statement of what went wrong." },
              "hint": { "type": "string", "description": "Where to look next: the working endpoints and indexes." },
              "documentation_url": { "type": "string", "format": "uri", "description": "The developer portal." }
            }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "site", "description": "The site content index." },
    { "name": "agent-surfaces", "description": "Text surfaces published for AI agents." }
  ]
}