Connect Repository

curl --request POST \
  --url https://api.example.com/api/v1/repos/{owner}/{repo}/install

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/repos/{owner}/{repo}/install', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/repos/{owner}/{repo}/install",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/repos/{owner}/{repo}/install"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/repos/{owner}/{repo}/install")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "status": "<string>",
  "installation_id": 123,
  "repo": "<string>"
}

POST

api

repos

{owner}

{repo}

install

Connect Repository

curl --request POST \
  --url https://api.example.com/api/v1/repos/{owner}/{repo}/install

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/repos/{owner}/{repo}/install', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/repos/{owner}/{repo}/install",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/repos/{owner}/{repo}/install"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/repos/{owner}/{repo}/install")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "status": "<string>",
  "installation_id": 123,
  "repo": "<string>"
}

Overview

Connects a repository to Nectr AI by installing a webhook and initiating background tasks to scan the repository structure and build a code knowledge graph. This is a one-click operation that uses the user’s existing OAuth token (with repo scope) - no GitHub redirect required.

Authentication

Requires a valid JWT token in the Authorization header.

Authorization: Bearer <token>

Path Parameters

string

required

Repository owner (user or organization)

string

required

Repository name

Request

curl -X POST "https://api.nectr.ai/api/v1/repos/acme/my-backend/install" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

import httpx

headers = {
    "Authorization": "Bearer YOUR_JWT_TOKEN"
}

response = httpx.post(
    "https://api.nectr.ai/api/v1/repos/acme/my-backend/install",
    headers=headers
)
result = response.json()

const response = await fetch(
  'https://api.nectr.ai/api/v1/repos/acme/my-backend/install',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    }
  }
);

const result = await response.json();

Response

string

Always returns "connected" on success

integer

Database ID of the newly created installation record

string

Full repository name in owner/repo format

Example Response

{
  "status": "connected",
  "installation_id": 42,
  "repo": "acme/my-backend"
}

What Happens During Connection

1. Webhook Installation

A GitHub webhook is created on the repository with:

Events: pull_request, issues
Payload URL: {BACKEND_URL}/api/v1/webhooks/github
Secret: Randomly generated 64-character hex string
Content type: JSON

The webhook ID and secret are stored in the Installation record for later verification and cleanup.

2. Database Record Creation

An Installation record is persisted with:

{
  "user_id": current_user.id,
  "repo_full_name": "owner/repo",
  "webhook_id": 123456,
  "webhook_secret": "...",
  "is_active": True
}

3. Background Tasks (Async)

Two tasks are queued in the background: Project Scanner (scan_repo):

Fetches the repository file tree from GitHub
Analyzes project structure and dependencies
Identifies language, framework, and key files

Graph Builder (build_repo_graph):

Creates a Neo4j knowledge graph of the codebase
Indexes files with language and size metadata
Establishes Repository -[:CONTAINS]-> File relationships

These tasks run asynchronously and do not block the response.

Error Responses

Repository is already connected

{
  "detail": "Repo already connected"
}

JWT token is invalid, expired, or missing

{
  "detail": "Unauthorized"
}

GitHub OAuth token cannot be decrypted (SECRET_KEY changed)

{
  "detail": "Session expired — please log out and sign in again."
}

Failed to install webhook on GitHub

{
  "detail": "Failed to install webhook: {error_message}"
}

Common causes:

User lacks admin permissions on the repository
OAuth token missing repo scope
GitHub API is unavailable

Permissions Required

GitHub OAuth Scopes

repo - Required to create webhooks and access repository contents

Repository Access

The authenticated user must have admin permissions on the repository to install webhooks.

List Repositories - View all repositories with connection status
Disconnect Repository - Remove webhook and deactivate connection
Rescan Repository - Rebuild the code knowledge graph

List Repositories

Disconnect Repository

⌘I

Authentication

Repositories

Reviews

Events

Analytics

Memory

Webhooks

MCP Server

Connect Repository

Overview

Authentication

Path Parameters

Request

Response

Example Response

What Happens During Connection

1. Webhook Installation

2. Database Record Creation

3. Background Tasks (Async)

Error Responses

Permissions Required

GitHub OAuth Scopes

Repository Access

​Overview

​Authentication

​Path Parameters

​Request

​Response

​Example Response

​What Happens During Connection

​1. Webhook Installation

​2. Database Record Creation

​3. Background Tasks (Async)

​Error Responses

​Permissions Required

​GitHub OAuth Scopes

​Repository Access

​Related Endpoints

Overview

Authentication

Path Parameters

Request

Response

Example Response

What Happens During Connection

1. Webhook Installation

2. Database Record Creation

3. Background Tasks (Async)

Error Responses

Permissions Required

GitHub OAuth Scopes

Repository Access

Related Endpoints