Goalbadger Developer & Agent Resources

Goalbadger is an AI-powered goal-execution operating system with a mentor layer. This page is the canonical public index for developers and AI agents looking for Goalbadger's machine-readable interfaces.

Public agent API

The current public API is read-only, zero-auth, and contains no private user or tenant data.

Runtime REST and MCP access is governed by Goalbadger's platform capability public_agent_access_v1. It ships available by default but can be disabled through Platform Rollout without exposing or changing private product data. When disabled, REST endpoints return HTTP 503 with application/problem+json and code public_agent_access_disabled; MCP returns the equivalent machine-readable JSON-RPC transport error. Static discovery documents remain readable so clients can understand the availability contract.

All public API errors use application/problem+json with a stable code, human-readable detail, and a resolution hint.

Model Context Protocol (MCP)

Goalbadger exposes a stateless, public Streamable HTTP MCP endpoint:

The public server advertises resources and tools. Both are read-only.

MCP 2026 lifecycle

MCP 2026-07-28 is stateless. It does not use the old initialize / initialized handshake or protocol sessions. A modern client may call server/discover first, or call a supported RPC directly.

Every modern HTTP request must:

Example discovery request:

POST /mcp HTTP/1.1
Host: goalbadger.app
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover

{"jsonrpc":"2.0","id":"discover-1","method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"example-client","version":"1.0.0"}}}}

Goalbadger validates the mirrored transport headers against the request body. Header/body disagreement is rejected with MCP HeaderMismatch (-32020). An unsupported modern protocol version is rejected with UnsupportedProtocolVersion (-32022) and a supported-version list.

Legacy 2025 clients may continue to use initialize; that compatibility path is separate from the modern stateless lifecycle.

initialize negotiates rather than failing. A client that echoes back the 2026-07-28 version advertised in the manifest receives a successful result carrying the newest legacy version the server speaks (2025-11-25), per the MCP lifecycle. UnsupportedProtocolVersion (-32022) is reserved for non-initialize calls that pin an unsupported version in the MCP-Protocol-Version header.

Because the public server is stateless and always answers with a single JSON body — it never upgrades to an SSE stream — a client advertising only Accept: application/json is served normally.

Public MCP resources

Each resource returned by resources/list has mimeType: text/markdown and returns non-empty Markdown from resources/read.

Public MCP tools

All three tools are explicitly read-only, non-destructive, and idempotent.

Rate limits

The public agent surface is unauthenticated, so quota is tracked per client IP.

The same quota applies to POST /mcp. Machine-readable values live at GET /api/agent/v1/capabilities under rateLimit.

Versioning and deprecation

Markdown content negotiation

The canonical homepage supports the same-URL Markdown convention. Send:

GET / HTTP/1.1
Host: goalbadger.app
Accept: text/markdown

A successful Markdown representation returns Content-Type: text/markdown; charset=utf-8 and a Vary header containing Accept so CDN caches do not mix HTML and Markdown representations.

Discovery

The homepage also publishes HTTP Link relations for the sitemap, Markdown representation, developer catalog, OpenAPI description, MCP description, and llms.txt.

Authentication and private data

Goalbadger does not currently advertise a public OAuth authorization server for private product data. Existing Google, LinkedIn, and other OAuth flows in Goalbadger are connector/client flows; they are not an authorization server for third-party agents.

RFC 9728 protected-resource metadata is published at https://goalbadger.app/.well-known/oauth-protected-resource. It describes the current state honestly: scopes_supported and authorization_servers are both empty, because the public agent API requires no scope and there is no authorization server to point at. The public OpenAPI document says the same thing with an empty security requirement.

Accordingly, the public OpenAPI document intentionally does not publish OAuth scopes that cannot yet be granted. Private Goal Maps, tasks, blockers, evidence, mentor rooms, tenant data, user records, role changes, billing state, and execution mutations remain unavailable through the public agent API.

A future authenticated agent API must preserve Goalbadger's architecture invariants:

  1. Least-privilege OAuth scopes are machine-readable and explicitly granted.
  2. Tenant and workspace authorization is enforced server-side.
  3. Reads are limited to the authenticated user's permitted execution context.
  4. Agent- or AI-originated changes are proposals unless a canonical deterministic product authority accepts them.
  5. Role, entitlement, billing, membership, and execution truth cannot be granted or changed by an agent merely because a UI or feature flag permits it.
  6. Security-sensitive operations are auditable.

Candidate future scopes for security/product review include goals:read, progress:read, mentoring:read, and execution:propose. They are not active OAuth scopes today, and are published machine-readably at GET /api/agent/v1/capabilities under authorization.futureScopes, each carrying grantable: false.

Getting started

No signup, key, or sales conversation is needed to call the public agent API:

curl https://goalbadger.app/api/agent/v1/capabilities

Because the surface is read-only and returns the same stable resources everywhere, it doubles as its own sandbox — there is no separate test host or test credential to request. Goalbadger's product itself has a free tier; see https://goalbadger.app/pricing and sign in at https://goalbadger.app/login.

Error codes

public_agent_access_disabled

Runtime public agent access is disabled by Goalbadger platform rollout policy. Retry after the platform capability is enabled; REST responses include a Retry-After hint.

agent_resource_not_found

The requested public resource id does not exist. List https://goalbadger.app/api/agent/v1/resources and retry with a returned id.

agent_endpoint_not_found

The requested public agent API endpoint does not exist. This includes the exact /api/agent/v1 base path. Read https://goalbadger.app/openapi.json for supported operations.

mcp_header_mismatch

Required MCP 2026 transport metadata is missing or does not match the JSON-RPC body. Correct the MCP-Protocol-Version, Mcp-Method, and where required Mcp-Name headers and retry.

mcp_method_not_allowed

The public MCP transport accepts JSON-RPC messages by POST. MCP 2026 has no standalone GET stream or DELETE session endpoint.

Contact

Product and integration questions: https://goalbadger.app/contact

This page renders developers.md, the Markdown source agents read directly.