Getting Started

Integrating with Coveralls

Using the Web App

Using the API

Getting Help

API > The /Jobs Endpoint



The /jobs endpoint is where you post coverage reports to Coveralls.

Here, you will send a POST request with a JSON representation of a coverage report to Coveralls, and Coveralls will process it and store it in its database.

  • Resource: Coverage Report (“Job”) (job)
  • Actions: POST (Create)
  • URI: *
  • Data format: JSON
  • Authentication: Coveralls Repo Token

    * If using Coveralls Enterprise, replace with the hostname of your instance.

Use Cases for the /Jobs Endpoint

This endpoint is useful for sending coverage reports directly to Coveralls, without using a Coveralls Integration.

Typical use cases:

  • A user creates a new Coveralls Integration that posts coverage reports to the /jobs endpoint, or extends an existing integration to add new features.
  • A user studies the /jobs endpoint to resolve an issue with a Coveralls Integration, potentially to override its default settings and support an atypical use case.

Example Request

Let’s look at an example POST request to the /jobs endpoint:

curl -X POST -F 'json_file=@/path/to/coverage.json' 

That’s a complete and valid request, so let’s break it down:

  • curl: The command-line tool we’re using to make the request.
  • -X POST: The HTTP method we’re using to make the request.
  • The URL of the /jobs endpoint.
  • -F 'json_file=@/path/to/coverage.json': The JSON file we’re sending to Coveralls. This is your coverage report. It’s being passed as a form parameter (-F)—specifically, as a multipart/form-data file attachment.

That last part is a key point, so let’s reiterate:

Key Points

1. Your Coverage Report is in a JSON File

Your coverage report will be in the form of a JSON file. It will contain the coverage data for your project, as well as some metadata about the CI job that sent it. We’ll see an example below.

2. That File is Passed as a Form Parameter

The JSON file must be passed as a multipart/form-data file attachment, where the name of the form parameter is json_file, and the value is the path to your JSON file.

Authentication (Coveralls Repo Token)

Coveralls Repo Tokens

Requests to the /jobs endpoint are authenticated against your Coveralls Repo Token, which is a required parameter that must be present in your JSON file.

Key Points

1. Your Coveralls Repo Token is Required

Your Coveralls Repo Token is a secret token, unique to your repository, that identifies your repo to the Coveralls API. Coveralls will only process coverage reports that are sent with a valid Coveralls Repo Token.

2. It Must be Passed in the JSON File (Not Header)

Your Coveralls Repo Token must be present in your JSON file as the repo_token parameter. It is not passed in the header of your request like a typical API token.

Read more about the Coveralls Repo Token.

The JSON File (POST Body)

The /jobs endpoint only accepts HTTP POST requests, and the body of your request must be a JSON filecalled json_file—which contains a coverage report for your project.

The Form File Attachment

The JSON File that contains your coverage report must be passed as a form file attachment (-F 'json_file=@/path/to/coverage.json'). The /jobs endpoint accepts no other form data (-F) besides the json_file.

Why a Form File Attachment?

Because a project with all it’s coverage can be very large, sending your coverage report as a form file attachment allows it to exist as a single parameter and remain readable in the same format on both sides of the request.

In addition, you can optionally gzip your JSON file to avoid hitting server size limits. In that case, you’ll just need to set the Content-Type header to gzip/json:

curl -X POST -F 'json_file=@/path/to/coverage.json' -H 'Content-Type: gzip/json'

Example JSON File

Here’s an example of a small, but complete, json_file:*

  "repo_token": "JXNndt7hKpvcXmdcpJfCKKgy01qsvrhNk",
  "service_name": "travis-ci",
  "service_job_id": "235900128",
  "source_files": [
      "name": "example.rb",
      "coverage": [null, 1, null]
      "name": "lib/two.rb",
      "coverage": [null, 1, 0, null]

* Note: We could also refer to this JSON file as the “coverage report,” since that’s all it contains; but it’s useful to distinguish it here as the “JSON file,” because, below, we’ll explore the nature of the coverage report that resides inside the JSON file, and its structure in terms of its JSON objects and all of their various parameters.

The Coverage Report (JSON Objects)

While it comprises the body of any POST request to the /jobs endpoint in the form of a JSON form file attachment, the Coveralls coverage report format warrants its own section to explain its structure.

JSON Objects

The coverage report is comprised of two (2) JSON objects:

  • The Job: The “Job” object (unlabeled) is the coverage report’s parent object. It contains metadata on the report, including the Coveralls Repo Token (repo_token), information about the CI service and job that generated the report, and the coverage report itself, in the form of the source_files object.
  • Source Files: The source_files array is a collection of individual source_file objects containing the coverage data for each source file in your project. This is the literal coverage data that Coveralls uses to generate your Coveralls coverage reports.

JSON Object: Job


A hash representing the coverage data from a single run of a test suite.


Here’s an example of a Job object—the outer, “container” object of a coverage report. It looks similar to the example json_file above, but this example has more parameters, and the source_files array has been truncated for clarity:

  "repo_token": "JXNndt7hKpvcXmdcpJfCKKgy01qsvrhNk",
  "service_name": "circleci",
  "service_job_id": "235900128",
  "source_files": [truncated],
  "service_pull_request": "42",
  "parallel": true,
  "flag_name": "ruby-2.2.3"

This particular report is for a pull request build, with parallel jobs*, on CircleCI , using flag names to help identify each of its jobs.

* Note: Because this job is part of a parallel build, the build will need to be closed, later, using the Parallel Build Webhook.


Name Description Type
The secret token for your repository, found at the top of your Repo Page, or in Repo Settings, at Coveralls. String
The CI service or other environment in which the test suite was run. Can be anything, but certain values may trigger automatic support by certain Coveralls Integrations. String
service_number The build number. Will default to incrementing integers, applied chronologically to the builds on a repo. String
A unique identifier for the job, assigned by the service specified in "service_name". String
service_job_number The job number. Will default to incrementing integers based on the jobs in a build. String
service_pull_request The ID of the pull request associated with a build, if any. Used for identifying builds as pull requests and sending PR comments. Coveralls expects a simple numerical value for this parameter, typically the user-facing PR number (ex. 42). String
An array of source files, including their coverage data. Details elaborated in Source File spec below. Array
parallel If set to true, the build will not be considered done until a POST request has been sent to the Parallel Build Webhook. Boolean
flag_name If this is set, the job being reported will be so labeled in Coveralls views, and in statuses reported to your git host. It is required to take advantage of the Carryforward Flags feature. Should be unique. String
A hash of git data used to display information about a build's commit, and to link pull request commits to their base commits by SHA. Example:

"git": {
    "head": {
        "id": "b31f08d07ae564b08237e5a336e478b24ccc4a65",
        "author_name": "Nick Merwin",
        "author_email": "...",
        "committer_name": "Nick Merwin",
        "committer_email": "...",
        "message": "Version bump"
    "branch": "master",
    "remotes": [
        "name": "origin",
        "url": ""
run_at A timestamp indicating when the job ran. Must be parseable by Ruby. Example:

"run_at": "2013-02-18 00:52:48 -0800"

* Keep in mind that the required fields here are required in raw POST requests to the /jobs endpoint; but the same fields are not necessarily required when configuring a Coveralls Integration. The point of most integrations is to automatically populate as many of these fields for you as possible.

JSON Object: Source File


A hash representing a source code file and its coverage data for a single job. The source_files array in the Job object is an array of these objects.


Here’s an example of a Source File object—one of the hash values to be found in the source_files array in the Job object:

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


Name Description Type
The file path of the source file, relative to the repo root dir. Must be unique in the job. Can include slashes. This is used to pull in the source for line-by-line coverage display, so must be the exact path relative to the repo root. String
The MD5 digest of the full source code of this file. We don’t store source code on Coveralls, rather just digests to track changes. String
The coverage data for this file, for this job. The item at index 0 represents the coverage for line 1 of the source code.

Acceptable values in the array:
  • A positive integer if the line is covered, representing the number of times the line was covered ("hit") during this run of the test suite.
  • A zero (0) if the line was not covered ("hit") by this run of the test suite.
  • A null to indicate the line was not relevant to code coverage (ex. whitespace, or a comment).
[null, 1, 0, null, 4, 15, null]
branches The branch coverage data for this file, for ths job. Each branch is represented by 4 elements in the array:

[line-number, block-number, branch-number, hits, line-number-2, block-number-2, branch-number-2, hits-2, ...etc.]

Acceptable values in the array: positive integers if the branch was covered, representing the number of times the branch was "hit" during this run of the test suite.
source The contents of the source file. (Required for manual repos on Enterprise) String


200 Success

Coveralls will respond with an HTTP 200 OK response if the request was successful, along with a JSON object containing the Job ID and URL to the new Job at Coveralls.


Header: 200 OK
Body: {"message":"Job #6F97449D268333D87EE1D263482E8AFCCC4693A5.2","url":""}


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


Header: 422 Unprocessable Entity
Body: {"error":true,"message":"Couldn't find a repository matching this job."}


Any problems, questions or comments about this doc? Let us know.