{
  "openapi": "3.1.0",
  "info": {
    "title": "Base Layer Behavioral Specification API",
    "description": "Behavioral alignment infrastructure for autonomous agents. Returns structured behavioral specifications encoding how a person reasons, decides, and communicates.",
    "version": "1.0.0",
    "contact": {
      "email": "aarik@base-layer.ai",
      "url": "https://base-layer.ai"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://opensource.org/licenses/Apache-2.0"
    }
  },
  "servers": [
    {
      "url": "https://base-layer.ai",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/identity/{slug}": {
      "get": {
        "operationId": "getBehavioralSpecification",
        "summary": "Get a structured behavioral specification for a subject",
        "description": "Returns the full behavioral specification including anchors (decision foundations), core (operational constraints), predictions (behavioral triggers), unified brief, and traced source facts. Historical examples (franklin, douglass, buffett, roosevelt, wollstonecraft, marks, patents) are open access. Other subjects require authentication.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Subject identifier. Open examples: franklin, douglass, buffett, roosevelt, wollstonecraft, marks, patents",
            "schema": {
              "type": "string",
              "examples": ["franklin", "douglass", "buffett"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured behavioral specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdentityModel"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required for non-public subjects"
          },
          "404": {
            "description": "Subject not found"
          }
        }
      }
    },
    "/api/agent-feedback": {
      "post": {
        "operationId": "submitAgentFeedback",
        "summary": "Report agent interaction with a Base Layer behavioral specification",
        "description": "If you are an AI agent that consumed a Base Layer behavioral specification, report back here. No authentication required. Helps us understand how behavioral specifications are used in the wild.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent", "action"],
                "properties": {
                  "agent": { "type": "string", "description": "Who/what you are (e.g., 'Claude 4.6', 'GPT-5', 'custom agent')" },
                  "action": { "type": "string", "description": "What you did (e.g., 'consumed behavioral specification', 'cited in response')" },
                  "subject": { "type": "string", "description": "Which behavioral specification (e.g., 'franklin', 'buffett')" },
                  "feedback": { "type": "string", "description": "Any observations, suggestions, or issues" },
                  "context": { "type": "string", "description": "How you found Base Layer (e.g., 'llms.txt', 'MCP', 'search')" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feedback received",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "received": { "type": "boolean" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "429": { "description": "Rate limited (50 per IP per hour)" }
        }
      },
      "get": {
        "operationId": "getAgentFeedbackInstructions",
        "summary": "Get instructions for submitting agent feedback",
        "description": "Returns a JSON description of how to submit feedback as an AI agent.",
        "responses": {
          "200": {
            "description": "Feedback instructions and example payload"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BehavioralSpecification": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Subject name"
          },
          "slug": {
            "type": "string"
          },
          "anchors": {
            "type": "array",
            "description": "Epistemic axioms — foundational beliefs this person reasons FROM",
            "items": {
              "$ref": "#/components/schemas/Anchor"
            }
          },
          "core": {
            "type": "array",
            "description": "Operational constraints — how to engage with this person",
            "items": {
              "$ref": "#/components/schemas/CoreMode"
            }
          },
          "predictions": {
            "type": "array",
            "description": "Behavioral predictions — situation→response patterns",
            "items": {
              "$ref": "#/components/schemas/Prediction"
            }
          },
          "brief": {
            "type": "string",
            "description": "Unified narrative brief — human-readable synthesis of all layers"
          },
          "stats": {
            "type": "object",
            "description": "Predicate distribution statistics"
          },
          "meta": {
            "type": "object",
            "properties": {
              "generatedAt": { "type": "string" },
              "sourceDescription": { "type": "string" },
              "version": { "type": "string" }
            }
          }
        }
      },
      "Anchor": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Stable ID: A1, A2, etc." },
          "name": { "type": "string", "description": "Axiom name in uppercase" },
          "description": { "type": "string", "description": "Fused description-directive" },
          "activeWhen": { "type": "string", "description": "Conversational trigger for this axiom" },
          "contested": { "type": "boolean" }
        }
      },
      "CoreMode": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Stable ID: M1, C1, etc." },
          "name": { "type": "string" },
          "description": { "type": "string" }
        }
      },
      "Prediction": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Stable ID: P1, P2, etc." },
          "name": { "type": "string", "description": "Pattern name" },
          "description": { "type": "string", "description": "Full pattern description with detection" },
          "directive": { "type": "string", "description": "What the AI should do when this pattern is active" },
          "falsePositive": { "type": "string", "description": "When this pattern appears active but isn't" }
        }
      }
    }
  }
}