General Support

Language Integrations

Coveralls API

Open an Issue

API Introduction

For users of the Ruby programming language, Coveralls is best accessed by our official gem. We hope to expand our official support to other languages and toolchains soon.

We want to encourage developers to help us expand Coveralls’ usefulness to other languages, and for that we have provided a RESTful Coverage API to allow use with any language.

Sending Coverage to Coveralls

Each coverage job on Coveralls consists of a reference to a repository, and a set of source files with their associated coverage data.

At its simplest level, a coverage job on Coveralls consists of two items: the source code of a file and which lines were covered. The source code is stored as a string, and the line-by-line coverage data is stored as an array. Just toss this information in a JSON hash, and – boom! – you’ve got your source file.

Referencing a Repository

We can reference a repository in one of two ways:

service_job_id String and service_name String

Coveralls currently supports the following continuous integration services: Travis CI (open source), Travis Pro (private repos), CircleCI, Semaphore, JenkinsCI, or Codeship.

Setting service_name to "travis-ci" and service_job_id to the Travis Job ID will automatically look up the appropriate build and repository, and assign the job correctly on Coveralls.

repo_token String

The secret repo token for your repository, found at the bottom of your repository’s page on Coveralls. This is useful if your job is running on a service we don’t support out-of-the-box. If you choose to use the repo token, a new build will be created for every job.

Source Files

Here’s an example of what a source file would look like as JSON:

  "name":     "lib/example.rb",
  "source_digest":   "1eb14b3a053f951ca925f2fd4d633eeb",
  "coverage": [null, 1, null]

name String

The relative file path of this source file in the git repo. Must be unique in the job. Can include slashes. The file type for syntax highlighting will be determined from the file extension in this parameter. This is used to pull in the source for coverage display, so must be the exact path relative to the repo root.

source_digest String

The MD5 digest of full source code of this file. We don’t store source code on Coveralls, rather just digests to track changes.

coverage Array

An array of coverage data, with item at index 0 representing the coverage for line 1 of the source code.

Acceptable values for the array is an integer representing the number of times that line is covered, or null representing a line that is not relevant to coverage (such as whitespace or a comment).

Posting to Coveralls

To post a new job, send a multipart HTTP POST to

Because a project with all it’s coverage and source can be large, you must write your API request to a JSON file and send it with the form parameter json_file. You can optionally GZIP your json – set the content-type header to “gzip/json” in that case.

Coveralls will respond with an HTTP 200 OK if the request was successful.

Any other response code should be considered a failure and the response body will be set to error text.

Here’s an example of a complete json_file:

  "service_job_id": "1234567890",
  "service_name": "travis-ci",
  "source_files": [
      "name": "example.rb",
      "source_digest": "asdfasdf1234asfasdf2345",
      "coverage": [null, 1, null]
      "name": "lib/two.rb",
      "source_digest": "asdf1234asdfsdfggsfgd9423",
      "coverage": [null, 1, 0, null]

Getting data from Coveralls

The following are examples of endpoints that can be requested as JSON:
(latest build)
(get 10 builds at a time)

For easier programmatic access, you can use the build commit sha to instead of its numerical ID, e.g.:

Source file endpoints will return the coverage array, e.g:


The index of the array corresponds to the index of the source file line number. The value is the number of times the line was executed, and “null” implies the line is not relavent.

Aggregate directory coverage can be queried for builds and jobs using the “paths” parameter, which accepts a comma separated list or glob style format:*,lib/coveralls/configuration.rb