{
  "openapi": "3.1.1",
  "info": {
    "title": "Git Brain Agent Discovery HTTP API",
    "version": "1.0.0",
    "description": "Machine-readable discovery resources for Git Brain agents. This contract intentionally covers public website metadata only; Git Brain does not offer a supported third-party product REST API.",
    "contact": {
      "name": "Git Brain Support",
      "email": "support@git-brain-api.com",
      "url": "https://www.git-brain.com/contact"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://www.git-brain.com",
      "description": "Canonical production website"
    }
  ],
  "x-api-versioning": {
    "strategy": "request-header",
    "header": "Git-Brain-API-Version",
    "currentMajor": "1",
    "defaultWhenOmitted": "1",
    "policy": "https://www.git-brain.com/api-policy.md"
  },
  "x-deprecation-policy": {
    "status": "No operations are currently deprecated.",
    "minimumNoticeDays": 180,
    "policy": "https://www.git-brain.com/api-policy.md",
    "signals": ["Deprecation", "Sunset", "Link"]
  },
  "tags": [
    {
      "name": "Agent discovery",
      "description": "Public resources that help agents discover, interpret, and navigate Git Brain content."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getGitBrainHomepage",
        "summary": "Get the Git Brain homepage",
        "description": "Returns the visual HTML homepage by default. When the request prefers `text/markdown`, returns the concise `llms.txt` agent representation from the same canonical URL.",
        "tags": ["Agent discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "$ref": "#/components/parameters/AcceptNegotiatedContent"
          }
        ],
        "responses": {
          "200": {
            "description": "The representation selected from the request's Accept header.",
            "headers": {
              "Vary": {
                "$ref": "#/components/headers/VaryAccept"
              },
              "Git-Brain-API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "Link": {
                "$ref": "#/components/headers/DeprecationLink"
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "$ref": "#/components/schemas/HtmlDocument"
                }
              },
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                },
                "example": "# Git Brain\n\n> Git Brain brings JetBrains-style visual Git workflows to VS Code-compatible IDEs."
              }
            }
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getGitBrainAgentSummary",
        "summary": "Get concise agent context",
        "description": "Returns the concise Git Brain product summary and authoritative links following the llms.txt convention.",
        "tags": ["Agent discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "Concise Git Brain agent context.",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getGitBrainFullAgentContext",
        "summary": "Get comprehensive agent context",
        "description": "Returns detailed product, workflow, support, troubleshooting, release, and public-interface context for agents.",
        "tags": ["Agent discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "Comprehensive Git Brain agent context.",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getGitBrainSitemap",
        "summary": "Get the public site map",
        "description": "Returns the canonical, indexable Git Brain page inventory using the Sitemaps XML protocol.",
        "tags": ["Agent discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The current public URL inventory.",
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/SitemapDocument"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getGitBrainOpenApiDescription",
        "summary": "Get this OpenAPI description",
        "description": "Returns the self-describing OpenAPI 3.1 document for Git Brain's public agent-discovery HTTP surface.",
        "tags": ["Agent discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The current Git Brain agent-discovery OpenAPI description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDescription"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/api-policy.md": {
      "get": {
        "operationId": "getGitBrainApiPolicy",
        "summary": "Get the discovery API lifecycle policy",
        "description": "Returns the versioning, deprecation, sunset, and rate-limit conventions for Git Brain's public agent-discovery surface.",
        "tags": ["Agent discovery"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The current discovery API lifecycle policy.",
            "headers": {
              "Git-Brain-API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "Link": {
                "$ref": "#/components/headers/DeprecationLink"
              }
            },
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "400": {
            "$ref": "#/components/responses/UnsupportedApiVersion"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ApiVersion": {
        "name": "Git-Brain-API-Version",
        "in": "header",
        "required": false,
        "description": "Requested discovery API major version. Omission currently selects version 1; unsupported values receive a structured 400 response.",
        "schema": {
          "type": "string",
          "enum": ["1"],
          "default": "1"
        }
      },
      "AcceptNegotiatedContent": {
        "name": "Accept",
        "in": "header",
        "required": false,
        "description": "Preferred response media types. Quality values are honored. Use `text/markdown` for agent-optimized content or `text/html` for the visual page.",
        "schema": {
          "type": "string",
          "examples": ["text/markdown, text/html;q=0.8", "text/html"]
        }
      }
    },
    "headers": {
      "ApiVersion": {
        "description": "The discovery API major version used for the response.",
        "schema": {
          "type": "string",
          "const": "1"
        }
      },
      "RateLimitPolicy": {
        "description": "Current HTTPAPI structured field describing the named quota and window in seconds.",
        "schema": {
          "type": "string",
          "example": "\"public-discovery\";q=600;w=60"
        }
      },
      "RateLimit": {
        "description": "Current HTTPAPI structured field reporting the named policy's remaining quota and reset interval in seconds.",
        "schema": {
          "type": "string",
          "example": "\"public-discovery\";r=599;t=60"
        }
      },
      "RateLimitLimitCompatibility": {
        "description": "Compatibility alias for the 600-request quota used by clients implementing earlier HTTPAPI drafts.",
        "schema": {
          "type": "integer",
          "const": 600
        }
      },
      "RateLimitRemainingCompatibility": {
        "description": "Compatibility alias for the remaining request count used by clients implementing earlier HTTPAPI drafts.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimitResetCompatibility": {
        "description": "Compatibility alias for the seconds until reset used by clients implementing earlier HTTPAPI drafts.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 60
        }
      },
      "Deprecation": {
        "description": "RFC 9745 structured date. Present only after this operation or version is deprecated.",
        "schema": {
          "type": "string",
          "example": "@1806537600"
        }
      },
      "Sunset": {
        "description": "RFC 8594 HTTP-date. Present only when removal has been scheduled.",
        "schema": {
          "type": "string",
          "example": "Tue, 30 Jun 2027 23:59:59 GMT"
        }
      },
      "DeprecationLink": {
        "description": "RFC 8288 link to the published lifecycle policy using the RFC 9745 deprecation relation.",
        "schema": {
          "type": "string",
          "const": "</api-policy.md>; rel=\"deprecation\"; type=\"text/markdown\""
        }
      },
      "RetryAfter": {
        "description": "Seconds until a rate-limited client should retry.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "VaryAccept": {
        "description": "Signals that cached representations vary by Accept and Accept-Encoding.",
        "schema": {
          "type": "string",
          "const": "Accept, Accept-Encoding"
        }
      }
    },
    "responses": {
      "MethodNotAllowed": {
        "description": "The public discovery resource only supports GET and HEAD.",
        "headers": {
          "Allow": {
            "description": "Methods supported by public discovery resources.",
            "schema": {
              "type": "string",
              "const": "GET, HEAD"
            }
          },
          "Git-Brain-API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AgentError"
            }
          }
        }
      },
      "UnsupportedApiVersion": {
        "description": "The requested discovery API major version is unsupported.",
        "headers": {
          "Git-Brain-API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "Link": {
            "$ref": "#/components/headers/DeprecationLink"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AgentError"
            },
            "example": {
              "error": "UNSUPPORTED_API_VERSION",
              "message": "Git Brain discovery API version 2 is not supported.",
              "resolution": "Send Git-Brain-API-Version: 1, or omit the header to use the current version. See /api-policy.md."
            }
          }
        }
      },
      "NotAcceptable": {
        "description": "None of the available representations are acceptable according to the request header.",
        "headers": {
          "Vary": {
            "$ref": "#/components/headers/VaryAccept"
          }
        }
      },
      "TooManyRequests": {
        "description": "The per-client edge-partition discovery quota was exhausted.",
        "headers": {
          "Git-Brain-API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Link": {
            "$ref": "#/components/headers/DeprecationLink"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AgentError"
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested public resource does not exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AgentError"
            },
            "example": {
              "error": "NOT_FOUND",
              "message": "The requested Git Brain resource does not exist.",
              "resolution": "See /openapi.json, /llms.txt, or /sitemap.xml for supported resources."
            }
          },
          "text/markdown": {
            "schema": {
              "$ref": "#/components/schemas/MarkdownDocument"
            }
          },
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/HtmlDocument"
            }
          }
        }
      }
    },
    "schemas": {
      "AgentError": {
        "type": "object",
        "description": "A structured error with a stable machine code and a recovery hint.",
        "additionalProperties": false,
        "required": ["error", "message", "resolution"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable error code suitable for branching logic.",
            "enum": [
              "NOT_FOUND",
              "NOT_ACCEPTABLE",
              "RATE_LIMITED",
              "UNSUPPORTED_API_VERSION",
              "METHOD_NOT_ALLOWED"
            ]
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "description": "Human-readable explanation of the failure."
          },
          "resolution": {
            "type": "string",
            "minLength": 1,
            "description": "Specific next step an agent can take to recover."
          },
          "retryAfterSeconds": {
            "type": "integer",
            "minimum": 1,
            "description": "Delay before retrying a rate-limited request; present for RATE_LIMITED errors."
          }
        }
      },
      "HtmlDocument": {
        "type": "string",
        "description": "A complete UTF-8 HTML document.",
        "contentMediaType": "text/html"
      },
      "MarkdownDocument": {
        "type": "string",
        "description": "A UTF-8 Markdown document.",
        "contentMediaType": "text/markdown"
      },
      "SitemapDocument": {
        "type": "string",
        "description": "A UTF-8 XML sitemap conforming to sitemaps.org protocol 0.9.",
        "contentMediaType": "application/xml",
        "contentSchema": {
          "type": "object"
        }
      },
      "OpenApiDescription": {
        "type": "object",
        "description": "An OpenAPI 3.1 document describing the public Git Brain agent-discovery interface.",
        "required": ["openapi", "info", "paths"],
        "properties": {
          "openapi": {
            "type": "string",
            "pattern": "^3\\.1\\.[0-9]+$"
          },
          "info": {
            "type": "object"
          },
          "paths": {
            "type": "object"
          },
          "components": {
            "type": "object"
          }
        },
        "additionalProperties": true
      }
    }
  },
  "externalDocs": {
    "description": "Git Brain developer resources and public interface boundaries",
    "url": "https://www.git-brain.com/developers"
  }
}