Connections API

The Connections API allows you to manage code host connections.

Note

When connections_readonly is enabled in the config, connections are managed via the config file and create/update/delete operations will return a 403 Forbidden response.

Connections Status

Check if connections management is in read-only mode.

GET /api/v1/connections/status

Response

{
  "readonly": true,
  "message": "Connections are managed via configuration file. Changes through the UI are disabled."
}

When not read-only:

{
  "readonly": false
}

List Connections

Get all configured connections.

GET /api/v1/connections

Response

[
  {
    "id": 1,
    "name": "github-work",
    "type": "github",
    "url": "https://api.github.com",
    "exclude_archived": true,
    "created_at": "2024-01-01T00:00:00Z"
  },
  {
    "id": 2,
    "name": "gitlab-internal",
    "type": "gitlab",
    "url": "https://gitlab.example.com",
    "exclude_archived": false,
    "created_at": "2024-01-05T00:00:00Z"
  }
]

Get Connection

Get a specific connection by ID.

GET /api/v1/connections/{id}

Response

{
  "id": 1,
  "name": "github-work",
  "type": "github",
  "url": "https://api.github.com",
  "exclude_archived": true,
  "created_at": "2024-01-01T00:00:00Z"
}

Create Connection

Create a new code host connection.

POST /api/v1/connections

Request Body

GitHub

{
  "name": "github-work",
  "type": "github",
  "url": "https://api.github.com",
  "token": "ghp_xxxxxxxxxxxx",
  "exclude_archived": true
}

GitLab

{
  "name": "gitlab-internal",
  "type": "gitlab",
  "url": "https://gitlab.example.com",
  "token": "glpat-xxxxxxxxxxxx",
  "exclude_archived": true
}

Gitea

{
  "name": "gitea-self",
  "type": "gitea",
  "url": "https://gitea.example.com",
  "token": "xxxxxxxxxx",
  "exclude_archived": false
}

Bitbucket

{
  "name": "bitbucket-cloud",
  "type": "bitbucket",
  "url": "https://api.bitbucket.org/2.0",
  "token": "xxxxxxxxxx",
  "exclude_archived": true
}

Response (201 Created)

{
  "id": 3,
  "name": "github-work",
  "type": "github",
  "url": "https://api.github.com",
  "exclude_archived": true,
  "created_at": "2024-01-15T12:00:00Z"
}

Update Connection

Update an existing connection. Requires all fields (name, type, url). Token is optional - if empty, the existing token is preserved.

PUT /api/v1/connections/{id}

Request Body

{
  "name": "github-work-updated",
  "type": "github",
  "url": "https://api.github.com",
  "token": "",
  "exclude_archived": true
}

Note

Name, type, and URL are required. Token is optional - leave empty to keep the existing token.

Response

{
  "id": 1,
  "name": "github-work-updated",
  "type": "github",
  "url": "https://api.github.com",
  "exclude_archived": true,
  "created_at": "2024-01-01T00:00:00Z"
}

Delete Connection

Delete a connection. Associated repositories are also removed.

DELETE /api/v1/connections/{id}

Response

Returns 204 No Content on success.

Danger

Deleting a connection removes all associated repositories and indexed data.

Test Connection

Test if a connection’s credentials are valid.

POST /api/v1/connections/{id}/test

Response (success)

{
  "status": "ok",
  "message": "Connection validated successfully"
}

Response (failure)

{
  "status": "error",
  "error": "Invalid token or insufficient permissions"
}

Sync Connection

Queue a job to fetch repositories from a connection. The actual fetching happens asynchronously.

POST /api/v1/connections/{id}/sync

Response

{
  "status": "queued",
  "job_id": 789,
  "message": "Sync job queued - repositories will be fetched in the background"
}

Conflict Response (409)

If a sync is already in progress:

{
  "status": "already_syncing",
  "message": "Connection sync job already running"
}

Note

The API prevents duplicate syncs. If a connection already has a pending or running sync job, the request returns 409 Conflict.

List Connection Repositories

List all repositories that belong to a specific connection.

GET /api/v1/connections/{id}/repos

Response

[
  {
    "id": 1,
    "name": "org/repo-one",
    "clone_url": "https://github.com/org/repo-one.git",
    "default_branch": "main",
    "branches": ["main", "develop"],
    "status": "indexed",
    "last_indexed": "2024-01-15T10:00:00Z"
  },
  {
    "id": 2,
    "name": "org/repo-two",
    "clone_url": "https://github.com/org/repo-two.git",
    "default_branch": "main",
    "branches": ["main"],
    "status": "pending"
  }
]

Examples

cURL

# Check if connections are read-only
curl "http://localhost:8080/api/v1/connections/status"

# List connections
curl "http://localhost:8080/api/v1/connections"

# Get a specific connection
curl "http://localhost:8080/api/v1/connections/1"

# Create connection
curl -X POST "http://localhost:8080/api/v1/connections" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-work",
    "type": "github",
    "url": "https://api.github.com",
    "token": "ghp_xxxx",
    "exclude_archived": true
  }'

# Update connection
curl -X PUT "http://localhost:8080/api/v1/connections/1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-work-updated",
    "type": "github",
    "url": "https://api.github.com",
    "exclude_archived": true
  }'

# Test connection credentials
curl -X POST "http://localhost:8080/api/v1/connections/1/test"

# Trigger sync
curl -X POST "http://localhost:8080/api/v1/connections/1/sync"

# List repos for a connection
curl "http://localhost:8080/api/v1/connections/1/repos"

# Delete connection
curl -X DELETE "http://localhost:8080/api/v1/connections/1"

JavaScript

const API = 'http://localhost:8080/api/v1';

// Check if connections are read-only
const status = await fetch(`${API}/connections/status`).then(r => r.json());
console.log('Read-only:', status.readonly);

// List connections
const connections = await fetch(`${API}/connections`).then(r => r.json());

// Get a specific connection
const connection = await fetch(`${API}/connections/1`).then(r => r.json());

// Create connection
const newConn = await fetch(`${API}/connections`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'github-work',
    type: 'github',
    url: 'https://api.github.com',
    token: 'ghp_xxxx',
    exclude_archived: true
  })
}).then(r => r.json());

// Test connection
const test = await fetch(`${API}/connections/1/test`, {
  method: 'POST'
}).then(r => r.json());

// Trigger sync
const sync = await fetch(`${API}/connections/1/sync`, {
  method: 'POST'
}).then(r => r.json());

// List repos for a connection
const repos = await fetch(`${API}/connections/1/repos`).then(r => r.json());

Python

import requests

API = "http://localhost:8080/api/v1"

# Check if connections are read-only
status = requests.get(f"{API}/connections/status").json()
print(f"Read-only: {status['readonly']}")

# List connections
connections = requests.get(f"{API}/connections").json()

# Get a specific connection
connection = requests.get(f"{API}/connections/1").json()

# Create connection
new_conn = requests.post(
    f"{API}/connections",
    json={
        "name": "github-work",
        "type": "github",
        "url": "https://api.github.com",
        "token": "ghp_xxxx",
        "exclude_archived": True
    }
).json()

# Test connection
test = requests.post(f"{API}/connections/1/test").json()

# Trigger sync
sync = requests.post(f"{API}/connections/1/sync").json()

# List repos for a connection
repos = requests.get(f"{API}/connections/1/repos").json()

Connection Types

Type	Description
github	GitHub.com or GitHub Enterprise
gitlab	GitLab.com or self-hosted GitLab
gitea	Gitea instances
bitbucket	Bitbucket Cloud or Bitbucket Server

Repository Status Values

Status	Description
pending	Waiting to be indexed
indexed	Successfully indexed
error	Indexing failed

Next Steps

• Jobs API - Monitor sync and indexing jobs
• Repositories API - Repository management