All docs

Start here

API basics

SDK

CLI

MCP

Agent setups

Data pipeline

Webhooks

Webhooks

What's new

What's New

Repos & Spine

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

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

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"

Connect a Repo

Request Body

Example

Response 201 Created

List Repos

Query Parameters

Example

Get Repo

Path Parameters

Example

Submit a Repo Scan

Path Parameters

Request Body

Example

Response 201 Created

Get Latest Scan

Path Parameters

Example

Preview Install Patch Set

Path Parameters

Example

Response

Apply Install Patch Set

Path Parameters

Example

Response

Get Install Status

Path Parameters

Example

Rollback Install

Path Parameters

Example

List Streams

Path Parameters

Example

Response

Get Tracking Snippet

Path Parameters

Query Parameters

Example

Response

Search Knowledge Base

Path Parameters

Request Body

Example

List Knowledge Base Docs

Path Parameters

Example

Response `201 Created`

Response `201 Created`