GuidesAPIChangelogSupportStatusCodecov HomeTry Codecov for Free
API Endpoints
These docs are for v4.6. Click to read the latest docs for v2023.

Upload

🚧

Codecov API v1 deprecation in progress

Please use the Codecov API v2. Documentation can be found here.

Upload versions 1 and 3 are depreciated.

Upload query - as seen as $query below

ArgumentRequiredDescription
commitYesThe destination commit sha for the report.
tokenYesA UUID token used to identify the project.
branchNoThe target branch for the report. This value may be overridden during the Codecov discovery process.
buildNoThe build number provided by your CI service.
jobNoThe job number provided by your CI service.
build_urlNoThe http url to link back to your CI provider.
nameNoA custom name for this specific upload.
slugNoThe owner/repo slug name of the project.
yamlNoThe relative path to the codecov.yml in this project.
serviceNoThe CI service name. See below for acceptable values.
flagsNoUsed for Flags. Can be one or more flags. E.g., flags=unit or flags=unit,java
prNoThe pull request number this commit is currently found in.

List of acceptable CI service names.

[
  "travis",
  "buildbot",
  "circleci",
  "buddybuild",
  "solano",
  "teamcity",
  "appveyor",
  "wercker",
  "magnum",
  "shippable",
  "codeship",
  "drone.io",
  "jenkins",
  "semaphore",
  "gitlab",
  "bamboo",
  "snap",
  "buildkite",
  "bitrise",
  "greenhouse",
  "custom"
]

Uploaded report content - as seen as @reports below

The uploaded content can be any number of coverage report formats wrapped up into the same file.

touch reports
cat coverage.xml >> reports
echo '<<<<<< EOF' >> reports
cat lcov.info >> reports
echo '<<<<<< EOF' >> reports

The resulting file at reports will look like the following.

<?xml version="1.0" encoding="UTF-8" ?>
<coverage>
  ..data..
</coverage>
<<<<<< EOF
TN:
SF:file.js
..data..
<<<<<< EOF

Codecov JSON report format

Codecov also supports a custom JSON coverage file format.

Version 2 - Direct upload

Upload v2 is used to upload report contents directly to Codecov. The reports are included in the upload body.

curl -X POST \
  --data-binary @reports \
  "https://codecov.io/upload/v2?${query}"

Version 4 - Upload to S3

Version 4 is recommended because it uploads and archives the reports to S3 immediately. Codecov's web server will not get the report data directly, which can cause issues if the file size of the uploaded report large (generally greater than 45MB).

# tell codecov we have an upload
res=$(curl -sX POST -H 'Accept: text/plain' "https://codecov.io/upload/v4?${query}")

cc_url=$(echo "$res" | sed -n 1p)  # where the reports will end up in Codecov UI
s3_url=$(echo "$res" | sed -n 2p)  # this url is temporary. it will expire

# upload reports to s3
curl -fisX PUT --data-binary @reports \
  -H 'Content-Type: text/plain' \
  -H 'x-amz-storage-class: REDUCED_REDUNDANCY' \
  "$s3_url"

echo "View reports at $cc_url"

Version 5 - Fetched

Version 5 is used when the report can be downloaded at a url. Codecov will fetch the report at time of processing.

reports="https://company.com/assets/coverage/..."
curl -X POST \
  --data-binary $reports \
  "https://codecov.io/upload/v5?${query}&url=${reports}"