canonical: https://jentic.com/apis/coveralls.io/coveralls

# Coveralls API

Jentic publishes the only available OpenAPI specification for Coveralls API, keeping it validated and agent-ready. The Coveralls API lets developers and CI systems register repositories, post coverage reports for build jobs, and close out parallel build pipelines that run tests across multiple workers. It is the programmatic surface behind Coveralls' coverage tracking service, accepting LCOV, Cobertura, and other coverage formats from GitHub, GitLab, and Bitbucket projects. The API uses a Personal API Token in the Authorization header and is commonly invoked from CI scripts, custom test runners, and quality dashboards.

## For AI agents

Register repositories, post test coverage reports from CI, and close parallel build jobs on Coveralls. Use when an agent needs to record code coverage for a build run.

## Scope

Does not handle test execution, source code hosting, or static analysis - use for posting and managing code coverage reports only.

## Capabilities

- Register a repository on Coveralls so coverage reports can be posted against it
- Post a coverage report for a specific build job, including line and branch coverage data
- Retrieve repository configuration details for GitHub, GitLab, or Bitbucket repos already on Coveralls
- Update repository settings such as comment behaviour and badge visibility
- Close a parallel build by signalling that all coverage jobs have been submitted
- Delete a repository entry when a project is retired or archived

## Use cases

### CI Coverage Reporting

After a CI build runs the test suite, a coverage tool produces an LCOV or Cobertura report. The job runner then posts that report to Coveralls via POST `/api/v1/jobs` so that the coverage percentage, line-by-line details, and pull request status checks are updated. This integration takes minutes to set up because most CI providers already have Coveralls plugins, and it keeps the team's coverage history in one place.

Example prompt: Post a coverage report to `/api/v1/jobs` with service_name 'github-actions', repo_token from the vault, and the LCOV payload, then confirm a 200 response.

### Parallel Build Coordination

When a test suite is split across multiple parallel CI workers, each worker posts its partial coverage to Coveralls. Once all workers have submitted their slices, the build coordinator calls POST /webhook with the build number to merge results into a single coverage report. Without this final webhook call, Coveralls leaves the build in an open state and the PR check never resolves.

Example prompt: Send POST /webhook with payload {repo_token, payload: {build_num, status: 'done'}} to close a parallel build for repo 'acme/widgets' once all four workers have posted.

### Repository Onboarding Automation

When a new microservice is created from a template, an automation script registers it with Coveralls so coverage tracking is enabled before the first build runs. POST `/api/repos` creates the entry and returns a repo token that is then injected into the CI environment as COVERALLS_REPO_TOKEN. This avoids manual UI steps and keeps coverage onboarding consistent across hundreds of repos.

Example prompt: Call POST `/api/repos` with {repo: {service: 'github', name: 'acme/payments-svc'}} and store the returned repo_token as a CI secret named COVERALLS_REPO_TOKEN.

### Coverage Quality Gate Agent

An AI agent embedded in a release workflow checks coverage status before merging. It calls GET `/api/repos/{service}/{repo_user}/{repo_name}` to fetch the current coverage percentage and recent build history, then decides whether to block or approve the merge. Through Jentic, the agent finds the right operation by intent, loads its schema, and executes the call without reading Coveralls documentation.

Example prompt: Search Jentic for 'check coverage status on coveralls', load the GET `/api/repos` schema, execute against repo 'acme/widgets' on github service, and return the latest coverage_percent.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/jobs` | Post a coverage report from a CI build |
| POST | `/api/repos` | Register a new repository on Coveralls |
| GET | `/api/repos/{service}/{repo_user}/{repo_name}` | Get repository information |
| PUT | `/api/repos/{service}/{repo_user}/{repo_name}` | Update repository settings |
| DELETE | `/api/repos/{service}/{repo_user}/{repo_name}` | Delete a repository entry |
| POST | `/webhook` | Close a parallel build |

## Key resources

- **Repositories** — Create, retrieve, update, and delete repository entries on Coveralls
- **Jobs** — Post coverage reports for individual CI build jobs
- **Webhook** — Close parallel builds once all worker jobs have reported

## Why Jentic

- **Setup:** Wiring Coveralls by hand means handling its token in the Authorization header, pinning the coveralls.io host, and coding your own coverage job and repo requests. Through Jentic you install once, import Coveralls from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Coveralls puts the repo in the URL path (`/api/repos/{service}/{repo_user}/{repo_name}`), so a rule can pin your agent to one repository: it acts only on that repo. You choose the operations it may call, so destructive ones like deleting a repo are not included unless you add them.
- **Credential handling:** Your Coveralls token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'post a coverage report' or 'read coverage for a repo', and Jentic returns the matching Coveralls operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Codecov API** — Codecov is the main competitor to Coveralls and offers similar coverage upload and reporting endpoints.
- **Code Climate API** — Code Climate combines coverage tracking with maintainability and technical debt scoring.
- **GitHub API** — GitHub hosts the source repos that Coveralls tracks and surfaces the coverage status checks on pull requests.
- **CircleCI API** — CircleCI runs the build jobs whose coverage is then posted to Coveralls.

## FAQ

### Why is there no official OpenAPI spec for Coveralls API?

Coveralls does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Coveralls API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Coveralls API use?

Coveralls uses a personal API token sent in the Authorization header in the format 'token XXX'. Through Jentic, the token is stored encrypted in the vault and injected at execution time, so the token never appears in the agent's prompt or context.

### How do I post a coverage report to Coveralls through Jentic?

Search Jentic for 'post coverage report to coveralls', load the POST `/api/v1/jobs` schema, then execute with the service name, repo_token, and coverage payload. Jentic handles the Authorization header automatically using the stored personal token.

### Can I close a parallel build using the Coveralls API?

Yes. Once all parallel CI workers have posted their partial coverage to `/api/v1/jobs`, send a POST to /webhook with the build_num and status 'done' so Coveralls merges the slices into one report and resolves the pull request check.

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

Coveralls does not publish hard numerical rate limits in the OpenAPI spec. In practice the API tolerates one report per build job and several repository management calls per minute. If a 429 response appears, back off and retry with exponential delay.

### Can I register repositories on Coveralls programmatically?

Yes. POST `/api/repos` creates a new repository entry and returns a repo_token that you store as the COVERALLS_REPO_TOKEN secret in your CI provider. This is the standard pattern for onboarding many repos at once without using the web UI.

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

Yes. Because you run Jentic One yourself, your own rules decide which Coveralls operations and credentials the agent can use. Coveralls puts the repository in the URL path (`/api/repos/{service}/{repo_user}/{repo_name}`), so you can pin the agent to a single repo and let it act only on that one. You also choose the operations it may call, so you can allow posting coverage reports to `/api/v1/jobs` and closing parallel builds via /webhook while excluding destructive ones like DELETE `/api/repos.`