Repositories API

The Repositories API allows you to manage indexed repositories.

List Repositories

Get all indexed repositories.

GET /api/v1/repos

Query Parameters

Parameter	Type	Description
connection_id	integer	Filter by connection ID
search	string	Search repositories by name (partial match)
status	string	Filter by status (indexed, pending, etc.)
limit	integer	Results per page (default: 15, max: 500)
offset	integer	Pagination offset

Response

{
  "repos": [
    {
      "id": 1,
      "name": "myorg/api",
      "clone_url": "https://github.com/myorg/api.git",
      "branches": ["main", "develop"],
      "status": "indexed",
      "last_indexed": "2024-01-15T10:30:00Z",
      "excluded": false
    }
  ],
  "total_count": 45,
  "limit": 15,
  "offset": 0,
  "has_more": true
}

Get Repository

Get a specific repository by ID.

GET /api/v1/repos/by-id/{id}

Parameters

Parameter	Type	Description
id	integer	Repository ID

Response

{
  "id": 1,
  "name": "myorg/api",
  "clone_url": "https://github.com/myorg/api.git",
  "branches": ["main", "develop"],
  "status": "indexed",
  "last_indexed": "2024-01-15T10:30:00Z",
  "excluded": false
}

Add Repository

Add a new repository for indexing.

POST /api/v1/repos

Request Body

{
  "connection_id": 1,
  "name": "myorg/api",
  "clone_url": "https://github.com/myorg/api.git",
  "default_branch": "main",
  "branches": ["main", "develop"]
}

Response

Returns the created repository with status 201 Created.

Sync Repository

Trigger a re-index for a repository.

POST /api/v1/repos/by-id/{id}/sync

Response

{
  "status": "queued",
  "job_id": "abc123",
  "message": "Sync job queued"
}

Conflict Response (409)

If a sync is already in progress:

{
  "status": "already_syncing",
  "message": "Repository sync already in progress"
}

Note

The API prevents duplicate syncs. If a repository is already being synced or has a pending job, the request returns 409 Conflict.

## Delete Repository

Remove a repository from the index.

```http
DELETE /api/v1/repos/by-id/{id}

Response

Returns 204 No Content on success.

Caution

Deleting a repository removes all indexed data. If repos_readonly is enabled, this endpoint returns 403 Forbidden.

Exclude Repository

Exclude a repository from sync and indexing (soft delete).

POST /api/v1/repos/by-id/{id}/exclude

Response

{
  "message": "Repository excluded from sync and indexing",
  "id": 1
}

Tip

Excluded repositories are not deleted from the database. They can be included again later. This is useful when repos_readonly mode is enabled.

Include Repository

Include a previously excluded repository.

POST /api/v1/repos/by-id/{id}/include

Response

{
  "message": "Repository included - will be indexed on next sync",
  "id": 1
}

Set Poll Interval

Set a custom polling interval for a repository.

PUT /api/v1/repos/by-id/{id}/poll-interval

Request Body

{
  "interval_seconds": 3600
}

Use 0 to reset to the default interval.

Response

{
  "status": "updated",
  "repo_id": 1,
  "interval_seconds": 3600
}

Repository Status Endpoint

Check if repos are in read-only mode.

GET /api/v1/repos/status

Response

{
  "readonly": false
}

Examples

cURL

# List repositories
curl "http://localhost:8080/api/v1/repos"

# Search repositories
curl "http://localhost:8080/api/v1/repos?search=myorg"

# Filter by connection
curl "http://localhost:8080/api/v1/repos?connection_id=1"

# Filter by status
curl "http://localhost:8080/api/v1/repos?status=indexed"

# Pagination
curl "http://localhost:8080/api/v1/repos?limit=20&offset=0"

# Get specific repo
curl "http://localhost:8080/api/v1/repos/by-id/1"

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

# Exclude repo
curl -X POST "http://localhost:8080/api/v1/repos/by-id/1/exclude"

# Include repo
curl -X POST "http://localhost:8080/api/v1/repos/by-id/1/include"

# Set poll interval (1 hour)
curl -X PUT "http://localhost:8080/api/v1/repos/by-id/1/poll-interval" \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 3600}'

# Delete repo
curl -X DELETE "http://localhost:8080/api/v1/repos/by-id/1"

JavaScript

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

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

// Get specific repo
const repo = await fetch(`${API}/repos/by-id/1`).then(r => r.json());

// Trigger sync
await fetch(`${API}/repos/by-id/1/sync`, { method: 'POST' });

// Exclude repo
await fetch(`${API}/repos/by-id/1/exclude`, { method: 'POST' });

// Set poll interval
await fetch(`${API}/repos/by-id/1/poll-interval`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ interval_seconds: 3600 })
});

Python

import requests

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

# List repos
repos = requests.get(f'{API}/repos').json()

# Get specific repo
repo = requests.get(f'{API}/repos/by-id/1').json()

# Trigger sync
requests.post(f'{API}/repos/by-id/1/sync')

# Exclude repo
requests.post(f'{API}/repos/by-id/1/exclude')

# Set poll interval
requests.put(f'{API}/repos/by-id/1/poll-interval',
             json={'interval_seconds': 3600})

Status Values

Status	Description
pending	Waiting to be indexed
indexing	Building search index
indexed	Ready for search
error	Indexing failed

Next Steps

• Connections API - Connection management
• Jobs API - Job monitoring