---
title: "POST /v1/compare/batch"
method: POST
path: "/v1/compare/batch"
tags: ["packages"]
---

# POST /v1/compare/batch

`POST /v1/compare/batch`

## Request

- Base URL: `https://api.pkgseek.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pkgseek.com/v1/compare/batch`
- Auth: none declared

## Query parameters

- `catalog_revision` string

## Request body

- MatrixRequest
  - `items` MatrixItem[], required
    - `arch` string
    - `installed_version` string
    - `intent` 'desired' | 'observed', required
    - `item_id` string, required
    - `name` string, required
    - `purl` string
    - `repo` string
    - `source` string
    - `source_name` string
    - `source_version` string
  - `schema_version` integer, required
  - `source_scope` MatrixScope
    - `arch` string
    - `distro` string, required
    - `kind` 'repository', required
    - `release` string, required
    - `repo` string
    - `source` string, required
  - `targets` MatrixScope[], required: Targets must be unique after release-alias canonicalization.
    - `arch` string
    - `distro` string, required
    - `kind` 'repository', required
    - `release` string, required
    - `repo` string
    - `source` string, required

## Response `200`

One read-only repeatable-read snapshot; indexed builds only; candidates require confirmation

- MatrixResponse
  - `catalog_revision` string, required
  - `compared_at` string, required
  - `policy` string, required
  - `rows` MatrixRow[], required
    - `cells` MatrixCell[], required
      - `candidate_count` integer, required
      - `candidates` MatrixCandidate[], required
        - `evidence` MatrixEvidence[], required
          - `kind` string, required
          - `value` string, required
        - `evidence_truncated` boolean, required
        - `indexed_cves` integer, required
        - `install_command` string, nullable: Only a package-name command; requires explicit UI confirmation and does not configure the source, pin the version, or resolve dependencies.
        - `name` string, required
        - `resolution` PackageResolution, required
          - `catalog_revision` string, required
          - `coverage` ScopeCoverage, required
            - `generation` string, nullable
            - `observed_at` string, nullable
            - `reason` string, required
            - `state` string, required: Legacy index timestamps cannot prove a complete import generation.
          - `match_type` string, required
          - `policy` string, required
          - `requested` PackageScope, required: An explicit ordinary-repository request uses one exact release snapshot.
            - `arch` string, required
            - `distro` string, required
            - `release` string, required
            - `repo` string, nullable
            - `source` string, required
          - `resolved` PackageScope, required: An explicit ordinary-repository request uses one exact release snapshot.
            - `arch` string, required
            - `distro` string, required
            - `release` string, required
            - `repo` string, nullable
            - `source` string, required
          - `selection` string, required
          - `warnings` string[], required
        - `security_scope` string, required
        - `version` string, required
      - `candidates_truncated` boolean, required
      - `state` string, required
      - `target_index` integer, required
      - `warnings` string[], required
    - `item` MatrixItem, required: P0 inventory item. Text limits also apply in UTF-8 bytes. Desired items must omit installed_version.
      - `arch` string
      - `installed_version` string
      - `intent` 'desired' | 'observed', required
      - `item_id` string, required
      - `name` string, required
      - `purl` string
      - `repo` string
      - `source` string
      - `source_name` string
      - `source_version` string
    - `source` MatrixCandidate
      - `evidence` MatrixEvidence[], required
        - `kind` string, required
        - `value` string, required
      - `evidence_truncated` boolean, required
      - `indexed_cves` integer, required
      - `install_command` string, nullable: Only a package-name command; requires explicit UI confirmation and does not configure the source, pin the version, or resolve dependencies.
      - `name` string, required
      - `resolution` PackageResolution, required
        - `catalog_revision` string, required
        - `coverage` ScopeCoverage, required
          - `generation` string, nullable
          - `observed_at` string, nullable
          - `reason` string, required
          - `state` string, required: Legacy index timestamps cannot prove a complete import generation.
        - `match_type` string, required
        - `policy` string, required
        - `requested` PackageScope, required: An explicit ordinary-repository request uses one exact release snapshot.
          - `arch` string, required
          - `distro` string, required
          - `release` string, required
          - `repo` string, nullable
          - `source` string, required
        - `resolved` PackageScope, required: An explicit ordinary-repository request uses one exact release snapshot.
          - `arch` string, required
          - `distro` string, required
          - `release` string, required
          - `repo` string, nullable
          - `source` string, required
        - `selection` string, required
        - `warnings` string[], required
      - `security_scope` string, required
      - `version` string, required
    - `source_reason` string, required
  - `schema_version` integer, required
  - `source_scope` MatrixScope
    - `arch` string
    - `distro` string, required
    - `kind` 'repository', required
    - `release` string, required
    - `repo` string
    - `source` string, required
  - `targets` MatrixTarget[], required
    - `coverage` ScopeCoverage, required
      - `generation` string, nullable
      - `observed_at` string, nullable
      - `reason` string, required
      - `state` string, required: Legacy index timestamps cannot prove a complete import generation.
    - `reason` string, required
    - `requested` MatrixScope, required
      - `arch` string
      - `distro` string, required
      - `kind` 'repository', required
      - `release` string, required
      - `repo` string
      - `source` string, required
    - `resolved` PackageScope: An explicit ordinary-repository request uses one exact release snapshot.
      - `arch` string, required
      - `distro` string, required
      - `release` string, required
      - `repo` string, nullable
      - `source` string, required
    - `state` string, required
  - `warnings` string[], required

## Other responses

- `400`: Invalid versioned request
- `409`: Catalog revision mismatch
- `413`: 64 KiB request limit
- `422`: Item, target, candidate or response budget exceeded
- `429`: Admission limit
- `503`: Disabled or dependency unavailable
- `504`: 10 second total timeout

---

[API](https://skmtc.dev/pkgseek/apis/pkgseek-api.md) · [All operations](https://skmtc.dev/pkgseek/apis/pkgseek-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pkgseek/apis/pkgseek-api/revisions/277f0f960210?raw)