Developers

specgit developer resources

specgit is GitHub-native docs collaboration, not a generic REST platform. Agents read public facts as Markdown, then use the review tools after a GitHub App sign-in. There are no self-serve API keys.

When to use specgit

Use specgit when the job is editing, commenting on, or publishing Markdown or HTML that already lives in a GitHub repository — or when a product team needs a visual editor whose saves are commits, comments are pull request review threads, and publish is a merge. Do not use specgit as a model API, a webhook hub, or a substitute for GitHub's own REST or GraphQL APIs.

Quickstart

Read product facts at /llms.txt.
Open the no-account sandbox at /try.
Sign in through the GitHub App — walkthrough at /auth.md. The session cookie is the credential.
Call GET https://specgit.com/api/agent/tools or POST JSON-RPC initialize to /api/agent.

Public surfaces

LLM index
Product facts, pricing, and when-to-use guidance. Prefer this over scraping HTML.
Full LLM context
One-file Markdown of the highest-authority public pages.
OpenAPI
Typed agent API for document review tools, including problem+json errors.
Agent auth
GitHub App sign-in. specgit has no API keys and no password. A session cookie is the credential.
MCP server
Streamable HTTP MCP at /api/agent. Discover the card at /.well-known/mcp.json. tools/call needs the session cookie.
Sandbox
The real editor on a sample document. No account required.

Agent tools

Authenticated agents call GET https://specgit.com/api/agent/tools or MCP tools/list. Mutating tools require an AI allowance; reads are free. The current tools:

read_document — Read a GitHub-hosted document's current source and metadata through specgit.
list_threads — List open and resolved PR review threads for a document, re-anchored to the current content.
create_comment — Create an anchored review thread on a line range in a GitHub-hosted document.
reply_thread — Reply to an existing review thread on a document.
resolve_thread — Resolve or reopen a review thread on a document.

Errors, versioning, and rate limits

Advertised agent endpoints use RFC 9457 application/problem+json with a machine-readable code, a human detail, and a hint. Unknown /api/* paths return HTTP 404 in that shape, not an HTML shell. Codes: unauthenticated, bad_request, not_found, method_not_allowed, rate_limited, upgrade_required, ai_budget, unknown_tool, internal, error.

The current major version is 1.0.0, echoed as API-Version on advertised agent endpoints (/api/agent, tools, invoke, and unknown/api/* 404s). Breaking changes ship a new major path. Those endpoints allow 60 requests per 60 seconds after a real limiter check, and send RateLimit, RateLimit-Policy, and Retry-After on 429.