Skip to main content
POST
/
api
/
v1
/
repos
/
{owner}
/
{repo}
/
install
Connect Repository
curl --request POST \
  --url https://api.example.com/api/v1/repos/{owner}/{repo}/install
{
  "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

​
owner
string
required
Repository owner (user or organization)
​
repo
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"

​
Response

​
status
string
Always returns "connected" on success
​
installation_id
integer
Database ID of the newly created installation record
​
repo
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

​
400 Bad Request
Repository is already connected
{
  "detail": "Repo already connected"
}
​
401 Unauthorized
JWT token is invalid, expired, or missing
{
  "detail": "Unauthorized"
}
​
401 Session Expired
GitHub OAuth token cannot be decrypted (SECRET_KEY changed)
{
  "detail": "Session expired — please log out and sign in again."
}
​
502 Bad Gateway
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us