Tidelift subscriber API documentation – Tidelift

Current Tidelift API documentation as well as future API documentation updates can be found on our dedicated API site:

https://api.tidelift.com/docs

THE SECTION BELOW IS FOR USERS OF A LEGACY VERSION OF TIDELIFT. FOR MOST TIDELIFT IMPLEMENTATIONS THE DEDICATED API DOCUMENTATION IS THE APPROPRIATE RESOURCE. IF YOU ARE UNCERTAIN WHICH VERSION OF TIDELIFT YOUR ORGANIZATION IS USING, PLEASE CONTACT TIDELIFT SUPPORT.

––

This article covers how to use the API to integrate the Tidelift Subscription into your workflow. Note that we strongly recommend that you use the Tidelift CLI instead of directly calling the API with curl or your own code.

Authorization

You need a repository API key to use the API. You can generate an API key for each tracked repository through the Tidelift subscriber dashboard. The Tidelift Subscriber API requires an API key to be passed using the "Authorization" header.

Example: curl -H 'Authorization: Bearer {{api-key-example}}'

Submitting Package Files

Files can be submitted through the endpoint below by replacing team-name and repo-name with your team and repository/project names respectively.

Example: https://api.tidelift.com/subscriber/upload?team={{team-name}}&repository={{repo-name}}&branch={{branch-name}}

URL Parameters

Parameter	Description
team-name	The name of your organization, URL encoded.
repo-name	The name of the repository/project, URL encoded.

Query Parameters

Parameter	Description
revision (optional)	An ID that can be used to reference back to this version of the scan. Some examples of a revision: Jenkins build number, the git commit SHA, or a custom ID created using `uuidgen`. If a revision parameter is omitted, one will be generated using the current date and time.
branch (optional)	The branch name of the scan: used to determine the health of the scan in comparison to the default branch (typically master). If omitted, it will be assumed that the scan is for the default branch. On non-default branches, only newly-introduced issues will block a build.

Form Parameters

Parameter	Description
files[]	A set of one or more dependency files. You may also provide your `.tidelift.yml` configuration file in this set.

HTTP Headers

Header Name	Value
Authorization	Your API token. `Authorization: Bearer {{api-key-example}}`.

Responses

Successful responses will include JSON that includes the revision that the scan was created with.Example: { "revision": "a57ff7a3b3e437ae9f14fb264dd63506b2c7a285" }

Code	Description
201	Files were successfully submitted and a new scan is being created.
401	The authorization token sent was not found or incorrect for the given team and repository names.
404	There was no repository with the given name assigned to the given team name.
400	Files were not found in the `files[]` parameter of the request.
5xx	An unexpected error occurred. Please contact Tidelift Support for further assistance.

Example Submissions

Curl

Here is a complete example using curl to submit Gemfile.lock files from the command line.

curl -X POST -F "files[]=@Gemfile.lock" -F "files[]=@Gemfile" -H "Authorization: Bearer v2/repository/example-api-key" https://api.tidelift.com/subscriber/upload?team=team-name&repository=repo-name&branch=branch-name

Python

Here is a complete example using >= python 3.6 to submit Gemfile.lock files from the command line.

First, if urllib3 is not installed: $ pip install urllib3

from urllib3 import PoolManager

TEAM_NAME = "team-name"
REPO_NAME = "repo-name"
API_KEY = "api-key"
BRANCH_NAME = "branch-name"

http = PoolManager()

file_list = [
  ("files[]", ('Gemfile', open("Gemfile", "rb").read())),
  ("files[]", ('Gemfile.lock', open("Gemfile.lock", "rb").read())),
]

res = http.request(
  "POST",
  f"https://api.tidelift.com/subscriber/upload?team={TEAM_NAME}&repository={REPO_NAME}&branch={BRANCH_NAME}",
  headers={'Authorization': "Bearer {API_KEY}"},
  fields=file_list,
)
print(res.data)

Retrieving Scan Status

You can get the status of a previous scan by referencing its revision. The status will return back the overall result of the scan.

Example: https://api.tidelift.com/subscriber/{{team-name}}/{{repo-name}}/{{revision}}/status

URL Parameters

Parameter	Description
team-name	The name of your team, URL encoded.
repo-name	The name of the repository, URL encoded.
revision	The revision that the manifest files were uploaded with. If you did not send a revision in the manifest upload request, one was created for you and is available from the upload response.

HTTP Headers

Header Name	Value
Authorization	Your API token. `Authorization: Bearer {{api-key-example}}`.

Example Submission

Here is an example using curl to get the status of a scan.curl -H "Authorization: Bearer v2/repository/example-api-key" https://api.tidelift.com/subscriber/team-name/repo-name/revision/status

Response

200-status responses will include JSON that resembles:

{
  "id": "55c98b13-9288-4830-a1bb-cd66684f47f9",
  "status": "failure",                                 // whether the scan was a success or failure.
  "revision": "85431aff54ae5780f231b6f1395a8ac56",     // the revision of the code that was uploaded
  "branch": "master",                                  // the branch the code was on for this scan
  "details_url": "https://tidelift.com/scans/8675309", // a link to see more details on our website
  "manifests": [
    {
      "platform": "rubygems",                          // platform of this manifest group
      "paths": [                                       // paths in the group
        "Gemfile.lock",
        "Gemfile"
      ],
      "issues": [                                      // All issues found on default branch (usually master),
                                                       // or newly-introduced issues found on any other branch
        {
          "platform": "rubygems",
          "name": "fake-package",
          "version": "3.2.1",
          "dependency_type": "runtime",                // the Maven configuration, Rubygems group, etc.
                                                       //     (possible values vary by platform)
          "issue_type": "license_prohibited",          // the type of issue, from the list at /docs/config/
          "direct": true,                              // whether the dependency is direct (from your manifest) or
                                                       //     transitive (from your dependencies' dependencies)
          "action": "fail",                            // the policy-configured action for this issue
                                                       //     fail - will result in a "failure" status for the scan
                                                       //     warn - does not affect the overall scan status
          "licenses": [                                // list of prohibited licenses
            "MIT"                                      // (only present if issue_type is license_prohibited)
          ]
        }
      ]
    }
  ]
}

If this is a default branch (usually master), you will see all issues present. If you scan a feature branch only issues added in that branch will be listed.

The `status` field will be set to `failure` if any of the issues listed have `"action" : "fail"`.

Issue types configured to `skip` in your policy will not be listed in this API response.

HTTP Status Code	Description
200	Successful response that should contain the status and revision of the scan.
401	The authorization token sent was not found or incorrect for the given team and repository names.
404	There was no scan found for the combination of team, repository, and revision. After submitting a new revision, you may see a 404 for a short window of time before the scan is created.
5xx	An unexpected error occurred. Please contact Tidelift Support for further assistance.

Statuses

*If you have just submitted a revision for a scan, be prepared for the scan to 404 for a window of time, before it enters the pending status.

Status	Description
pending	The scan request has been received and is preparing to run.
running	The scan is running. Allow some time for it to complete and send another request to get the final status.
success	The scan completed with no failing checks.
failure	The scan completed and the build was blocked. Your policy defines which issues block a build. On non-default branches, only regressions (newly-introduced issues) will block the build.
error	The scan did not complete and a new scan should be submitted.

Authorization

Submitting Package Files

URL Parameters

Query Parameters

Form Parameters

HTTP Headers

Responses

Example Submissions

Curl

Python

Retrieving Scan Status

URL Parameters

HTTP Headers

Example Submission

Response

Statuses

Related articles