# ScopeDocs API Documentation

ScopeDocs is an AI knowledge base for engineering documentation.
It unifies GitHub, Slack, Linear, and Supabase into a single source of truth with source-linked docs and grounded answers.

API Base URL: https://scopedocs-ai-production.up.railway.app
Documentation: https://guide.scopedocs.app

## Authentication

All API requests require an API key.
Pass the key via X-API-Key header or Authorization: Bearer header.
API keys are prefixed with `sk-sd_` followed by 64 hex characters.
Keys are created in Settings > Organization > API Key Management (organization owner only).

Available scopes: docs:read, graph:read, prs:read, chat

## Documentation Pages

### Getting Started

- [Introduction](https://guide.scopedocs.app/getting-started/introduction)
- [Authentication](https://guide.scopedocs.app/getting-started/authentication)
- [Quick Start](https://guide.scopedocs.app/getting-started/quick-start)
- [MCP Server](https://guide.scopedocs.app/getting-started/mcp-server)

### API Reference

- [Docs API](https://guide.scopedocs.app/api-reference/docs-api)
- [Knowledge Graph API](https://guide.scopedocs.app/api-reference/graph-api)
- [Pull Requests API](https://guide.scopedocs.app/api-reference/prs-api)
- [Chat API](https://guide.scopedocs.app/api-reference/chat-api)

## API Endpoints

### Docs API (scope: docs:read)

- GET https://scopedocs-ai-production.up.railway.app/api/v1/docs — List generated docs. Query: repo?, limit (default 50, max 200), offset
- GET https://scopedocs-ai-production.up.railway.app/api/v1/docs/search — Vector search. Query: q (required), top_k (default 5, max 20)
- GET https://scopedocs-ai-production.up.railway.app/api/v1/docs/{doc_id} — Get full doc content by UUID

### Knowledge Graph API (scope: graph:read)

- GET https://scopedocs-ai-production.up.railway.app/api/v1/graph/repos — List repos with indexed graph data
- GET https://scopedocs-ai-production.up.railway.app/api/v1/graph/node/{node_id} — Get single graph node with relationships
- GET https://scopedocs-ai-production.up.railway.app/api/v1/graph/{repo} — Full knowledge graph for a repo (nodes + edges)

### Pull Requests API (scope: prs:read)

- GET https://scopedocs-ai-production.up.railway.app/api/v1/prs/{repo}/{number} — Get PR data + AI-generated explanation

### Chat API (scope: chat)

- POST https://scopedocs-ai-production.up.railway.app/api/v1/chat — Stateless RAG chat. Body: { message, type: "documentation"|"database"|"both", repo? }

## Error Codes

- 401 Unauthorized — Missing or invalid API key
- 403 Forbidden — Valid key but missing required scope
- 404 Not Found — Resource not found
- 429 Too Many Requests — Rate limit exceeded (check Retry-After header)
- 500 Internal Server Error — Server error