# BibiGPT API — Agent Reference

> Scoped llms.txt for BibiGPT's API surface. Pair with /llms.txt (product) and /llms-full.txt (deep context).

BibiGPT exposes 4 ways for agents to integrate:

1. **MCP** (recommended) — Streamable HTTP, OAuth2 + Bearer
2. **REST OpenAPI** — tRPC-derived OpenAPI 3 spec
3. **NLWeb /ask** — Natural-language Q&A with optional SSE
4. **CLI / Anthropic Skill** — `npx skills add JimmyLv/bibigpt-skill`

---

## 1. MCP — Model Context Protocol

- **Endpoint**: https://bibigpt.co/api/mcp
- **Transport**: Streamable HTTP (`POST` for JSON-RPC, `GET` for SSE responses, `DELETE` for session close)
- **Discovery**: https://bibigpt.co/.well-known/mcp.json
- **Server card**: https://bibigpt.co/.well-known/mcp/server-card.json
- **OAuth metadata**: https://bibigpt.co/.well-known/oauth-authorization-server (RFC 8414)
- **PKCE**: S256 supported
- **Auth modes**: OAuth2 authorization_code, Bearer token, Anonymous (discovery-only)

### Tools

| Tool | Read-only | Idempotent | Description |
|---|---|---|---|
| summarize_video | yes | yes | Summarize a public video/audio URL |
| summarize_video_with_config | yes | yes | Summarize with prompt/lang/model overrides |
| summarize_by_chapter | yes | yes | Long-video chapter-by-chapter breakdown |
| get_subtitle | yes | yes | Full transcript with timestamps |
| create_summary_task | no | yes | Async job for long content; returns task_id |
| get_task_status | yes | yes | Poll status / fetch async result |

---

## 2. REST OpenAPI

- **Spec**: https://bibigpt.co/api/openapi.json (OpenAPI 3.0)
- **Spec (legacy ChatGPT plugin)**: https://bibigpt.co/ai/openapi.yaml (OpenAPI 3.0.1)
- **Auth**: `Authorization: Bearer <token>` from https://bibigpt.co/dashboard/api
- **Operation IDs**: snake_case, function-calling compatible (LLMs can call them as tools)
- **Versioning**: `/v1/*` paths; breaking changes will roll out under `/v2/*` with deprecation notice

Major endpoint groups:

- `/v1/library/*` — saved videos & playlists
- `/v1/notes/*` — user notes & highlights
- `/v1/agent/*` — agent-native helpers
- `/v1/summary/*` — direct summarization

---

## 3. NLWeb /ask

- **Endpoint**: `POST https://bibigpt.co/api/ask`
- **Spec**: https://github.com/microsoft/NLWeb
- **Body**: `{ "question": "string", "prefer": { "streaming": boolean }, "context"?: { "url"?: "string" } }`
- **Sync response**: `{ "_meta": { "response_type": "answer", "version": "0.1", "engine": "bibigpt" }, "answer": "...", "sources": [...] }`
- **Streaming response** (when `prefer.streaming: true` or `Accept: text/event-stream`):
  - `event: start` — initial `_meta`
  - `event: result` — incremental answer chunks
  - `event: complete` — final `_meta` + sources

---

## 4. CLI / Anthropic Skill

- **Install (GitHub direct)**: `npx skills add JimmyLv/bibigpt-skill`
- **Install (skills.sh registry)**: `npx skills add https://github.com/jimmylv/bibigpt-skill --skill bibi`
- **skills.sh registry page**: https://skills.sh/jimmylv/bibigpt-skill/bibi (953 installs · 73 GitHub stars · Gen Agent Trust Hub Pass · Socket Pass)
- **Local skill registry**: https://bibigpt.co/.well-known/agent-skills/index.json
- **Sha256-pinned archive**: https://github.com/JimmyLv/bibigpt-skill/archive/refs/heads/main.zip
- **Compatible**: Claude Code, OpenClaw, Codex, any agent supporting Anthropic Skills

---

## Discovery Snapshot — One Call to Find Everything

```bash
curl https://bibigpt.co/api/discover
```

Returns JSON with all agent entry points:

```json
{
  "name": "BibiGPT",
  "version": "1.0.0",
  "endpoints": {
    "mcp": "https://bibigpt.co/api/mcp",
    "openapi": "https://bibigpt.co/api/openapi.json",
    "nlweb_ask": "https://bibigpt.co/api/ask",
    "agent_card": "https://bibigpt.co/.well-known/agent-card.json",
    "agent_skills": "https://bibigpt.co/.well-known/agent-skills/index.json",
    "ai_plugin": "https://bibigpt.co/.well-known/ai-plugin.json",
    "oauth_metadata": "https://bibigpt.co/.well-known/oauth-authorization-server",
    "api_catalog": "https://bibigpt.co/.well-known/api-catalog",
    "llms_txt": "https://bibigpt.co/llms.txt",
    "llms_full": "https://bibigpt.co/llms-full.txt",
    "pricing": "https://bibigpt.co/pricing.md",
    "homepage_md": "https://bibigpt.co/index.md"
  }
}
```

---

## Rate Limits

- Anonymous: 5 req/min per IP
- Free auth: 10 req/min
- Plus: 30 req/min
- Pro / Lifetime: 60 req/min

429 response includes `Retry-After` header. `X-RateLimit-{Limit, Remaining, Reset}` headers expose budget.

---

## Error Format (JSON-RPC for MCP, RFC 7807 for REST)

### MCP
```json
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params: missing url", "data": { "field": "url" } } }
```

### REST
```json
{ "type": "https://bibigpt.co/errors/rate-limit", "title": "Rate limit exceeded", "status": 429, "detail": "60 req/min limit reached", "instance": "/v1/summary" }
```

---

## SDK Status

- **npm**: `@bibigpt/sdk` (TypeScript) — current
- **PyPI**: planned
- **Go modules**: planned
- **RubyGems**: planned

For now, agents on non-JS stacks should use the OpenAPI spec directly with their language's HTTP client + JSON parser.

---

## Changelog

See https://bibigpt.co/changelog.md for API changelog (date-tagged, semver-linked).

---

Last updated: 2026-05-09 · Maintainer: JimmyLv · Issues: https://github.com/JimmyLv/bibigpt-skill/issues