### Install Sourcebot via Smithery CLI

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/mcp/README.md

Example command to install Sourcebot using the Smithery CLI, specifying the client as 'claude'. This is an alternative installation method.

```bash
npx -y @smithery/cli install @sourcebot-dev/sourcebot --client claude
```

--------------------------------

### Build zoekt and install dependencies

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CONTRIBUTING.md

Run make to build zoekt binaries and install web dependencies.

```sh
cd sourcebot
make
```

--------------------------------

### Directory structure example

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/connections/local-repos.mdx

Example directory structure for local repositories.

```sh
repos/
├─ repo_1/
├─ repo_2/
├─ repo_3/
├─ ...

```

--------------------------------

### Install Mintlify CLI

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/README.md

Install the Mintlify CLI globally to manage your documentation locally. This command is run in your terminal.

```bash
npm i -g mintlify
```

--------------------------------

### Install yarn

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CONTRIBUTING.md

Install yarn globally using npm.

```sh
npm install --global yarn
```

--------------------------------

### Example API Request with Authentication

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/api-reference/authentication.mdx

This example demonstrates how to make a POST request to the /api/search endpoint, including the Authorization header and JSON payload.

```bash
curl -X POST https://your-sourcebot-instance.com/api/search \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world", "matches": 10}'
```

--------------------------------

### Install and Configure MCP Server

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Commands for global installation and configuration of the Sourcebot MCP server for Claude Desktop.

```bash
# Install globally
npm install -g @sourcebot/mcp

# Run with environment variables
SOURCEBOT_HOST=https://your-sourcebot-instance \
SOURCEBOT_TOKEN=your-api-key \
sourcebot-mcp

# Configure in Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "sourcebot": {
      "command": "npx",
      "args": ["-y", "@sourcebot/mcp"],
      "env": {
        "SOURCEBOT_HOST": "https://your-sourcebot-instance",
        "SOURCEBOT_TOKEN": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Add CHANGELOG Entry Example

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/AGENTS.md

Example format for adding an entry to the CHANGELOG.md file. Each PR requires a single-sentence description followed by a link to the PR.

```markdown
Added
- New feature for X
[#123](https://github.com/sourcebot-dev/sourcebot/pull/123)
```

--------------------------------

### Install corepack

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CONTRIBUTING.md

Install corepack globally using npm.

```sh
npm install -g corepack
```

--------------------------------

### Example File Browser URL

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/web/src/app/(app)/browse/README.md

A concrete example of a URL path used to view a specific TypeScript file in the Sourcebot repository.

```sh
/browse/github.com/sourcebot-dev/sourcebot@HEAD/-/blob/packages/backend/src/env.ts
```

--------------------------------

### Start Local Development Server

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/README.md

Run the Mintlify development server from the root of your documentation project. Ensure docs.json is present in the directory.

```bash
mintlify dev
```

--------------------------------

### Visualize repository structure

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/features/search/search-contexts.mdx

Example directory structure for a GitLab instance used to organize repositories into groups.

```sh
web/
├─ admin_panel/
├─ customer_portal/
├─ pipelines/
├─ ...
backend/
├─ billing_server/
├─ auth_server/
├─ db_migrations/
├─ pipelines/
├─ ...
shared/
├─ protobufs/
├─ react/
├─ pipelines/
├─ ...
```

--------------------------------

### Sourcebot Complex Query Example

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

A comprehensive example combining multiple search filters and boolean logic to construct a sophisticated query.

```bash
# Complex query example
"async function" repo:backend lang:TypeScript -file:test rev:main
```

--------------------------------

### Start Development Docker Services

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/AGENTS.md

Ensure Docker is running and start the necessary services (PostgreSQL, Redis) using Docker Compose. This must be done before running `yarn dev`.

```bash
docker compose -f docker-compose-dev.yml up -d
```

--------------------------------

### Example Sourcebot Configuration with Two Connections

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/connections/overview.mdx

Define connections to GitHub.com and a self-hosted GitLab instance. Ensure environment variables for tokens are set.

```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "connections": {
        // 1. A connection to GitHub.com
        "github-connection": {
            "type": "github",
            "repos": [
                "sourcebot-dev/sourcebot"
            ],
            "token": {
                "env": "GITHUB_TOKEN"
            }
        },
        // 2. A connection to a self-hosted GitLab instance
        "gitlab-connection": {
            "type": "gitlab",
            "url": "https://gitlab.example.com",
            "groups": [
                "my-group",
                "my-other-group/sub-group"
            ],
            "token": {
                "env": "GITLAB_TOKEN"
            }
        }
    }
}
```

--------------------------------

### Run Sourcebot with authentication token

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/connections/bitbucket-data-center.mdx

Pass the Bitbucket access token as an environment variable when starting the Sourcebot container.

```bash
docker run \
    -e BITBUCKET_TOKEN=<ACCESS_TOKEN> \
    /* additional args */ \
    ghcr.io/sourcebot-dev/sourcebot:latest
```

--------------------------------

### Install universal-ctags on macOS

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CONTRIBUTING.md

Execute the provided script to install the required version of universal-ctags on macOS.

```sh
./install-ctags-macos.sh
```

--------------------------------

### Example Config with Language Model Providers

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/language-model-providers.mdx

Define multiple language model providers in your Sourcebot configuration file. Ensure environment variables for credentials are set.

```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "models": [
        // 1. Google Vertex config for Gemini 2.5 Pro
        {
            "provider": "google-vertex",
            "model": "gemini-2.5-pro",
            "displayName": "Gemini 2.5 Pro",
            "project": "sourcebot",
            "credentials": {
                "env": "GOOGLE_APPLICATION_CREDENTIALS"
            }
        },
        // 2. OpenAI config for o3 
        {
            "provider": "openai",
            "model": "o3",
            "displayName": "o3",
            "token": {
                "env": "OPENAI_API_KEY"
            }
        }
    ]
}
```

--------------------------------

### Create Sourcebot Configuration File

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/README.md

Create a `config.json` file to define Sourcebot's behavior, such as repositories to index and LLM providers. This example configures a single connection to GitHub.com to index the Sourcebot repository.

```json
echo '{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    // Comments are supported.
    // This config creates a single connection to GitHub.com that
    // indexes the Sourcebot repository
    "connections": {
        "starter-connection": {
            "type": "github",
            "repos": [
                "sourcebot-dev/sourcebot"
            ]
        }
    }
}' > config.json
```

--------------------------------

### Sourcebot Keyword Search Examples

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Demonstrates basic keyword searching, including matching single keywords, multiple keywords (AND logic), and exact phrase matching.

```bash
# Keyword search (default)
foo                           # Match files containing "foo"
foo bar                       # Match files containing both "foo" AND "bar"
"foo bar"                     # Match files containing the phrase "foo bar"
```

--------------------------------

### Start All Sourcebot Services

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/AGENTS.md

Use this command to concurrently run all necessary development services including Zoekt, backend, web, and watchers. Ensure Docker is running and Zoekt binaries are built beforehand.

```bash
yarn dev
```

--------------------------------

### Sourcebot Declarative Configuration Example

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/declarative-config.mdx

Use this JSON structure to define Sourcebot connections and repositories. Ensure the `$schema` property points to the correct Sourcebot schema.

```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/refs/heads/main/schemas/v3/index.json",
    "connections": {
        "connection-1": {
            "type": "github",
            "repos": [
                "sourcebot-dev/sourcebot"
            ]
        }
    }
}
```

--------------------------------

### Configure connection-level permission enforcement

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/features/permission-syncing.mdx

Example JSON configuration showing how to set enforcement flags for GitHub, Bitbucket, and Gerrit connections.

```json
{
  "connections": {
    "my-github": {
      "type": "github",
      "enforcePermissions": true
    },
    "my-bitbucket": {
      "type": "bitbucket",
      "enforcePermissions": true,
      "enforcePermissionsForPublicRepos": true
    },
    "my-gerrit": {
      "type": "gerrit",
      "url": "https://gerrit.example.com",
      "enforcePermissions": false
    }
  }
}
```

--------------------------------

### Docker Compose Configuration for Sourcebot

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/features/agents/review-agent.mdx

Example docker-compose.yml to set up Sourcebot, mounting a local directory for configuration and private keys. Ensure the paths within the volume mount are correct for your Sourcebot deployment.

```yaml
services:
    sourcebot:
        image: ghcr.io/sourcebot-dev/sourcebot:latest
        pull_policy: always
        container_name: sourcebot
        ports:
            - "3000:3000"
        volumes:
            - "/Users/michael/sourcebot_review_agent_workspace:/data"
        environment:
            CONFIG_PATH: "/data/config.json"

```

--------------------------------

### Sourcebot Search Filter Examples

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Shows how to refine searches using filters for file paths, repository names, branches, languages, and symbols.

```bash
# Search filters
file:README                   # Filter to filepaths matching /README/
file:\.test\.ts$              # Filter to test files
-file:node_modules            # Exclude node_modules
repo:backend                  # Filter to repos matching /backend/
-repo:deprecated              # Exclude deprecated repos
rev:develop                   # Search on develop branch
rev:v2.*                      # Search on v2.x tags
lang:TypeScript               # Filter to TypeScript files
-lang:JSON                    # Exclude JSON files
sym:\bmain\b                  # Find symbol definitions for "main"
context:frontend              # Use predefined search context
```

--------------------------------

### Use search_code MCP Tool

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Example parameters and response structure for the search_code MCP tool.

```typescript
// Tool parameters
{
  query: "handleAuth",           // Search pattern (substring by default)
  useRegex: false,               // Use regex matching
  filterByRepos: ["org/backend"], // Scope to specific repos
  filterByLanguages: ["TypeScript", "JavaScript"],
  filterByFilepaths: ["src/auth/*"],
  caseSensitive: false,
  includeCodeSnippets: true,     // Include matching code in response
  ref: "main",                   // Branch/tag to search
  maxTokens: 4000                // Max response tokens
}

// Example response
{
  "content": [{
    "type": "text",
    "text": "file: https://sourcebot/browse/org/backend/src/auth/handler.ts\nnum_matches: 3\nrepo: github.com/org/backend\nlanguage: TypeScript\n\n```\nexport async function handleAuth(req: Request) {\n  const token = req.headers.authorization;\n  // ...\n}\n```"
  }]
}
```

--------------------------------

### Sourcebot Regex Search Examples

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Illustrates how to use regular expressions for more precise code searching, including pattern matching and specific function identification.

```bash
# Regex search (toggle regex mode)
foo.*bar                      # foo followed by any characters, then bar
^function\s+\w+               # function at start of line
async\s+function\s+handle\w+  # async functions starting with "handle"
```

--------------------------------

### Example Config with Amazon Bedrock Provider

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/language-model-providers.mdx

Configure Amazon Bedrock as a language model provider. Set AWS credentials and region using environment variables. The model and region can be specified.

```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "models": [
        {
            "provider": "amazon-bedrock",
            "model": "YOUR_MODEL_HERE",
            "displayName": "OPTIONAL_DISPLAY_NAME",
            "accessKeyId": {
                "env": "AWS_ACCESS_KEY_ID"
            },
            "accessKeySecret": {
                "env": "AWS_SECRET_ACCESS_KEY"
            },
            "sessionToken": {
                "env": "AWS_SESSION_TOKEN"
            },
            "region": "YOUR_REGION_HERE", 
            "baseUrl": "OPTIONAL_BASE_URL"
        }
    ] 
}
```

--------------------------------

### Parse complex negation and regex patterns

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/queryLanguage/test/negation.txt

Advanced examples involving multiple negated prefixes, regex alternation, and whitespace handling.

```text
lang:typescript -file:*.test.ts -file:*.spec.ts

==>

Program(AndExpr(PrefixExpr(LangExpr),NegateExpr(PrefixExpr(FileExpr)),NegateExpr(PrefixExpr(FileExpr))))
```

```text
-(file:test.js lang:python)

==>

Program(NegateExpr(ParenExpr(AndExpr(PrefixExpr(FileExpr),PrefixExpr(LangExpr)))))
```

```text
-()

==>

Program(NegateExpr(ParenExpr))
```

```text
- file:test.js

==>

Program(NegateExpr(PrefixExpr(FileExpr)))
```

```text
-file:(test|spec)

==>

Program(NegateExpr(PrefixExpr(FileExpr)))
```

```text
-repo:(org1|org2)

==>

Program(NegateExpr(PrefixExpr(RepoExpr)))
```

```text
chat lang:TypeScript -file:(test|spec)

==>

Program(AndExpr(Term,PrefixExpr(LangExpr),NegateExpr(PrefixExpr(FileExpr))))
```

--------------------------------

### Run Sourcebot with Azure Devops PAT environment variable

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/connections/ado-cloud.mdx

Example command to run Sourcebot using Docker, passing the Azure Devops PAT via an environment variable.

```bash
docker run \
    -e ADO_TOKEN=<PAT> \
    /* additional args */ \
    ghcr.io/sourcebot-dev/sourcebot:latest
```

--------------------------------

### Documentation Writing Style Guide

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CLAUDE.md

Guidelines for writing and editing `.mdx` files in `docs/`, emphasizing clarity, conciseness, and proper formatting for technical content.

```APIDOC
## Documentation Writing Style

When writing or editing `.mdx` files in `docs/`:

- Do NOT use em dashes (`—`). Use periods to break sentences, commas, or parentheses instead.
- Write in second person ("you") and present tense.
- Keep sentences short and direct. Lead with what the user needs to know.
- Use bold for UI elements and key terms (e.g., **Settings → API Keys**).
- Use inline code for technical values, flags, and identifiers (e.g., `REPO_READ`).
- Prefer short paragraphs (1-3 sentences). Use bullet lists to break up dense information.
- Use tables for parameter documentation.
```

--------------------------------

### Example Config with Anthropic Provider

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/language-model-providers.mdx

Configure Anthropic as a language model provider. Authentication can be handled via an API key in the 'x-api-key' header or a bearer token in the 'Authorization' header, both sourced from environment variables.

```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "models": [
        {
            "provider": "anthropic",
            "model": "YOUR_MODEL_HERE",
            "displayName": "OPTIONAL_DISPLAY_NAME",
            // Auth can be provided via a API key that is sent using the `x-api-key` header...
            "token": {
                "env": "ANTHROPIC_API_KEY"
            },
            // ...or via a auth token sent using the `Authorization: Bearer` header.
            "authToken": {
                "env": "ANTHROPIC_AUTH_TOKEN"
            },
            "baseUrl": "OPTIONAL_BASE_URL"
        }
    ] 
}
```

--------------------------------

### OR at Start of Query

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/queryLanguage/test/operators.txt

When 'or' appears at the start of a query without a preceding term, it is treated as a term itself, and the query defaults to an AND operation.

```Sourcebot
Program(AndExpr(Term,Term))
```

--------------------------------

### List Commits

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/features/mcp-server.mdx

Get a list of commits for a given repository.

```APIDOC
## list_commits

### Description
Get a list of commits for a given repository.

### Method
POST

### Endpoint
/list_commits

### Parameters
#### Query Parameters
- **repo** (string) - Required - The name of the repository to list commits for.
- **query** (string) - Optional - Search query to filter commits by message content (case-insensitive).
- **since** (string) - Optional - Show commits more recent than this date. Supports ISO 8601 (e.g., '2024-01-01') or relative formats (e.g., '30 days ago').
- **until** (string) - Optional - Show commits older than this date. Supports ISO 8601 (e.g., '2024-12-31') or relative formats (e.g., 'yesterday').
- **author** (string) - Optional - Filter commits by author name or email (case-insensitive).
- **ref** (string) - Optional - Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch.
- **page** (integer) - Optional - Page number for pagination (min 1, default: 1).
- **perPage** (integer) - Optional - Results per page for pagination (min 1, max 100, default: 50).

### Request Example
{
  "repo": "my-repo",
  "since": "2024-01-01",
  "author": "John Doe"
}

### Response
#### Success Response (200)
- **commits** (array) - List of commit objects.
  - **sha** (string) - The commit SHA.
  - **author** (string) - The author's name.
  - **email** (string) - The author's email.
  - **date** (string) - The commit date.
  - **message** (string) - The commit message.

#### Response Example
{
  "commits": [
    {
      "sha": "a1b2c3d4e5f6",
      "author": "John Doe",
      "email": "john.doe@example.com",
      "date": "2024-03-15T10:30:00Z",
      "message": "feat: Add new feature"
    }
  ]
}
```

--------------------------------

### Plain word OR

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/queryLanguage/test/regex.txt

Treats the word 'or' as a plain word when at the start of input.

```text
or
```

--------------------------------

### Parse group at start

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/queryLanguage/test/grouping.txt

Represents a parenthetical group followed by standalone terms.

```text
(start) middle end

==>

Program(AndExpr(ParenExpr(Term),Term,Term))
```

--------------------------------

### GET /list_language_models

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/mcp/README.md

Lists the available language models configured on the Sourcebot instance.

```APIDOC
## GET /list_language_models

### Description
Lists the available language models configured on the Sourcebot instance. Use this to discover which models can be specified when calling ask_codebase.

### Method
GET

### Endpoint
/list_language_models
```

--------------------------------

### MCP Tool: list_commits

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Gets commit history for a repository with optional filtering.

```APIDOC
## MCP Tool: list_commits

### Description
Gets commit history for a repository with optional filtering.

### Method
Not specified (Tool function)

### Endpoint
Not specified (Tool function)

### Parameters
#### Path Parameters
- **repo** (string) - Required - The repository name (e.g., "github.com/org/backend").
- **query** (string) - Optional - Filter by commit message content.
- **since** (string) - Optional - Filter commits after this date (ISO format or relative, e.g., "30 days ago").
- **until** (string) - Optional - Filter commits before this date (ISO format or relative).
- **author** (string) - Optional - Filter by author name or email.
- **ref** (string) - Optional - The branch or tag to list commits from (defaults to the repository's default branch).
- **path** (string) - Optional - Filter to commits that modified this specific file or directory path.
- **page** (integer) - Optional - Page number for pagination.
- **perPage** (integer) - Optional - Number of commits per page.

### Request Example
```json
{
  "repo": "github.com/org/backend",
  "query": "fix",
  "since": "2025-01-01",
  "until": "2025-01-31",
  "author": "john",
  "ref": "main",
  "path": "src/auth",
  "page": 1,
  "perPage": 50
}
```

### Response
#### Success Response (200)
- **content** (array) - Contains the list of commits.
  - **type** (string) - The type of content, expected to be "text".
  - **text** (string) - A JSON string containing commit details.
    - **commits** (array) - List of commit objects.
      - **sha** (string) - The commit SHA hash.
      - **author** (object) - Information about the commit author.
        - **name** (string) - Author's name.
        - **email** (string) - Author's email.
      - **committer** (object) - Information about the commit committer.
        - **name** (string) - Committer's name.
        - **email** (string) - Committer's email.
      - **message** (string) - The commit message.
      - **url** (string) - The URL to the commit in Sourcebot.
      - **pushedDate** (string) - The date and time the commit was pushed.
    - **totalCount** (integer) - The total number of commits matching the query.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"commits\":[{\"sha\":\"a1b2c3d4e5f6...\",\"author\":{\"name\":\"John Doe\",\"email\":\"john.doe@example.com\"},\"committer\":{\"name\":\"Jane Smith\",\"email\":\"jane.smith@example.com\"},\"message\":\"Fix: Resolve authentication bug\",\"url\":\"https://sourcebot/browse/...\",\"pushedDate\":\"2025-01-15T10:30:00Z\"}],\"totalCount\":10}"
    }
  ]
}
```
```

--------------------------------

### Sync all repositories

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/connections/bitbucket-data-center.mdx

Use this configuration to index all repositories visible to the provided token. A token must be configured to access private repositories.

```json
{
    "type": "bitbucket",
    "deploymentType": "server",
    "url": "https://mybitbucketdeployment.com",
    // Index all repos visible to the provided token
    "all": true
}
```

--------------------------------

### File Naming Conventions

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CLAUDE.md

Files must use camelCase starting with a lowercase letter.

```text
// Correct
shareChatPopover.tsx
userAvatar.tsx
apiClient.ts

// Incorrect
ShareChatPopover.tsx
UserAvatar.tsx
share-chat-popover.tsx
```

--------------------------------

### Run Sourcebot with a Config File

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/config-file.mdx

Mount a local config.json file into the container and specify its path using the CONFIG_PATH environment variable.

```bash
docker run \
    -v $(pwd)/config.json:/data/config.json \
    -e CONFIG_PATH=/data/config.json \
    ... \ # other options
    ghcr.io/sourcebot-dev/sourcebot:latest
```

--------------------------------

### GET /list_commits

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/mcp/README.md

Retrieves a list of commits for a specified repository with optional filtering and pagination.

```APIDOC
## GET /list_commits

### Description
Get a list of commits for a given repository.

### Method
GET

### Endpoint
/list_commits

### Parameters
#### Query Parameters
- **repo** (string) - Required - The name of the repository to list commits for.
- **query** (string) - Optional - Search query to filter commits by message content (case-insensitive).
- **since** (string) - Optional - Show commits more recent than this date. Supports ISO 8601 or relative formats.
- **until** (string) - Optional - Show commits older than this date. Supports ISO 8601 or relative formats.
- **author** (string) - Optional - Filter commits by author name or email (case-insensitive).
- **ref** (string) - Optional - Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch.
- **page** (integer) - Optional - Page number for pagination (min 1, default: 1).
- **perPage** (integer) - Optional - Results per page for pagination (min 1, max 100, default: 50).
```

--------------------------------

### Configure GitHub App in Sourcebot

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/connections/github.mdx

Use this JSON configuration to set up a GitHub App connection in Sourcebot. Ensure the 'id' matches your App ID and 'privateKey.env' points to the environment variable holding your private key.

```json
"apps": [
    {
        "type": "github", // must be github
        "id": "1234567", // Your GitHub App ID
        "privateKey": {
            "env": "GITHUB_APP_PRIVATE_KEY" // Token which contains your Github App private key
        }
    }
]
```

--------------------------------

### Get Repository File Tree

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Retrieve the file structure for a repository at a specific revision.

```bash
curl -X POST "https://your-sourcebot-instance/api/tree" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "repoName": "github.com/org/backend",
    "revisionName": "main",
    "paths": ["src", "tests"]
  }'
```

--------------------------------

### Build Zoekt Binaries

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/AGENTS.md

Build the Zoekt search engine binaries from the vendor directory. This is a prerequisite for running `yarn dev`. The `make zoekt` target also performs this action.

```bash
go build -C vendor/zoekt -o $(pwd)/bin ./cmd/...
```

--------------------------------

### Get Version

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Retrieves the current version of the Sourcebot instance. Useful for compatibility checks and monitoring.

```bash
# Get version
curl "https://your-sourcebot-instance/api/version"
```

--------------------------------

### Parse mixed negation and prefix patterns

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/queryLanguage/test/negation.txt

Examples of combining negation with prefixes and terms in various positions.

```text
file:test.js -console

==>

Program(AndExpr(PrefixExpr(FileExpr),Term))
```

```text
file:test.js -lang:python

==>

Program(AndExpr(PrefixExpr(FileExpr),NegateExpr(PrefixExpr(LangExpr))))
```

```text
function -file:test.js -lang:java

==>

Program(AndExpr(Term,NegateExpr(PrefixExpr(FileExpr)),NegateExpr(PrefixExpr(LangExpr))))
```

```text
(-file:test.js)

==>

Program(ParenExpr(NegateExpr(PrefixExpr(FileExpr))))
```

```text
(-file:a.js -lang:python)

==>

Program(ParenExpr(AndExpr(NegateExpr(PrefixExpr(FileExpr)),NegateExpr(PrefixExpr(LangExpr)))))
```

```text
(include -file:test.js)

==>

Program(ParenExpr(AndExpr(Term,NegateExpr(PrefixExpr(FileExpr)))))
```

```text
-((file:test.js))

==>

Program(NegateExpr(ParenExpr(ParenExpr(PrefixExpr(FileExpr)))))
```

--------------------------------

### Initialize Git Submodules

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/AGENTS.md

Initialize and update git submodules, which is necessary before building Zoekt. This ensures all required external code is present.

```bash
git submodule update --init --recursive
```

--------------------------------

### Get Commit Details API

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Returns details for a single commit including parent commit SHAs.

```APIDOC
## GET /api/commit

### Description
Returns details for a single commit including parent commit SHAs.

### Method
GET

### Endpoint
/api/commit

### Parameters
#### Query Parameters
- **repo** (string) - Required - The name of the repository (e.g., "github.com/org/backend").
- **ref** (string) - Required - The commit reference (hash or tag).

### Request Example
```bash
curl "https://your-sourcebot-instance/api/commit?repo=github.com/org/backend&ref=abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **hash** (string) - The commit hash.
- **date** (string) - The date and time of the commit (ISO 8601 format).
- **message** (string) - The commit message.
- **refs** (string) - References to the commit (e.g., branch names).
- **body** (string) - The detailed commit body.
- **authorName** (string) - The name of the commit author.
- **authorEmail** (string) - The email of the commit author.
- **parents** (array) - An array of parent commit SHAs.

#### Response Example
```json
{
  "hash": "abc123def456789...",
  "date": "2025-01-15T10:30:00Z",
  "message": "feat: add OAuth2 support",
  "refs": "HEAD -> main",
  "body": "Detailed commit description...",
  "authorName": "John Doe",
  "authorEmail": "john@example.com",
  "parents": ["def789abc123..."]
}
```
```

--------------------------------

### Re-install Dependencies

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/README.md

If Mintlify dev is not running, use this command to re-install project dependencies. This is a troubleshooting step.

```bash
mintlify install
```

--------------------------------

### Data Fetching with React Query

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CLAUDE.md

Prefer API routes with react-query for GET requests to leverage caching.

```tsx
// Preferred: API route + react-query
import { useQuery } from "@tanstack/react-query";

const { data, isLoading } = useQuery({
    queryKey: ["items", id],
    queryFn: () => fetch(`/api/items/${id}`).then(res => res.json()),
});
```

--------------------------------

### Bitbucket Connection Configuration

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/snippets/schemas/v3/connection.schema.mdx

Configuration details for establishing a connection to Bitbucket.

```APIDOC
## Bitbucket Connection Configuration

### Description
Configuration details for establishing a connection to Bitbucket.

### Properties

- **type** (string) - Required - Must be `"bitbucket"`.
- **user** (string) - Required - The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address.
- **gitUser** (string) - Optional - The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username.
- **token** (object) - Required - An authentication token. Can be specified via an environment variable or Google Cloud Secret.
  - **env** (string) - The name of the environment variable that contains the token.
  - **googleCloudSecret** (string) - The name of the Google Cloud Secret that contains the token.
```

--------------------------------

### GET /list_tree

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/mcp/README.md

Lists files and directories from a repository path. Can be used as a directory listing tool or a repo-tree tool.

```APIDOC
## GET /list_tree

### Description
Lists files and directories from a repository path. Can be used as a directory listing tool (depth: 1) or a repo-tree tool (depth > 1).

### Method
GET

### Endpoint
/list_tree

### Parameters
#### Query Parameters
- **repo** (string) - Required - The name of the repository to list files from.
- **path** (string) - Optional - Directory path (relative to repo root). If omitted, the repo root is used.
- **ref** (string) - Optional - Commit SHA, branch or tag name to list files from. If not provided, uses the default branch.
- **depth** (integer) - Optional - Number of directory levels to traverse below path (min 1, max 10, default: 1).
- **includeFiles** (boolean) - Optional - Whether to include file entries in the output (default: true).
- **includeDirectories** (boolean) - Optional - Whether to include directory entries in the output (default: true).
- **maxEntries** (integer) - Optional - Maximum number of entries to return before truncating (min 1, max 10000, default: 1000).
```

--------------------------------

### Configure Sourcebot MCP for Claude Desktop

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/packages/mcp/README.md

Add this JSON configuration to your `claude_desktop_config.json` file to integrate Sourcebot with Claude Desktop. The `SOURCEBOT_HOST` environment variable is optional and defaults to `https://app.sourcebot.dev` if not specified.

```json
{
    "mcpServers": {
        "sourcebot": {
            "command": "npx",
            "args": ["-y", "@sourcebot/mcp@latest"],
            // Optional - if not specified, https://app.sourcebot.dev is used
            "env": {
                "SOURCEBOT_HOST": "http://localhost:3000"
            }
        }
    }
}
```

--------------------------------

### Configure OpenAI provider

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/language-model-providers.mdx

Supports reasoning effort and reasoning summary configuration for compatible OpenAI models.

```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "models": [
        {
            "provider": "openai",
            "model": "YOUR_MODEL_HERE",
            "displayName": "OPTIONAL_DISPLAY_NAME",
            "token": {
                "env": "OPENAI_API_KEY"
            },
            "baseUrl": "OPTIONAL_BASE_URL",
            "reasoningEffort": "OPTIONAL_REASONING_EFFORT", // defaults to "medium"
            "reasoningSummary": "auto" // "auto" | "detailed" | "none". Defaults to "auto"
        }
    ] 
}
```

--------------------------------

### Get Diff Between Commits API

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Returns a structured diff between two git refs using a two-dot comparison.

```APIDOC
## GET /api/diff

### Description
Returns a structured diff between two git refs using a two-dot comparison.

### Method
GET

### Endpoint
/api/diff

### Parameters
#### Query Parameters
- **repo** (string) - Required - The name of the repository (e.g., "github.com/org/backend").
- **base** (string) - Required - The base commit reference (e.g., a tag or commit hash).
- **head** (string) - Required - The head commit reference (e.g., a tag or commit hash).

### Request Example
```bash
curl "https://your-sourcebot-instance/api/diff?repo=github.com/org/backend&base=v1.0.0&head=v2.0.0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **files** (array) - An array of files that have differences.
  - **oldPath** (string) - The path of the file in the base commit.
  - **newPath** (string) - The path of the file in the head commit.
  - **hunks** (array) - An array of diff hunks for the file.
    - **oldRange** (object) - The range of lines in the old file.
      - **start** (integer) - The starting line number.
      - **lines** (integer) - The number of lines in the hunk.
    - **newRange** (object) - The range of lines in the new file.
      - **start** (integer) - The starting line number.
      - **lines** (integer) - The number of lines in the hunk.
    - **heading** (string) - A header describing the changes in the hunk.
    - **body** (string) - The diff content of the hunk.

#### Response Example
```json
{
  "files": [
    {
      "oldPath": "src/auth/handler.ts",
      "newPath": "src/auth/handler.ts",
      "hunks": [
        {
          "oldRange": { "start": 10, "lines": 5 },
          "newRange": { "start": 10, "lines": 8 },
          "heading": "function handleAuth",
          "body": " function handleAuth(req) {\n-  return basicAuth(req);\n+  return oauth2Auth(req);\n+  // Additional OAuth logic\n }"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### API Route Query Parameter Validation

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/CLAUDE.md

Validate GET request query parameters using Zod schemas.

```ts
import { queryParamsSchemaValidationError, serviceErrorResponse } from "@/lib/serviceError";
import { z } from "zod";

const myQueryParamsSchema = z.object({
    q: z.string().default(''),
    page: z.coerce.number().int().positive().default(1),
});

export const GET = apiHandler(async (request: NextRequest) => {
    const rawParams = Object.fromEntries(
        Object.keys(myQueryParamsSchema.shape).map(key => [
            key,
            request.nextUrl.searchParams.get(key) ?? undefined
        ])
    );
    const parsed = myQueryParamsSchema.safeParse(rawParams);

    if (!parsed.success) {
        return serviceErrorResponse(
            queryParamsSchemaValidationError(parsed.error)
        );
    }

    const { q, page } = parsed.data;
    // ... rest of handler
});
```

--------------------------------

### Audit logs API response example

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/audit-logs.mdx

This JSON structure represents the expected response format when fetching audit logs.

```json
[
  {
    "id": "cmc146k7m0003xgo2tri5t4br",
    "timestamp": "2025-06-17T22:48:08.914Z",
    "action": "api_key.created",
    "actorId": "cmc12tnje0000xgn58jj8655h",
    "actorType": "user",
    "targetId": "205d1da1c6c3772b81d4ad697f5851fa11195176c211055ff0c1509772645d6d",
    "targetType": "api_key",
    "sourcebotVersion": "unknown",
    "orgId": 1
  },
  {
    "id": "cmc146c8r0001xgo2xyu0p463",
    "timestamp": "2025-06-17T22:47:58.587Z",
    "action": "user.performed_code_search",
    "actorId": "cmc12tnje0000xgn58jj8655h",
    "actorType": "user",
    "targetId": "1",
    "targetType": "org",
    "sourcebotVersion": "unknown",
    "metadata": {
      "message": "render branch:HEAD"
    },
    "orgId": 1
  },
  {
    "id": "cmc12vqgb0008xgn5nv5hl9y5",
    "timestamp": "2025-06-17T22:11:44.171Z",
    "action": "user.performed_code_search",
    "actorId": "cmc12tnje0000xgn58jj8655h",
    "actorType": "user",
    "targetId": "1",
    "targetType": "org",
    "sourcebotVersion": "unknown",
    "metadata": {
      "message": "render branch:HEAD"
    },
    "orgId": 1
  },
  {
    "id": "cmc12txwn0006xgn51ow1odid",
    "timestamp": "2025-06-17T22:10:20.519Z",
    "action": "user.performed_code_search",
    "actorId": "cmc12tnje0000xgn58jj8655h",
    "actorType": "user",
    "targetId": "1",
    "targetType": "org",
    "sourcebotVersion": "unknown",
    "metadata": {
      "message": "render branch:HEAD"
    },
    "orgId": 1
  },
  {
    "id": "cmc12tnjx0004xgn5qqeiv1ao",
    "timestamp": "2025-06-17T22:10:07.101Z",
    "action": "user.owner_created",
    "actorId": "cmc12tnje0000xgn58jj8655h",
    "actorType": "user",
    "targetId": "1",
    "targetType": "org",
    "sourcebotVersion": "unknown",
    "metadata": null,
    "orgId": 1
  },
  {
    "id": "cmc12tnjh0002xgn5h6vzu3rl",
    "timestamp": "2025-06-17T22:10:07.086Z",
    "action": "user.signed_in",
    "actorId": "cmc12tnje0000xgn58jj8655h",
    "actorType": "user",
    "targetId": "cmc12tnje0000xgn58jj8655h",
    "targetType": "user",
    "sourcebotVersion": "unknown",
    "metadata": null,
    "orgId": 1
  }
]
```

--------------------------------

### Get File Tree API

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Returns the file tree for a repository at a given revision, useful for browsing repository structure.

```APIDOC
## POST /api/tree

### Description
Returns the file tree for a repository at a given revision, useful for browsing repository structure.

### Method
POST

### Endpoint
/api/tree

### Parameters
#### Request Body
- **repoName** (string) - Required - The name of the repository (e.g., `github.com/org/backend`).
- **revisionName** (string) - Required - The git revision (branch, tag, or commit SHA) to get the file tree from.
- **paths** (array of strings) - Optional - An array of paths to include in the file tree. If omitted, the entire repository tree is returned.

### Request Example
```json
{
  "repoName": "github.com/org/backend",
  "revisionName": "main",
  "paths": ["src", "tests"]
}
```

### Response
#### Success Response (200)
- Returns a file tree structure. The exact structure may vary, but typically includes nested objects representing directories and files.

#### Response Example
```json
{
  "src": {
    "index.ts": { "type": "file", "size": 1024 },
    "auth": {
      "handler.ts": { "type": "file", "size": 512 }
    }
  },
  "tests": {
    "index.test.ts": { "type": "file", "size": 2048 }
  }
}
```
```

--------------------------------

### Configure Windsurf MCP Server with OAuth

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/features/mcp-server.mdx

Paste this JSON configuration into your `~/.codeium/windsurf/mcp_config.json` file to connect to Sourcebot via OAuth. Windsurf manages the OAuth flow.

```json
{
    "mcpServers": {
        "sourcebot": {
            "serverUrl": "https://sb.example.com/api/mcp"
        }
    }
}
```

--------------------------------

### GET /api/ee/audit

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/audit-logs.mdx

Retrieves a collection of audit logs representing notable events performed by users within the Sourcebot deployment.

```APIDOC
## GET /api/ee/audit

### Description
Fetches all audit logs stored in the Sourcebot deployment database.

### Method
GET

### Endpoint
/api/ee/audit

### Request Example
curl --request GET '$SOURCEBOT_URL/api/ee/audit' \
  --header 'X-Org-Domain: ~' \
  --header 'X-Sourcebot-Api-Key: $SOURCEBOT_OWNER_API_KEY'

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the log entry
- **timestamp** (string) - ISO 8601 timestamp of the action
- **action** (string) - The type of action performed
- **actorId** (string) - ID of the user who performed the action
- **actorType** (string) - Type of the actor
- **targetId** (string) - ID of the target resource
- **targetType** (string) - Type of the target resource
- **sourcebotVersion** (string) - Version of Sourcebot
- **orgId** (number) - Organization ID
- **metadata** (object) - Optional additional information about the action

#### Response Example
[
  {
    "id": "cmc146k7m0003xgo2tri5t4br",
    "timestamp": "2025-06-17T22:48:08.914Z",
    "action": "api_key.created",
    "actorId": "cmc12tnje0000xgn58jj8655h",
    "actorType": "user",
    "targetId": "205d1da1c6c3772b81d4ad697f5851fa11195176c211055ff0c1509772645d6d",
    "targetType": "api_key",
    "sourcebotVersion": "unknown",
    "orgId": 1
  }
]
```

--------------------------------

### Configure xAI Provider

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/configuration/language-model-providers.mdx

Set up the xAI provider by providing the model name and your xAI API key, preferably stored in an environment variable. An optional base URL can also be specified.

```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "models": [
        {
            "provider": "xai",
            "model": "YOUR_MODEL_HERE",
            "displayName": "OPTIONAL_DISPLAY_NAME",
            "token": {
                "env": "XAI_API_KEY"
            },
            "baseUrl": "OPTIONAL_BASE_URL"
        }
    ] 
}
```

--------------------------------

### Sourcebot Boolean Operator Examples

Source: https://context7.com/sourcebot-dev/sourcebot/llms.txt

Explains how to combine search terms using boolean operators like OR and NOT for complex query construction.

```bash
# Boolean operators
foo or bar                    # Match "foo" OR "bar"
foo (bar or baz)              # Match "foo" AND ("bar" OR "baz")
-(foo) bar                    # Match "bar" but NOT "foo"
```

--------------------------------

### Run Sourcebot with Bitbucket Cloud API Token

Source: https://github.com/sourcebot-dev/sourcebot/blob/main/docs/docs/connections/bitbucket-cloud.mdx

Execute this Docker command to run Sourcebot, providing the Bitbucket API token via the `BITBUCKET_TOKEN` environment variable.

```bash
docker run \
    -e BITBUCKET_TOKEN=<API_TOKEN> \
    /* additional args */ \
    ghcr.io/sourcebot-dev/sourcebot:latest
```