{
  "openapi": "3.1.1",
  "info": {
    "title": "Goalbadger Public Agent API",
    "version": "2026-08-25",
    "description": "Public, read-only discovery API for Goalbadger. This API exposes product, developer, and agent-integration metadata only. It does not expose private Goal Maps, execution state, mentoring rooms, tenant data, user records, or mutations.",
    "contact": {
      "name": "Goalbadger",
      "url": "https://goalbadger.app/contact",
      "email": "contact@goalbadger.app"
    }
  },
  "servers": [
    {
      "url": "https://goalbadger.app",
      "description": "Goalbadger production"
    }
  ],
  "externalDocs": {
    "description": "Goalbadger developer and agent resources",
    "url": "https://goalbadger.app/developers.md"
  },
  "tags": [
    {
      "name": "Agent Discovery",
      "description": "Public, read-only endpoints for agent capability and resource discovery."
    }
  ],
  "paths": {
    "/api/agent/v1/health": {
      "get": {
        "operationId": "getGoalbadgerAgentHealth",
        "summary": "Check the public agent API",
        "description": "Returns the public Goalbadger agent API version, access mode, OpenAPI location, and MCP transport metadata. No authentication is required.",
        "tags": ["Agent Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "The public agent API is reachable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentHealth" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/PublicAgentDisabled" }
        }
      }
    },
    "/api/agent/v1/capabilities": {
      "get": {
        "operationId": "getGoalbadgerPublicCapabilities",
        "summary": "Get public Goalbadger agent capabilities",
        "description": "Returns the machine-readable public capability catalog and explicit boundaries. Private user and tenant data is not exposed.",
        "tags": ["Agent Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "Current public agent capabilities.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentCapabilities" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/PublicAgentDisabled" }
        }
      }
    },
    "/api/agent/v1/resources": {
      "get": {
        "operationId": "listGoalbadgerPublicResources",
        "summary": "List public Goalbadger resources",
        "description": "Lists stable public resources that agents may read without authentication.",
        "tags": ["Agent Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "Public resource catalog.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResourceList" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/PublicAgentDisabled" }
        }
      }
    },
    "/api/agent/v1/resources/{resourceId}": {
      "get": {
        "operationId": "getGoalbadgerPublicResource",
        "summary": "Read a public Goalbadger resource",
        "description": "Reads one public Goalbadger resource by its stable resource id.",
        "tags": ["Agent Discovery"],
        "security": [],
        "parameters": [
          {
            "name": "resourceId",
            "in": "path",
            "required": true,
            "description": "Stable public resource id returned by the resource catalog.",
            "schema": {
              "type": "string",
              "enum": [
                "product-overview",
                "developer-resources",
                "agent-boundaries"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The requested public resource.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" }
              }
            }
          },
          "404": {
            "description": "No public resource exists with that id.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ProblemDetails" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/PublicAgentDisabled" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "PublicAgentDisabled": {
        "description": "The public agent surface is disabled by Goalbadger platform rollout policy.",
        "headers": {
          "Retry-After": {
            "description": "Suggested minimum delay before checking rollout state again.",
            "schema": { "type": "integer", "example": 60 }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      }
    },
    "schemas": {
      "AgentHealth": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "service",
          "status",
          "version",
          "access",
          "authenticationRequired",
          "privateUserDataExposed",
          "writesSupported",
          "openapi",
          "mcp"
        ],
        "properties": {
          "service": { "type": "string", "const": "Goalbadger Public Agent API" },
          "status": { "type": "string", "const": "ok" },
          "version": { "type": "string", "description": "Date-based public API contract version." },
          "access": { "type": "string", "const": "public_read_only" },
          "authenticationRequired": { "type": "boolean", "const": false },
          "privateUserDataExposed": { "type": "boolean", "const": false },
          "writesSupported": { "type": "boolean", "const": false },
          "openapi": { "type": "string", "format": "uri" },
          "mcp": { "$ref": "#/components/schemas/McpMetadata" }
        }
      },
      "McpMetadata": {
        "type": "object",
        "additionalProperties": false,
        "required": ["endpoint", "transport", "protocolVersion"],
        "properties": {
          "endpoint": { "type": "string", "format": "uri" },
          "transport": { "type": "string", "const": "streamable_http" },
          "protocolVersion": { "type": "string", "example": "2026-07-28" }
        }
      },
      "AgentCapabilities": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "service",
          "product",
          "version",
          "access",
          "authenticationRequired",
          "privateUserDataExposed",
          "writesSupported",
          "endpoints",
          "resources",
          "boundaries"
        ],
        "properties": {
          "service": { "type": "string" },
          "product": { "type": "string", "const": "Goalbadger" },
          "version": { "type": "string" },
          "access": { "type": "string", "const": "public_read_only" },
          "authenticationRequired": { "type": "boolean", "const": false },
          "privateUserDataExposed": { "type": "boolean", "const": false },
          "writesSupported": { "type": "boolean", "const": false },
          "endpoints": {
            "type": "object",
            "description": "Canonical machine-readable Goalbadger discovery endpoints.",
            "additionalProperties": { "type": "string", "format": "uri" }
          },
          "resources": {
            "type": "array",
            "minItems": 1,
            "items": { "$ref": "#/components/schemas/AgentResourceDescriptor" }
          },
          "boundaries": {
            "type": "object",
            "description": "Explicit public-data boundaries. Values are not_exposed for private product state.",
            "additionalProperties": { "type": "string" }
          }
        }
      },
      "AgentResourceDescriptor": {
        "type": "object",
        "required": ["id", "uri", "name", "description", "mimeType"],
        "properties": {
          "id": { "type": "string" },
          "uri": { "type": "string", "format": "uri" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "mimeType": { "type": "string", "const": "text/markdown" },
          "href": { "type": "string", "format": "uri" }
        }
      },
      "AgentResourceList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["resources"],
        "properties": {
          "resources": {
            "type": "array",
            "minItems": 1,
            "items": { "$ref": "#/components/schemas/AgentResourceDescriptor" }
          }
        }
      },
      "AgentResource": {
        "allOf": [
          { "$ref": "#/components/schemas/AgentResourceDescriptor" },
          {
            "type": "object",
            "required": ["content"],
            "properties": {
              "content": {
                "type": "string",
                "minLength": 1,
                "description": "Non-empty public resource content."
              }
            }
          }
        ]
      },
      "ProblemDetails": {
        "type": "object",
        "additionalProperties": false,
        "required": ["type", "title", "status", "code", "detail", "resolution"],
        "properties": {
          "type": { "type": "string", "format": "uri-reference" },
          "title": { "type": "string" },
          "status": { "type": "integer", "minimum": 400, "maximum": 599 },
          "code": { "type": "string" },
          "detail": { "type": "string" },
          "resolution": { "type": "string" },
          "instance": { "type": "string", "format": "uri-reference" }
        }
      }
    }
  },
  "x-goalbadger-feature-key": "public_agent_access_v1",
  "x-goalbadger-authenticated-agent-api": {
    "status": "not_public",
    "reason": "Private Goalbadger data and mutations require a separate OAuth, RBAC, audit, and execution-authority boundary. This OpenAPI document intentionally does not advertise an OAuth scheme that is not yet implemented."
  }
}