{
  "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. Access is unauthenticated and read-only: no OAuth scope, API key, or bearer token is required, which is declared machine-readably by the empty `security` requirement. Versioning, deprecation, and rate-limit policy: https://goalbadger.app/developers.md#versioning-and-deprecation",
    "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"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "The client exceeded the published public agent quota.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    30
                  ]
                }
              },
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "The public agent surface is disabled by Goalbadger platform rollout policy.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Suggested minimum delay before checking rollout state again.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "The client exceeded the published public agent quota.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    30
                  ]
                }
              },
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "The public agent surface is disabled by Goalbadger platform rollout policy.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Suggested minimum delay before checking rollout state again.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "The client exceeded the published public agent quota.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    30
                  ]
                }
              },
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "The public agent surface is disabled by Goalbadger platform rollout policy.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Suggested minimum delay before checking rollout state again.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No public resource exists with that id.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "The client exceeded the published public agent quota.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    30
                  ]
                }
              },
              "RateLimit-Limit": {
                "description": "Requests permitted in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    120
                  ]
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests still available in the current window.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    119
                  ]
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              },
              "RateLimit-Policy": {
                "description": "Structured-field quota policy, e.g. \"public-agent-rest\";q=120;w=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Date-based contract version that produced this response.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "2026-08-25"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "The public agent surface is disabled by Goalbadger platform rollout policy.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Suggested minimum delay before checking rollout state again.",
                "schema": {
                  "type": "integer",
                  "examples": [
                    60
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "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",
          "versioning",
          "authorization",
          "rateLimit",
          "onboarding"
        ],
        "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"
            }
          },
          "versioning": {
            "$ref": "#/components/schemas/AgentVersioning"
          },
          "authorization": {
            "$ref": "#/components/schemas/AgentAuthorization"
          },
          "rateLimit": {
            "$ref": "#/components/schemas/AgentRateLimit"
          },
          "onboarding": {
            "$ref": "#/components/schemas/AgentOnboarding"
          }
        }
      },
      "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"
          }
        }
      },
      "AgentVersioning": {
        "type": "object",
        "description": "How this API is versioned and how a retirement is announced.",
        "required": [
          "scheme",
          "currentVersion",
          "currentMajor",
          "basePath",
          "policyUrl",
          "minimumSunsetNoticeDays",
          "breakingChangePolicy",
          "deprecatedVersions"
        ],
        "properties": {
          "scheme": {
            "type": "string",
            "const": "url_path"
          },
          "currentVersion": {
            "type": "string",
            "description": "Date-based contract version."
          },
          "currentMajor": {
            "type": "string",
            "examples": [
              "v1"
            ]
          },
          "basePath": {
            "type": "string"
          },
          "policyUrl": {
            "type": "string",
            "format": "uri"
          },
          "minimumSunsetNoticeDays": {
            "type": "integer",
            "description": "Minimum days between a deprecation announcement and sunset."
          },
          "breakingChangePolicy": {
            "type": "string",
            "const": "new_major_path_segment"
          },
          "deprecatedVersions": {
            "type": "array",
            "description": "Deprecated majors. Each entry is also emitted as RFC 9745 Deprecation and RFC 8594 Sunset response headers.",
            "items": {
              "type": "object",
              "required": [
                "major",
                "deprecationDate",
                "sunsetDate",
                "successor"
              ],
              "properties": {
                "major": {
                  "type": "string"
                },
                "deprecationDate": {
                  "type": "string",
                  "description": "IMF-fixdate."
                },
                "sunsetDate": {
                  "type": "string",
                  "description": "IMF-fixdate."
                },
                "successor": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "AgentAuthorization": {
        "type": "object",
        "description": "Authorization model. Goalbadger publishes no OAuth scopes it cannot grant, so `scopesRequired` is empty and `futureScopes` entries are explicitly not grantable.",
        "required": [
          "model",
          "authenticationRequired",
          "oauthAuthorizationServer",
          "scopesRequired",
          "documentation",
          "futureScopes"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "public_read_only"
          },
          "authenticationRequired": {
            "type": "boolean",
            "const": false
          },
          "oauthAuthorizationServer": {
            "type": [
              "string",
              "null"
            ],
            "description": "Authorization server metadata URL, or null while none is published."
          },
          "scopesRequired": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "futureScopes": {
            "type": "array",
            "description": "Scope names under review. Not grantable today.",
            "items": {
              "type": "object",
              "required": [
                "name",
                "description",
                "grantable"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "grantable": {
                  "type": "boolean",
                  "const": false
                }
              }
            }
          }
        }
      },
      "AgentRateLimit": {
        "type": "object",
        "description": "Published quota for the unauthenticated public agent surface.",
        "required": [
          "requestsPerWindow",
          "windowSeconds",
          "burst",
          "scope",
          "headers",
          "retryAfterOn429",
          "documentation"
        ],
        "properties": {
          "requestsPerWindow": {
            "type": "integer"
          },
          "windowSeconds": {
            "type": "integer"
          },
          "burst": {
            "type": "integer"
          },
          "scope": {
            "type": "string",
            "const": "client_ip"
          },
          "headers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "retryAfterOn429": {
            "type": "boolean"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "AgentOnboarding": {
        "type": "object",
        "description": "Facts an agent can check before deciding to integrate.",
        "required": [
          "zeroAuthAccess",
          "apiKeyRequired",
          "selfServeSignup",
          "freeTierAvailable",
          "pricing",
          "sandbox",
          "contactSalesRequired"
        ],
        "properties": {
          "zeroAuthAccess": {
            "type": "boolean"
          },
          "apiKeyRequired": {
            "type": "boolean"
          },
          "selfServeSignup": {
            "type": "string",
            "format": "uri"
          },
          "freeTierAvailable": {
            "type": "boolean"
          },
          "pricing": {
            "type": "string",
            "format": "uri"
          },
          "sandbox": {
            "type": "object",
            "required": [
              "available",
              "description",
              "baseUrl"
            ],
            "properties": {
              "available": {
                "type": "boolean"
              },
              "description": {
                "type": "string"
              },
              "baseUrl": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "contactSalesRequired": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "x-goalbadger-feature-key": "public_agent_access",
  "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."
  },
  "security": []
}