Tidelift Subscriber API documentation

This article covers how to use the API to integrate the Tidelift Subscription into your workflow.

Authorization

You need an 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 repository/{{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 names respectively.

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

URL Parameters

Parameter Description
team-name The name of your organization, URL encoded.
repo-name The name of the repository, 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 repository/{{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 repository/example-api-key" https://api.tidelift.com/subscriber/team-name/repo-name/manifest/upload?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/{TEAM_NAME}/{REPO_NAME}/manifest/upload?branch={BRANCH_NAME}",
  headers={'Authorization': f"Bearer repository/{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 repository/{{api-key-example}}.

Example Submission

Here is an example using  curl to get the status of a scan.curl -H "Authorization: Bearer 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.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us