canonical: https://jentic.com/apis/codecov.com/codecov

# Codecov API

Codecov is a hosted code coverage reporting service that ingests test coverage uploads from CI pipelines and surfaces line, branch, and component-level coverage across every commit, branch, and pull request. The v2 API exposes 30 endpoints over api.codecov.io, including coverage trends, file reports, commit comparisons, flags, components, and test result analytics. Authentication is Bearer token or HTTP Basic, and the API is read-only apart from a single user PATCH operation.

## For AI agents

Read line and component-level coverage, commit comparisons, and test results from Codecov for repositories integrated with GitHub, GitLab, or Bitbucket.

## Scope

Does not handle coverage uploads, repository onboarding, or static analysis - use for reading Codecov coverage, comparison, and test result data only.

## Capabilities

- Pull a coverage trend for a repository over time via GET /{service}/{owner}/repos/{repo}/coverage/
- Compare coverage between two commits or branches with GET /{service}/{owner}/repos/{repo}/compare/
- Retrieve the file-level coverage report for a single source path
- List every flag (test suite or test type) configured on a repository and pull its coverage trend
- Enumerate components defined in codecov.yml and read their coverage breakdown
- Inspect the test results uploaded for a repository for flaky test analysis
- Read commit-level upload metadata to confirm CI uploaded its coverage report

## Use cases

### Pull Request Coverage Gating

Block pull requests that drop coverage below an acceptable threshold by reading commit comparison data straight from Codecov. The agent calls GET /{service}/{owner}/repos/{repo}/compare/ between the PR head and base, evaluates the delta, and posts a status check or PR comment. Replaces brittle screen-scraping of the Codecov UI with structured data.

Example prompt: Call GET `/github/acme/repos/web/compare`/ with base=main head=feature-x, and if coverage delta is below -1.0 post a failing GitHub status check

### Coverage Trend Reporting

Build a multi-repository coverage trend report for engineering leadership. Each project's GET /{service}/{owner}/repos/{repo}/coverage/ feed is sampled daily, then plotted alongside flag-level coverage to show whether unit, integration, and end-to-end tests are growing or shrinking. Removes the need for ad hoc screenshots in board reviews.

Example prompt: For each repository in the Codecov account fetch GET `/github/acme/repos/{repo}/coverage`/ for the last 30 days and write the daily averages to a Snowflake table

### Flaky Test Triage

Use the test results endpoint to surface flaky tests across a portfolio. The agent pulls GET /{service}/{owner}/repos/{repo}/test-results/, groups by test name, and ranks by failure rate so platform engineers can quarantine the worst offenders. Cuts the time spent staring at CI logs hunting for intermittent failures.

Example prompt: Pull GET `/github/acme/repos/web/test-results`/, group by test name, and produce a top-20 list of tests with failure rate above 5%

### Component Coverage Audits

Codecov components let teams group files (for example, all billing code) and track coverage as a unit. The agent enumerates GET /{service}/{owner}/repos/{repo}/components/ and pulls comparison data per component to flag any group that drops below an internal SLA. Useful for shared services where ownership is distributed.

Example prompt: List components for repository 'platform' via GET `/github/acme/repos/platform/components`/, then for each component compare coverage between releases r-12 and r-13

### Agent-Driven Coverage Lookups via Jentic

An engineer asks an agent 'is the payments service well tested?' and the Jentic-connected agent issues the right Codecov calls without holding the raw token. Jentic stores the Codecov Bearer token in its vault, returns the matching schema for the totals or trend endpoint, and executes on the agent's behalf. The user gets a one-line answer in seconds.

Example prompt: Search Jentic for 'get Codecov coverage totals', load the schema for GET /{service}/{owner}/repos/{repo}/totals/, execute it for the payments repo, and return the headline percentage

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/{service}/{owner_username}/repos/` | List repositories under an owner |
| GET | `/{service}/{owner_username}/repos/{repo_name}/totals/` | Get coverage totals for a repository |
| GET | `/{service}/{owner_username}/repos/{repo_name}/coverage/` | Get the coverage trend |
| GET | `/{service}/{owner_username}/repos/{repo_name}/compare/` | Compare coverage between commits or branches |
| GET | `/{service}/{owner_username}/repos/{repo_name}/file_report/{path}/` | Get coverage for a single file |
| GET | `/{service}/{owner_username}/repos/{repo_name}/components/` | List components |
| GET | `/{service}/{owner_username}/repos/{repo_name}/flags/` | List flags |
| GET | `/{service}/{owner_username}/repos/{repo_name}/test-results/` | Get test results analytics |

## Key resources

- **Owners and Users** — Resolve owners (GitHub orgs, GitLab groups, Bitbucket teams) and users under each owner
- **Repositories** — List repositories and read their configuration
- **Coverage** — Read coverage totals, trends, file reports, and report trees for a repository
- **Compare** — Diff coverage, components, flags, and impacted files between commits or branches
- **Components and Flags** — Enumerate Codecov components and flags and pull their coverage trends
- **Pull Requests** — List and inspect pull requests with their associated coverage data
- **Test Results** — Read uploaded test analytics for flaky and failing test analysis

## Why Jentic

- **Setup:** Wiring Codecov by hand means choosing between its Bearer and Basic auth schemes, targeting api.codecov.io/api/v2, and threading service, owner, and repo through every coverage and comparison read yourself. Through Jentic you install once, import the Codecov API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Codecov puts the service, owner, and repository in the URL path (/{service}/{owner_username}/repos/{repo_name}/...), so a rule can pin your agent to one repository: it reads that repo's totals, coverage, comparisons, components, flags, and test results and nothing else. Since these are read-only operations, you choose which of those reads the agent may call.
- **Credential handling:** Your Codecov token is stored once, encrypted, by your own Jentic One instance and injected at execution time as the Bearer or Basic credential. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'compare code coverage between branches' or 'get coverage totals for a repo', and Jentic returns the matching Codecov operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Coveralls API** — Competing hosted code coverage service with similar GitHub, GitLab, and Bitbucket coverage reporting
- **SonarCloud API** — Adds static analysis, security hotspots, and maintainability ratings alongside Codecov's coverage data
- **GitHub API** — Use GitHub for pull request, status check, and comment automation; Codecov for the coverage data those checks depend on

## FAQ

### Does Codecov publish an official OpenAPI specification?

Yes. Codecov serves an OpenAPI 3.0.3 document from its own API host at `https://api.codecov.io/api/v2/schema/`, which reports info.version 2.0.0 and covers 34 paths with a single bearer tokenAuth scheme. The specification indexed here is a curated, agent-optimized document written and maintained by Jentic from the Codecov reference documentation, covering 30 operations with an absolute base URL the vendor document leaves relative, so consult the vendor document when you need a path this one does not list. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Codecov API use?

The Codecov v2 API supports HTTP Bearer tokens and HTTP Basic authentication. Generate a token in Codecov account settings and send it as Authorization: Bearer {token}. Through Jentic the token is stored in the vault and never enters agent context.

### Can I compare coverage between two branches with the Codecov API?

Yes. GET /{service}/{owner}/repos/{repo}/compare/ accepts base and head identifiers and returns the coverage delta along with companion endpoints for impacted files, components, flags, and per-file diffs.

### What are the rate limits for the Codecov API?

Codecov does not publish a fixed public rate limit. The v2 API enforces fair-use throttling, so back off on HTTP 429 responses. For portfolio-wide trend pulls, throttle to a few requests per second per token to stay within fair-use bounds.

### How do I get coverage totals through Jentic?

Search Jentic for 'get Codecov coverage totals', load the schema for GET /{service}/{owner}/repos/{repo}/totals/, and execute it with the service (github, gitlab, bitbucket), owner username, and repository name. Jentic injects the Bearer token from the vault.

### Does the Codecov API support write operations?

The v2 API is read-only apart from PATCH /{service}/{owner}/users/{id}, which updates a single user record. Coverage uploads themselves use the separate Codecov uploader, not this REST API.

### Can I limit what my agent is allowed to do with the Codecov API?

Yes. Because Codecov puts the service, owner, and repository in the URL path, a rule in your self-hosted Jentic One instance can pin your agent to a single repository so it reads only that repo's totals, coverage trends, comparisons, components, flags, and test results. Since these operations are read-only, you decide which of those reads the agent may call and store the Bearer or Basic credential under your own rules. The agent cannot reach any repository or operation you have not allowed.