# ScopeDocs API Documentation — Full Reference

ScopeDocs is a multi-source document and context aggregation platform with a heterogeneous RAG pipeline.
It unifies GitHub, Slack, Linear, and Supabase into one AI knowledge base for engineering
documentation, with source-linked docs and grounded answers tied to your live codebase and workflow.

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

---
title: Introduction
---

## What is ScopeDocs?

ScopeDocs unifies GitHub, Slack, Linear, and Supabase into one AI knowledge base for engineering
documentation. It generates source-linked docs and answers grounded in your live codebase and
workflow, giving your team a single source of truth that stays current as you build.

## The Public API

The ScopeDocs Public API (/api/v1) provides programmatic access to:
- Source-linked documentation — list, search, retrieve full content
- Knowledge graphs — nodes, relationships, and full graph data per repo
- Pull request context — synced from GitHub with AI explanations
- Grounded chat — ask questions about your codebase in natural language

---
title: Authentication
---

## API Keys

ScopeDocs API keys follow the format: sk-sd_{64 hex characters}
The full key is shown only once at creation — store it securely.

## Creating an API Key

1. Go to Settings → Organization in the ScopeDocs app (https://scopedocs.app/settings?tab=organization)
2. Open the API Key Management section (organization owner only)
3. Click "Create API Key"
4. Enter a name, select scopes, and optionally set expiry
5. Copy the key — shown only once

## Using Your Key

Option 1 — X-API-Key header (recommended):
  curl https://scopedocs-ai-production.up.railway.app/api/v1/docs -H "X-API-Key: sk-sd_your_key_here"

Option 2 — Bearer token:
  curl https://scopedocs-ai-production.up.railway.app/api/v1/docs -H "Authorization: Bearer sk-sd_your_key_here"

## Scopes

- docs:read — Read generated documentation (list, search, retrieve)
- graph:read — Access knowledge graphs (repos, nodes, full graph)
- prs:read — Read pull request data and AI-generated explanations
- chat — Use the RAG chat endpoint

---
title: Docs API
scope: docs:read
---

## GET /api/v1/docs

List paginated generated documentation.

Query parameters:
- repo (string, optional): Filter by repository full name, e.g. "acme/backend"
- limit (integer, optional, default 50, max 200): Max results to return
- offset (integer, optional, default 0): Pagination offset

Example:
  curl "https://scopedocs-ai-production.up.railway.app/api/v1/docs?limit=10" -H "X-API-Key: sk-sd_your_key_here"

Response:
{
  "docs": [
    {
      "id": "d1a2b3c4-...",
      "title": "Authentication Service Overview",
      "doc_type": "overview",
      "audience_type": "developer",
      "style": "technical",
      "repo_full_name": "acme/backend",
      "is_stale": false,
      "created_at": "2026-01-15T10:22:00Z",
      "updated_at": "2026-03-20T08:00:00Z"
    }
  ],
  "total": 47
}

## GET /api/v1/docs/search

Vector similarity search over generated documentation.

Query parameters:
- q (string, required): The search query (min 1 character)
- top_k (integer, optional, default 5, max 20): Number of results to return

Example:
  curl "https://scopedocs-ai-production.up.railway.app/api/v1/docs/search?q=authentication&top_k=5" -H "X-API-Key: sk-sd_your_key_here"

Response:
{
  "results": [
    {
      "id": "d1a2b3c4-...",
      "title": "Authentication Service Overview",
      "similarity": 0.91,
      "excerpt": "The authentication service handles JWT issuance...",
      "repo_full_name": "acme/backend"
    }
  ]
}

## GET /api/v1/docs/{doc_id}

Retrieve full content of a single generated documentation entry.

Path parameters:
- doc_id (string, required): UUID of the documentation entry

Example:
  curl "https://scopedocs-ai-production.up.railway.app/api/v1/docs/d1a2b3c4-e5f6-7890-abcd-ef1234567890" -H "X-API-Key: sk-sd_your_key_here"

Response:
{
  "id": "d1a2b3c4-...",
  "repo_full_name": "acme/backend",
  "doc_type": "overview",
  "audience_type": "developer",
  "style": "technical",
  "title": "Authentication Service Overview",
  "content": "# Authentication Service Overview\n\n...",
  "references": { "github_prs": ["acme/backend#42"], "linear_issues": ["ENG-101"] },
  "is_stale": false,
  "file_path": null,
  "created_at": "2026-01-15T10:22:00Z",
  "updated_at": "2026-03-20T08:00:00Z"
}

---
title: Knowledge Graph API
scope: graph:read
---

## GET /api/v1/graph/repos

List repository full names with indexed knowledge graph data.

Example:
  curl "https://scopedocs-ai-production.up.railway.app/api/v1/graph/repos" -H "X-API-Key: sk-sd_your_key_here"

Response:
{ "repos": ["acme/backend", "acme/frontend", "acme/infra"] }

## GET /api/v1/graph/node/{node_id}

Get a single knowledge graph node with relationships and linked docs.

Path parameters:
- node_id (string, required): Unique identifier of the graph node

Example:
  curl "https://scopedocs-ai-production.up.railway.app/api/v1/graph/node/node_abc123" -H "X-API-Key: sk-sd_your_key_here"

Response:
{
  "id": "node_abc123",
  "type": "function",
  "label": "authenticate_user",
  "repo_full_name": "acme/backend",
  "file_path": "backend/auth/jwt_auth.py",
  "metadata": { "language": "python", "lines": 45 },
  "linked_docs": ["d1a2b3c4-..."],
  "relationships": [
    { "type": "calls", "target_id": "node_def456" },
    { "type": "referenced_by", "target_id": "node_ghi789" }
  ]
}

## GET /api/v1/graph/{repo}

Full knowledge graph for a repository (all nodes and edges).

Path parameters:
- repo (string, required): Repository full name, e.g. "acme/backend" (supports slashes in path)

Example:
  curl "https://scopedocs-ai-production.up.railway.app/api/v1/graph/acme/backend" -H "X-API-Key: sk-sd_your_key_here"

Response:
{
  "nodes": [
    { "id": "node_abc123", "type": "function", "label": "authenticate_user" }
  ],
  "edges": [
    { "source": "node_abc123", "target": "node_def456", "type": "belongs_to" }
  ]
}

---
title: Pull Requests API
scope: prs:read
---

## GET /api/v1/prs/{repo}/{number}

Get pull request data with cached AI-generated explanation.

Path parameters:
- repo (string, required): Repository full name, e.g. "acme/backend"
- number (integer, required): PR number on GitHub

Example:
  curl "https://scopedocs-ai-production.up.railway.app/api/v1/prs/acme/backend/42" -H "X-API-Key: sk-sd_your_key_here"

Response:
{
  "pr": {
    "number": 42,
    "repo": "acme/backend",
    "title": "feat: add rate limiting to API endpoints",
    "body": "This PR adds per-key rate limiting using Redis.",
    "state": "merged",
    "author": "alice",
    "created_at": "2026-03-10T14:30:00Z",
    "merged_at": "2026-03-12T09:15:00Z"
  },
  "explanation": {
    "summary": "Adds per-API-key rate limiting (RPM + RPD) using Redis...",
    "files_changed": 8,
    "impact": "medium",
    "areas": ["authentication", "api", "infrastructure"]
  }
}

---
title: Chat API
scope: chat
---

## POST /api/v1/chat

Stateless single-turn RAG chat. Each request is independent — no conversation history is maintained.

Request body (JSON):
- message (string, required, 1-4000 chars): The user question
- type (string, required): "documentation" | "database" | "both"
- repo (string, optional): Filter retrieval to a single repository

Example:
  curl -X POST "https://scopedocs-ai-production.up.railway.app/api/v1/chat" \
    -H "X-API-Key: sk-sd_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"message": "How does authentication work?", "type": "documentation", "repo": "acme/backend"}'

Response:
{
  "answer": "The authentication service uses JWT tokens issued by Supabase Auth...",
  "sources": [
    {
      "id": "d1a2b3c4-...",
      "title": "Authentication Service Overview",
      "similarity": 0.92,
      "excerpt": "JWT issuance and validation is handled by..."
    }
  ],
  "db_result": null
}

For type "database" or "both", db_result contains:
{
  "rows": [...],
  "columns": [...],
  "row_count": 10,
  "truncated": false,
  "query_time_ms": 45,
  "answer": "Natural language summary of the DB results"
}