Skip to main content

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. 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:

{
  "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:

{
  "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:

{
  "status": "success"
}

Error Responses​

The API may return the following error responses:

401 Unauthorized:

{
  "error": "Missing or invalid Authorization header. Expected format: Bearer <token>"
}

or

{
  "error": "Invalid or revoked API token"
}

400 Bad Request:

{
  "error": "Missing webhook payload"
}

or

{
  "error": "Git provider and ID are required"
}

or

{
  "error": "PR number is required"
}

or

{
  "error": "Commit SHA is required"
}

Example Usage​

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

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:

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: