API overview

Tidelift subscribers have full access to the Tidelift API. Using the Tidelift API subscribers can:

• Create and update catalogs and projects.
• Perform alignments
• Retrieve bills of materials
• Request and retrieve reports
• BETA: Get information from Tidelift about packages, releases, and vulnerabilities

Tidelift’s REST API is rooted at https://api.tidelift.com/external-api/.

Tidelift does not have a anonymous public API; all API endpoints are restricted to Tidelift subscribers.

Full API documentation

Supported REST API endpoints, parameters, and returned items are found in our dedicated API documentation at https://api.tidelift.com/docs.

Tidelift provides a downloadable API specification that can be used in tools that support importing OpenAPI specifications.

How to use the Tidelift API

Authentication

Authentication to the Tidelift API is done via API keys, passed as Bearer tokens.

An example header would be:

Authorization: Bearer <key goes here>

Passing data

There are two ways to pass data to the Tidelift API.

• Query parameters, passed in the URL
  • Example query: https://api.tidelift.com/external-api/v1/endpoint?platform=pypi&name=urllib3

• Body data, passed as JSON
  • Example data: { “project_name”: “myfancyproject” }

Which data form an API accepts will be documented in the full API documentation.

Escaping

If you are accessing items in the API such as package names that contain characters such as spaces or slashes ("/"), you will need to url-encode the item to access it properly. For example, if a Go package is named

github.com/my/special/go/package

you would access it in an API call as

github.com%2Fmy%2Fspecial%2Fgo%2Fpackage

Examples

Here are examples of using the project creation API, in a number of different ways.

Using curl:

curl -s -H "Accept: application/json" -H "Authorization: Bearer <your token>" \
 -X POST https://api.tidelift.com/external-api/v1/team/Yoyodyne-Propulsion-Systems/projects/ \
 –json ‘{ “project_name”: “overthruster”, “catalog”: “default”, “default_branch”: “main” }’

Using Python:

import json
import requests

API_KEY = "<your token>"

headers = {"Accept": "application/json", "Authorization": f"Bearer {API_KEY}"}

body = {"project_name": "overthruster", "default_branch": "main", "catalog": "default"}

r = requests.post(
    "https://api.tidelift.com/external-api/v1/team/Yoyodyne-Propulsion-Systems/projects",
    headers=headers,
    json=body,
)

if not r.ok:
    print(f"Error: API request returned {r.status_code}")
else:
    jsondata = r.json()

print(json.dumps(jsondata))

Using Ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.tidelift.com/external-api/v1/team/<your-team>/projects")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <your_token>"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "project_name": "my new project",
  "catalog": "default",
  "default_branch": "main"
})

response = https.request(request)

puts response.read_body

Using Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.tidelift.com/external-api/v1/team/<your-team>/projects"
  method := "POST"

  payload := strings.NewReader(`{
    "project_name": "my new project",
    "catalog": "default",
    "default_branch": "main"
  }`)

  client := &http.Client {
  }

  req, err := http.NewRequest(method, url, payload)
  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer <your_token>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Println(string(body))
}

Using JavaScript

const axios = require('axios');

let data = JSON.stringify({
  "project_name": "my new project",
  "catalog": "default",
  "default_branch": "main"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.tidelift.com/external-api/v1/team/<your-team-name>/projects',
  headers: { 
    'Authorization': 'Bearer <your_token>', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})

.catch((error) => {
  console.log(error);
});

Using Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\n    \"project_name\": \"my new project\",\n    \"catalog\": \"default\",\n    \"default_branch\": \"main\"\n}");

Request request = new Request.Builder()
  .url("https://api.tidelift.com/external-api/v1/team/<your-team>/projects")
  .method("POST", body)
  .addHeader("Authorization", "Bearer <your-token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

Using other tools

For other tools, Tidelift suggests using the downloadable API specification to assist in accessing the API.