API > The /Jobs Endpoint

Overview

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: https://coveralls.io/api/v1/jobs ^*
• Data format: JSON
• Authentication: Coveralls Repo Token
  
  * If using Coveralls Enterprise, replace coveralls.io 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 https://coveralls.io/api/v1/jobs -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.
• https://coveralls.io/api/v1/jobs: 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 file—called 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 https://coveralls.io/api/v1/jobs -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

Description

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

Example

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.

Parameters

"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": "git@github.com:lemurheavy/coveralls-ruby.git"
        }
    ]
}

"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

DESCRIPTION

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.

Example

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]
}

PARAMETERS

[null, 1, 0, null, 4, 15, null]

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

Response

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.

Example

Header: 200 OK
Body: {"message":"Job #6F97449D268333D87EE1D263482E8AFCCC4693A5.2","url":"https://coveralls.io/jobs/116403628"}

Failure

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

Example

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.