API Overview

Introduction

OtterWise provides a comprehensive REST API that allows you to programmatically access coverage data, analytics, and repository information. The API enables you to build custom dashboards, integrate coverage metrics into your own tools, and automate coverage tracking workflows.

Authentication

The OtterWise API uses Bearer token authentication. You can generate API tokens from your user settings page. Include the token in the Authorization header of your requests:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://otterwise.app/api/github/your-org/your-repo/analytics/trends

API Structure

The OtterWise API uses a path-based structure that mirrors your git provider's repository format. Most endpoints follow this pattern:

/api/{gitProvider}/{org}/{repo}/{resource}

Where:

• gitProvider - Your git provider (github, gitlab, or bitbucket)
• org - Your organization or user slug
• repo - Your repository name
• resource - The specific resource or endpoint you're accessing

Example Endpoints

# Get coverage trends
GET /api/github/my-org/my-repo/analytics/trends

# Get coverage hotspots
GET /api/github/my-org/my-repo/analytics/hotspots

# Get contributor statistics
GET /api/github/my-org/my-repo/analytics/contributors

Available Endpoints

The OtterWise API provides several categories of endpoints for different use cases:

Analytics Endpoints

Access detailed coverage analytics and insights for your repositories:

Repository Endpoints

Manage and retrieve information about your repositories, including coverage status, branches, and settings.

Coverage Endpoints

Access detailed coverage data for specific commits, branches, and pull requests. Retrieve line-by-line coverage information and coverage summaries.

Commit Endpoints

Retrieve coverage data and metadata for specific commits, including coverage percentages, type coverage, and mutation testing results.

Branch Endpoints

Access branch-specific coverage information and track coverage changes across different branches.

Pull Request Endpoints

Get coverage information for pull requests, including patch coverage (coverage of only the changed lines) and comparison with the base branch.

Response Format

All API responses are returned in JSON format. Successful responses include the requested data along with metadata about the request:

{
  "success": true,
  "data": {
    "repository": {
      "id": 123,
      "name": "my-repo"
    },
    "trends": {
      "2025-01-01": {
        "coverage": 85.5,
        "clover_coverage": 87.2,
        "type_coverage": 78.3,
        "commit_count": 5
      },
      "2025-01-02": {
        "coverage": 86.1,
        "clover_coverage": 87.8,
        "type_coverage": 79.1,
        "commit_count": 3
      }
    }
  }
}

Common Query Parameters

Many endpoints support query parameters to filter and customize the response:

Example Usage

Getting Coverage Trends

Retrieve coverage trends for the last 30 days, grouped by week:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://otterwise.app/api/github/my-org/my-repo/analytics/trends?from=2025-01-01&to=2025-01-31&granularity=week"

Finding Coverage Hotspots

Get the 10 files with the lowest coverage in your main branch:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://otterwise.app/api/github/my-org/my-repo/analytics/hotspots?branch=main&limit=10"

Getting Contributor Statistics

View top contributors and their average coverage over the last month:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://otterwise.app/api/github/my-org/my-repo/analytics/contributors?from=2025-01-01&to=2025-01-31&limit=20"

Rate Limiting

The OtterWise API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per API token. If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests:

Error responses include a JSON body with details about the error:

{
  "success": false,
  "message": "You do not have access to this repository",
  "error_code": "FORBIDDEN"
}

Getting Started

To get started with the OtterWise API:

1. Generate an API token from your user settings page
2. Visit the interactive API documentation to explore available endpoints
3. Use the "Try it out" feature in the Swagger UI to test endpoints
4. Integrate the API into your custom tools, dashboards, or workflows

Support and Resources

If you need help with the API or have questions about specific endpoints:

• Explore the interactive API documentation for detailed endpoint specifications
• Check out our other documentation pages for general OtterWise features
• Contact our support team for API-specific questions
• Report issues on our GitHub issues page