> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custoden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check multiple packages

> Checks up to 10 packages in one request.

Each package costs one unit of your [rate limit](https://docs.custoden.com/getting-started/rate-limits.md).

## Request body

```json theme={null}
{
  "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 |

The whole request is rejected with `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

```bash theme={null}
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" }
    ]
  }'
```

```json theme={null}
{
  "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](https://docs.custoden.com/api-reference/check-a-package.md#response) |
| `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 |


## OpenAPI

````yaml POST /v1/packages/check
openapi: 3.1.0
info:
  title: Custoden API
  version: v1
  description: >-
    Free, keyless API for checking open-source packages and GitHub Actions
    workflows.
  contact:
    url: https://github.com/Custoden/docs
servers:
  - url: https://api.custoden.com
security: []
paths:
  /v1/packages/check:
    post:
      summary: Check multiple packages
      description: Costs 1 rate limit unit per package.
      operationId: checkPackages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - packages
              properties:
                packages:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    $ref: '#/components/schemas/PackageInput'
      responses:
        '200':
          description: One result per input, in order
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      required:
                        - input
                      properties:
                        input:
                          $ref: '#/components/schemas/PackageInput'
                        report:
                          $ref: '#/components/schemas/PackageReport'
                        error:
                          $ref: '#/components/schemas/ErrorBody'
        '400':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    PackageInput:
      type: object
      required:
        - ecosystem
        - name
      properties:
        ecosystem:
          type: string
          enum:
            - npm
            - pypi
        name:
          type: string
        version:
          type: string
          maxLength: 128
    PackageReport:
      type: object
      required:
        - ecosystem
        - name
        - version
        - verdict
        - risk
        - findings
        - vulnerabilities
        - package
        - checked_at
      properties:
        ecosystem:
          type: string
          enum:
            - npm
            - pypi
        name:
          type: string
        version:
          type: string
        verdict:
          type: string
          enum:
            - malicious
            - suspicious
            - review
            - ok
        risk:
          type: string
          enum:
            - critical
            - high
            - medium
            - low
            - none
        findings:
          type: array
          items:
            $ref: '#/components/schemas/Finding'
        vulnerabilities:
          type: array
          items:
            $ref: '#/components/schemas/Vulnerability'
        package:
          type: object
          properties:
            latest_version:
              type: string
            version_published_at:
              type:
                - string
                - 'null'
              format: date-time
            created_at:
              type:
                - string
                - 'null'
              format: date-time
            versions_count:
              type: integer
            weekly_downloads:
              type:
                - integer
                - 'null'
            maintainers_count:
              type:
                - integer
                - 'null'
            repository:
              type:
                - string
                - 'null'
            license:
              type:
                - string
                - 'null'
            install_scripts:
              type: object
              additionalProperties:
                type: string
            artifact:
              $ref: '#/components/schemas/Artifact'
        checked_at:
          type: string
          format: date-time
    ErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
    Finding:
      type: object
      required:
        - id
        - severity
        - title
        - detail
      properties:
        id:
          type: string
        severity:
          $ref: '#/components/schemas/Severity'
        title:
          type: string
        detail:
          type: string
        references:
          type: array
          items:
            type: string
            format: uri
    Vulnerability:
      type: object
      required:
        - id
        - aliases
        - summary
        - severity
        - fixed_in
        - url
      properties:
        id:
          type: string
        aliases:
          type: array
          items:
            type: string
        summary:
          type: string
        severity:
          type: string
          enum:
            - critical
            - high
            - medium
            - low
            - unknown
        fixed_in:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
    Artifact:
      oneOf:
        - type: object
          required:
            - scanned
            - file
            - files
            - executed_on_install
          properties:
            scanned:
              const: true
            file:
              type: string
            files:
              type: integer
            executed_on_install:
              type: array
              items:
                type: string
        - type: object
          required:
            - scanned
            - reason
          properties:
            scanned:
              const: false
            reason:
              type: string
              enum:
                - no_artifact
                - too_large
                - unreadable_archive
                - removed_from_registry
    ErrorResponse:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
        request_id:
          type: string
    Severity:
      type: string
      enum:
        - critical
        - high
        - medium
        - low
        - info
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.