> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codebeaver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud API

> CodeBeaver cloud exposes a RESTful API

The CodeBeaver API is a RESTful API that allows you to interact with CodeBeaver programmatically.

## Authentication

The CodeBeaver API uses API keys to authenticate requests. You can manage your API keys from the [Team page](https://app.codebeaver.ai/team).
Every team can have multiple API keys. Team members can deactivate API keys if needed.

## API endpoints

### POST Webhook

The POST Webhook endpoint allows you to programmatically trigger CodeBeaver to analyze and write tests for your code. This is particularly useful when you want to integrate CodeBeaver into your own CI/CD pipelines or development workflows.

#### Endpoint

```
POST https://app.codebeaver.ai/api/webhook/
```

#### Headers

To authenticate your request, include your API token in the Authorization header:

```
Authorization: Bearer your_api_token_here
```

The token must be active and associated with your team. You can generate and manage API tokens from the CodeBeaver Team page.

#### Request Body

The webhook accepts different types of actions through its payload. Here are the supported payload structures:

For triggering analysis on a Pull Request:

```json theme={null}
{
  "type": "pull_request",
  "action": "analyze-and-generate",
  "git_provider": "github", // or "gitlab" or "bitbucket"
  "git_provider_id": "repository_id",
  "pr_number": 123
}
```

For triggering analysis on a specific commit:

```json theme={null}
{
  "type": "commit",
  "action": "analyze-and-generate",
  "git_provider": "github", // or "gitlab" or "bitbucket"
  "git_provider_id": "repository_id",
  "commit_sha": "abc123..."
}
```

#### Field Descriptions

* `type`: Specifies what you want CodeBeaver to analyze. Currently supports:

  * `pull_request`: Analyze changes in a pull request
  * `commit`: Analyze changes in a specific commit

* `action`: Defines what CodeBeaver should do. Supports:

  * `analyze`: Analyzes changes and provides test results and bug detection analysis
  * `analyze-and-generate`: Does everything `analyze` does, plus generates test files
  * `dry-run`: Performs analysis and shows what would be generated without making any changes

* `git_provider`: Identifies which Git hosting service you're using. Supports:

  * `github`: GitHub repositories
  * `gitlab`: GitLab repositories
  * `bitbucket`: Bitbucket repositories

* `git_provider_id`: The unique identifier of your repository in your Git provider's system

* `pr_number`: Required when type is "pull\_request". The number of the pull request to analyze

* `commit_sha`: Required when type is "commit". The full SHA hash of the commit to analyze

#### Response

A successful request will return:

```json theme={null}
{
  "status": "success"
}
```

#### Error Responses

The API may return the following error responses:

401 Unauthorized:

```json theme={null}
{
  "error": "Missing or invalid Authorization header. Expected format: Bearer <token>"
}
```

or

```json theme={null}
{
  "error": "Invalid or revoked API token"
}
```

400 Bad Request:

```json theme={null}
{
  "error": "Missing webhook payload"
}
```

or

```json theme={null}
{
  "error": "Git provider and ID are required"
}
```

or

```json theme={null}
{
  "error": "PR number is required"
}
```

or

```json theme={null}
{
  "error": "Commit SHA is required"
}
```

#### Example Usage

Here's a complete example showing how to trigger CodeBeaver on a pull request using curl:

```bash theme={null}
curl -X POST https://app.codebeaver.ai/api/webhook/ \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pull_request",
    "action": "analyze-and-generate",
    "git_provider": "github",
    "git_provider_id": "123456789",
    "pr_number": 42
  }'
```

And here's how you might integrate it into a Python script:

```python theme={null}
import requests

def trigger_codebeaver_analysis(api_token: str, repo_id: str, pr_number: int) -> None:
    """
    Trigger CodeBeaver to analyze and write tests for a pull request.

    Args:
        api_token: Your CodeBeaver API token
        repo_id: Your repository's ID in the git provider
        pr_number: The pull request number to analyze

    Raises:
        requests.exceptions.RequestException: If the API request fails
    """
    response = requests.post(
        "https://app.codebeaver.ai/api/webhook/",
        headers={
            "Authorization": f"Bearer {api_token}",
            "Content-Type": "application/json"
        },
        json={
            "type": "pull_request",
            "action": "analyze-and-generate",
            "git_provider": "github",
            "git_provider_id": repo_id,
            "pr_number": pr_number
        }
    )
    response.raise_for_status()
    return response.json()
```

#### Rate Limits

To ensure service quality, the webhook API is rate limited. Current limits are:

* 10 requests per minute per API token
* 1000 requests per day per team

#### Best Practices

When using the webhook API, consider these recommendations:

1. Store your API token securely and never commit it to version control
2. Implement proper error handling for API responses
3. Consider implementing retries with exponential backoff for failed requests
4. Monitor your API usage to stay within rate limits
5. Keep your API tokens rotated regularly for security

## Getting Help

If you encounter any issues or need assistance with the webhook API:

* Join our [Discord community](https://discord.gg/4QMwWdsMGt)
* Contact our support team at [info@codebeaver.ai](mailto:info@codebeaver.ai)