# Repos & Spine

> Connect repositories, run scans, install tracking, manage patch sets, and search the per-repo knowledge base via the graph8 Developer API.

Source: https://docs.graph8.com/developers/cli-spine/

> **Tip: What is Spine?**
> The Spine surface lets you connect a code repository to graph8, scan its tech stack and API routes, install the graph8 tracking snippet, manage patch sets (with rollback), and search the per-repo knowledge base — all programmatically.

Use the endpoints below to automate repo onboarding, CI-driven installs, and knowledge base lookups inside your own tooling or agents.

---

## Connect a Repo

`POST /repos`

Register a new code repository with graph8. Returns `201 Created` with the full repo record.

### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `repo_url` | string | **Yes** | — | Full URL of the repository (e.g. `https://github.com/org/repo`) |
| `repo_name` | string | **Yes** | — | Human-readable name for the repo (e.g. `my-app`) |
| `provider` | string | No | `"github"` | Source control provider — `github`, `gitlab`, or `local` |
| `default_branch` | string | No | `"main"` | Default branch name |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/repos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/org/repo",
    "repo_name": "my-app",
    "provider": "github",
    "default_branch": "main"
  }'
```

### Response `201 Created`

```json
{
  "data": {
    "id": "uuid",
    "repo_url": "https://github.com/org/repo",
    "repo_name": "my-app",
    "provider": "github",
    "default_branch": "main",
    "scan_status": "pending",
    "install_status": "pending",
    "project_id": null,
    "write_key": null,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
}
```

---

## List Repos

`GET /repos`

Returns a paginated list of connected repositories.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | `1` | Page number (1-indexed) |
| `limit` | integer | `50` | Items per page |

### Example

**cURL**

```bash
curl "https://be.graph8.com/api/v1/repos?page=1&limit=50" \
  -H "Authorization: Bearer $API_KEY"
```

---

## Get Repo

`GET /repos/{repo_id}`

Returns the full `RepoResponse` for a single connected repository.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl "https://be.graph8.com/api/v1/repos/uuid" \
  -H "Authorization: Bearer $API_KEY"
```

---

## Submit a Repo Scan

`POST /repos/{repo_id}/scan`

Upload the results of a local repo scan. graph8 stores this data and uses it to generate install patches and populate the knowledge base. Returns `201 Created`.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `tech_stack` | object | **Yes** | — | Tech stack descriptor, e.g. `{"framework": "next", "language": "ts"}` |
| `api_routes` | array | No | `[]` | List of detected API route objects, each with `path` (string) and `method` (string) |
| `readme_summary` | string | No | — | Plain-text summary extracted from the README |
| `product_type` | string | No | — | Product category (e.g. `b2b_saas`) |
| `gtm_readiness` | object | No | `{}` | Go-to-market readiness signals (e.g. `{"has_pricing_page": true}`) |
| `scan_duration_ms` | integer | No | — | Time in milliseconds the local scan took |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/repos/uuid/scan" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": { "framework": "next", "language": "ts" },
    "api_routes": [{ "path": "/api/users", "method": "GET" }],
    "readme_summary": "A B2B SaaS app built with Next.js.",
    "product_type": "b2b_saas",
    "gtm_readiness": { "has_pricing_page": true },
    "scan_duration_ms": 1234
  }'
```

### Response `201 Created`

```json
{
  "data": {
    "id": "uuid",
    "repo_id": "uuid",
    "tech_stack": { "framework": "next", "language": "ts" },
    "api_routes": [{ "path": "/api/users", "method": "GET" }],
    "readme_summary": "A B2B SaaS app built with Next.js.",
    "product_type": "b2b_saas",
    "gtm_readiness": { "has_pricing_page": true },
    "scan_duration_ms": 1234,
    "created_at": "2026-01-15T10:05:00Z"
  }
}
```

---

## Get Latest Scan

`GET /repos/{repo_id}/scan`

Returns the most recent scan result for a repository.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl "https://be.graph8.com/api/v1/repos/uuid/scan" \
  -H "Authorization: Bearer $API_KEY"
```

---

## Preview Install Patch Set

`POST /repos/{repo_id}/install`

Generate a preview patch set for installing the graph8 tracking layer into the repo. No body required. Returns the patch set in `PREVIEW` status — patches are not applied yet.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/repos/uuid/install" \
  -H "Authorization: Bearer $API_KEY"
```

### Response

```json
{
  "data": {
    "id": "uuid",
    "repo_id": "uuid",
    "status": "PREVIEW",
    "patches": [
      {
        "file_path": "app/layout.tsx",
        "action": "modify",
        "description": "Inject graph8 analytics provider",
        "diff": "...",
        "content": "..."
      }
    ],
    "applied_at": null,
    "rolled_back_at": null,
    "created_at": "2026-01-15T10:10:00Z"
  }
}
```

Each item in `patches` has:

| Field | Type | Description |
|-------|------|-------------|
| `file_path` | string | Relative path of the file to create or modify |
| `action` | string | `"create"` or `"modify"` |
| `description` | string | Human-readable summary of the change |
| `diff` | string | Unified diff of the change |
| `content` | string | Full file content after the patch |

---

## Apply Install Patch Set

`POST /repos/{repo_id}/install/apply`

Commit the previewed patch set. No body required. Sets the patch set status to `applied`.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/repos/uuid/install/apply" \
  -H "Authorization: Bearer $API_KEY"
```

### Response

```json
{
  "data": {
    "status": "applied",
    "patch_count": 5
  }
}
```

---

## Get Install Status

`GET /repos/{repo_id}/install/status`

Returns the latest `PatchSetResponse` for a repository, reflecting the current install state.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl "https://be.graph8.com/api/v1/repos/uuid/install/status" \
  -H "Authorization: Bearer $API_KEY"
```

---

## Rollback Install

`POST /repos/{repo_id}/rollback`

Roll back the most recently applied patch set. No body required. Returns the rolled-back `PatchSetResponse`.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/repos/uuid/rollback" \
  -H "Authorization: Bearer $API_KEY"
```

---

## List Streams

`GET /repos/{repo_id}/streams`

List the analytics streams associated with a repository. Each stream has a `write_key` used for tracking.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl "https://be.graph8.com/api/v1/repos/uuid/streams" \
  -H "Authorization: Bearer $API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "uuid",
      "name": "graph8.com",
      "domains": ["graph8.com"],
      "write_key": "wk_..."
    }
  ]
}
```

---

## Get Tracking Snippet

`GET /repos/{repo_id}/snippet`

Return the ready-to-paste tracking snippet for a repository, including a React component import and a plain `<script>` tag.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `stream_id` | string | — | Stream ID to use for the snippet. Required if the repo has no stored write key. |

### Example

**cURL**

```bash
# Repo already has a stored write key
curl "https://be.graph8.com/api/v1/repos/uuid/snippet" \
  -H "Authorization: Bearer $API_KEY"

# Specify a stream explicitly
curl "https://be.graph8.com/api/v1/repos/uuid/snippet?stream_id=stream-uuid" \
  -H "Authorization: Bearer $API_KEY"
```

### Response

```json
{
  "data": {
    "write_key": "wk_...",
    "tracking_host": "https://t.graph8.com",
    "domains": ["graph8.com"],
    "react_snippet": "import { G8Analytics } from '@graph8/nextjs'\n...",
    "script_tag": "<script src=\"https://t.graph8.com/p.js\" data-write-key=\"wk_...\" data-tracking-host=\"https://t.graph8.com\" defer></script>",
    "config": {
      "write_key": "wk_...",
      "tracking_host": "https://t.graph8.com",
      "project_id": "uuid",
      "domains": ["graph8.com"]
    }
  }
}
```

---

## Search Knowledge Base

`POST /repos/{repo_id}/kb/search`

Semantic search over the per-repo knowledge base that graph8 builds from your scan results and installed documentation.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | **Yes** | Natural-language search query |
| `limit` | integer | No | Number of results to return — `1` to `50`, default `10` |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/repos/uuid/kb/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does authentication work",
    "limit": 10
  }'
```

---

## List Knowledge Base Docs

`GET /repos/{repo_id}/kb`

Returns a list of knowledge base documents for a repository, grouped by section.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `repo_id` | string (UUID) | Repository ID |

### Example

**cURL**

```bash
curl "https://be.graph8.com/api/v1/repos/uuid/kb" \
  -H "Authorization: Bearer $API_KEY"
```