Repos & Spine

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

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

{
  "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

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

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

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

{
  "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

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

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

Response

{
  "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

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

Response

{
  "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

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

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

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

Response

{
  "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

# 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

{
  "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

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

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