Packages
Check multiple packages
Checks up to 10 packages in one request.
POST
/
v1
/
packages
/
check
Check multiple packages
curl --request POST \
--url https://api.custoden.com/v1/packages/check \
--header 'Content-Type: application/json' \
--data '
{
"packages": [
{
"name": "<string>",
"version": "<string>"
}
]
}
'import requests
url = "https://api.custoden.com/v1/packages/check"
payload = { "packages": [
{
"name": "<string>",
"version": "<string>"
}
] }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({packages: [{name: '<string>', version: '<string>'}]})
};
fetch('https://api.custoden.com/v1/packages/check', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.custoden.com/v1/packages/check",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'packages' => [
[
'name' => '<string>',
'version' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.custoden.com/v1/packages/check"
payload := strings.NewReader("{\n \"packages\": [\n {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.custoden.com/v1/packages/check")
.header("Content-Type", "application/json")
.body("{\n \"packages\": [\n {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.custoden.com/v1/packages/check")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"packages\": [\n {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"input": {
"ecosystem": "npm",
"name": "<string>",
"version": "<string>"
},
"report": {
"ecosystem": "npm",
"name": "<string>",
"version": "<string>",
"verdict": "malicious",
"risk": "critical",
"findings": [
{
"id": "<string>",
"severity": "critical",
"title": "<string>",
"detail": "<string>",
"references": [
"<string>"
]
}
],
"vulnerabilities": [
{
"id": "<string>",
"aliases": [
"<string>"
],
"summary": "<string>",
"severity": "critical",
"fixed_in": [
"<string>"
],
"url": "<string>"
}
],
"package": {
"latest_version": "<string>",
"version_published_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"versions_count": 123,
"weekly_downloads": 123,
"maintainers_count": 123,
"repository": "<string>",
"license": "<string>",
"install_scripts": {},
"artifact": {
"scanned": true,
"file": "<string>",
"files": 123,
"executed_on_install": [
"<string>"
]
}
},
"checked_at": "2023-11-07T05:31:56Z"
},
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}
]
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"request_id": "<string>"
}Each package costs one unit of your rate limit.
The whole request is rejected with
Request body
{
"packages": [
{ "ecosystem": "npm", "name": "express", "version": "4.17.1" },
{ "ecosystem": "npm", "name": "discordi.js" },
{ "ecosystem": "pypi", "name": "requests" }
]
}
| Field | Type | Description |
|---|---|---|
packages | array | 1 to 10 items |
packages[].ecosystem | string | npm or pypi |
packages[].name | string | Package name |
packages[].version | string | Optional. Defaults to the latest release |
400 if any item is malformed. Lookups that fail for a single package, such as a missing package, are returned in that item’s error field and do not fail the request.
Example
curl -X POST https://api.custoden.com/v1/packages/check \
-H "Content-Type: application/json" \
-d '{
"packages": [
{ "ecosystem": "npm", "name": "express", "version": "4.17.1" },
{ "ecosystem": "npm", "name": "discordi.js" },
{ "ecosystem": "npm", "name": "nope-not-real-zzzq" }
]
}'
{
"results": [
{
"input": { "ecosystem": "npm", "name": "express", "version": "4.17.1" },
"report": { "name": "express", "version": "4.17.1", "verdict": "ok", "risk": "medium", "...": "..." }
},
{
"input": { "ecosystem": "npm", "name": "discordi.js" },
"report": { "name": "discordi.js", "verdict": "malicious", "risk": "critical", "...": "..." }
},
{
"input": { "ecosystem": "npm", "name": "nope-not-real-zzzq" },
"error": {
"code": "package_not_found",
"message": "npm package \"nope-not-real-zzzq\" does not exist.",
"details": {
"hint": "If an AI assistant suggested this name, do not install it. Unregistered names can be claimed by attackers."
}
}
}
]
}
Response
| Field | Type | Description |
|---|---|---|
results | array | One item per input, in the same order |
results[].input | object | The package as submitted |
results[].report | object | Present on success. Same shape as Check a package |
results[].error | object | Present on failure, with code, message and optional details |
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_json | Body is not valid JSON |
| 400 | invalid_request | packages is missing or an item lacks ecosystem or name |
| 400 | too_many_packages | More than 10 items |
| 400 | unsupported_ecosystem | An item has an unsupported ecosystem |
| 400 | invalid_package_name | An item has an invalid name |
| 413 | payload_too_large | Body exceeds 64 KB |
| 429 | rate_limited | Not enough remaining units for the whole batch |
⌘I
Check multiple packages
curl --request POST \
--url https://api.custoden.com/v1/packages/check \
--header 'Content-Type: application/json' \
--data '
{
"packages": [
{
"name": "<string>",
"version": "<string>"
}
]
}
'import requests
url = "https://api.custoden.com/v1/packages/check"
payload = { "packages": [
{
"name": "<string>",
"version": "<string>"
}
] }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({packages: [{name: '<string>', version: '<string>'}]})
};
fetch('https://api.custoden.com/v1/packages/check', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.custoden.com/v1/packages/check",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'packages' => [
[
'name' => '<string>',
'version' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.custoden.com/v1/packages/check"
payload := strings.NewReader("{\n \"packages\": [\n {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.custoden.com/v1/packages/check")
.header("Content-Type", "application/json")
.body("{\n \"packages\": [\n {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.custoden.com/v1/packages/check")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"packages\": [\n {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"input": {
"ecosystem": "npm",
"name": "<string>",
"version": "<string>"
},
"report": {
"ecosystem": "npm",
"name": "<string>",
"version": "<string>",
"verdict": "malicious",
"risk": "critical",
"findings": [
{
"id": "<string>",
"severity": "critical",
"title": "<string>",
"detail": "<string>",
"references": [
"<string>"
]
}
],
"vulnerabilities": [
{
"id": "<string>",
"aliases": [
"<string>"
],
"summary": "<string>",
"severity": "critical",
"fixed_in": [
"<string>"
],
"url": "<string>"
}
],
"package": {
"latest_version": "<string>",
"version_published_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"versions_count": 123,
"weekly_downloads": 123,
"maintainers_count": 123,
"repository": "<string>",
"license": "<string>",
"install_scripts": {},
"artifact": {
"scanned": true,
"file": "<string>",
"files": 123,
"executed_on_install": [
"<string>"
]
}
},
"checked_at": "2023-11-07T05:31:56Z"
},
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}
]
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"request_id": "<string>"
}