Managed Backend API¶

The Glassdocs managed backend at https://app.glassdocs.site is what the extension's default Managed (no key) mode talks to: an authenticating, budgeting, usage-metering reverse proxy in front of an OpenAI-compatible model provider, plus a small identity endpoint. You authenticate with a GitHub token — there is no Glassdocs API key or account — and the backend stores no prompt or completion text, only token counts for metering.

Authentication¶

Every request carries a GitHub token as a bearer credential:

Authorization: Bearer <github-token>

The backend verifies the token against GitHub on each request and discards it — no user tokens are stored server-side. The extension supplies the token from your GitHub sign-in automatically.

The API is browser-callable: CORS is enabled for GET, POST, and OPTIONS with the Authorization and Content-Type headers.

Error shape¶

All errors are JSON with the HTTP status carrying the semantics:

{ "error": "Invalid GitHub token" }

POST /v1/chat/completions¶

An OpenAI-compatible chat completion. Point any OpenAI-format client at https://app.glassdocs.site/v1 with the GitHub token in the API-key slot.

curl -sS https://app.glassdocs.site/v1/chat/completions \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Summarize this page for me." }
    ]
  }'

The response is a standard OpenAI-format chat completion, passed through from the provider.

What the backend enforces¶

The request body is OpenAI-format, but a few fields are controlled server-side:

• Model — the backend chooses the model (the operator-configured managed model, or your organization's configured model if it has a shared key). A model field in the request is overridden.
• No streaming — responses are returned complete; stream is forced off.
• Output clamp — max_tokens is capped at 8192 per request; multi-sample knobs (n, best_of, logprobs, top_logprobs) are dropped.

Who pays: org key or free tier¶

• If you belong to a GitHub organization whose admin configured a shared provider key (see Admin), that key and model are used. The org's own spend pays, and the free-tier caps below don't apply.
• Otherwise you're on the free tier: Glassdocs' key pays, gated by fair-use token caps — a per-user daily cap and a global daily circuit breaker. Caps reset at midnight UTC. Check your remaining budget with GET /api/me.

Responses¶

GET /api/me¶

Identity, tenant, and remaining free-tier budget for the token's user. The extension calls this to display who you are and how much free budget remains.

curl -sS https://app.glassdocs.site/api/me \
  -H "Authorization: Bearer $GITHUB_TOKEN"

Response:

{
  "login": "octocat",
  "tenant": null,
  "billing": "free",
  "orgs": ["your-org"],
  "budget": {
    "perUserDaily": 100000,
    "usedToday": 1234,
    "remaining": 98766
  }
}

The budget shown here is computed with the same defaults the /v1 enforcer uses, so what you see is what is enforced. When billing is "org" the free-tier numbers don't apply — your organization's key pays and Glassdocs enforces no cap.

Self-hosting¶

The backend is the same software whether Glassdocs hosts it or you do. The two endpoints above are the surface for the extension and API consumers; the server also exposes the admin/control-plane API used by the admin dashboard — GitHub OAuth sign-in plus /api/admin/org/... routes for org configuration, keys, access, and KB setup. A self-hosted deployment ships the full surface. Point the extension's Managed base URL (up to /v1) at your host, or push it to your whole organization via enterprise policy. See Hosting for the deployment options.

See also¶

• Extension — the primary client of this API
• Enterprise deployment — pointing every staff install at a hosted or self-hosted backend
• Admin — configuring an org shared key so members skip the free-tier caps
• Security — the identity model and what is (and isn't) stored

Knowledge-base read endpoints¶

Since the MCP server shipped, the admin read endpoints accept the same GitHub bearer token as everything above. They are how the MCP server works, and you can call them directly.

You must be an admin of the organization — the same check the dashboard applies.

GET /api/admin/org/{org}/kbs¶

Every KB registered for the organization.

curl -sS https://app.glassdocs.site/api/admin/org/your-org/kbs \
  -H "Authorization: Bearer $(gh auth token)"

{
  "org": "your-org",
  "count": 2,
  "kbs": [
    {
      "repo": "your-org/handbook",
      "name": "handbook",
      "cfProject": "your-org-handbook",
      "siteUrl": "https://your-org-handbook.pages.dev",
      "isArchived": false,
      "lastStatus": "success"
    }
  ]
}

GET /api/admin/org/{org}/kbs/docs¶

With ?repo= — the Markdown pages in that KB. Add &path= to read one page.

# list
curl -sS "https://app.glassdocs.site/api/admin/org/your-org/kbs/docs?repo=handbook" \
  -H "Authorization: Bearer $(gh auth token)"

# read one page
curl -sS "https://app.glassdocs.site/api/admin/org/your-org/kbs/docs?repo=handbook&path=docs/index.md" \
  -H "Authorization: Bearer $(gh auth token)"

Page content is read from your GitHub repo on each request and never stored by Glassdocs — the same passthrough guarantee as the rest of the control plane.

GET /api/admin/org/{org}/kbs/status¶

Live deploy status for every KB, straight from GitHub Actions. The lastStatus in the list endpoint comes from a cached crawl and can lag; this doesn't.