# Vendor API and CLI reference

Source: https://opvs.ai/docs/guides/vendors/reference

> The registry endpoints a vendor uses, with their auth, and every opvs-skills command and setting.

The CLI wraps most of these calls. The full marketplace API is also on [Marketplace Registry](https://opvs.ai/docs/api/marketplace-registry.md).

## Hosts

Host

Use

`https://market.opvs.ai`

the registry: public reads, and your writes with a partner key

`https://api.opvs.ai`

public registry reads and [harvest](https://opvs.ai/docs/guides/vendors/harvest.md)

## Auth

Auth

How

Used for

none

—

public reads

partner key

header `X-Admin-Key: <partner key>`

publish, revoke, must-upgrade (registry); harvest uses `--partner-key`

## Public reads (`/api/v1/registry`, no auth)

Method

Path

Returns

GET

`/packages`

published packages; filters `vendor`, `category`, `tier`; `limit` up to 200

GET

`/search?intent=`

packages ranked by meaning and recent usage

GET

`/packages/{vendor}/{name}`

latest version detail: score, ratings, manifest, methods

GET

`/packages/{vendor}/{name}/versions`

version history

GET

`/packages/{vendor}/{name}/{version}`

one version (its `id` is the `package_id` below)

GET

`/packages/{vendor}/{name}/reviews`

public reviews, newest first

GET

`/certificates/{fingerprint}`

a vendor public key

```bash
curl -s "https://market.opvs.ai/api/v1/registry/packages/@opvs-ai/agentboard/versions" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['name'], [v['version'] for v in d['versions']][:3])"
# → agentboard ['2.2.9', …]          (a wrong name answers 404)
```

**Errors**

Code

Trigger

Fix

`404`

no published package or version with that name

check `@vendor/name` and the version; list with `/packages?vendor=`

`422`

a bad query, for example `/search` without `intent`, or `limit` over 200

send `intent=…`; keep `limit` at 200 or less

## Vendor writes (partner key, `market.opvs.ai`)

Method

Path

Notes

POST

`/api/v1/bundles/upload-url`

an upload URL for your bundle

POST

`/api/v1/registry/packages`

publish a signed version. `409` if the version exists, `422` + findings if the review blocks

POST

`/api/v1/registry/packages/{package_id}/revoke`

body `{"reason": "…"}`. See [Revoke a version](https://opvs.ai/docs/guides/vendors/revoke-a-version.md).

POST

`/api/v1/registry/packages/{package_id}/must-upgrade`

body `{"reason": "…"}`, 1–1024 characters. See [Required upgrades](https://opvs.ai/docs/guides/vendors/required-upgrades.md).

A partner key can only act on packages in its own vendor scope; anything else is `403`.

```bash
# revoke @acme/leads 1.2.0 with your partner key
PKG_ID=$(curl -s "https://market.opvs.ai/api/v1/registry/packages/@acme/leads/1.2.0" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
curl -s -X POST "https://market.opvs.ai/api/v1/registry/packages/$PKG_ID/revoke" \
  -H "X-Admin-Key: $OPVS_PARTNER_KEY" -H "Content-Type: application/json" \
  -d '{"reason": "secret included in the bundle; fixed in 1.2.1"}'
# → 200 with the version now "revoked"; 403 error if the package is not yours
```

**Errors**

Code

Trigger

Fix

`401` / `403`

partner key missing, unknown or revoked

set `X-Admin-Key`; ask vendors@opvs.ai for a new key if it was revoked

`403` scope mismatch

the package belongs to another vendor

act only on your own scope

`404`

no such package version

look up the `id` with the version read above

`409`

the version already exists (publish), or is already revoked (must-upgrade)

bump the version; flag a live version instead

`422`

the manifest or the security review refused the publish

read `findings`; see [Security review](https://opvs.ai/docs/guides/vendors/security-review.md)

## Done by OPVS for you today

Ask vendors@opvs.ai for: vendor approval; minting and revoking certificates and partner keys; approving upstream hosts; editing the marketing overlay; replying to or hiding reviews; running the standalone security review; sandbox test calls.

## The `opvs-skills` CLI

Install from public npm: `npm install -g @opvs-ai/skills`.

Command

What it does

Key flags

`generate [name]`

build typed tools, MCP definitions, SDK, CLI and OpenAPI from `schema.yaml`

`--skills-dir`, `--dry-run`, `--all`

`validate [name]`

consistency check across a skill's files

`--skills-dir`

`publish <package>`

pack, sign and publish

`--private-key`, `--api-url https://market.opvs.ai`, `--admin-key`, `--dry-run`

`doctor <@vendor/name>`

registry health of a package

`--api-url` (default `https://api.opvs.ai`)

`harvest <agents|tasks|traces|workspace|memory>`

read how your skill is used

`--brand`, `--agent`, `--args`, `--partner-key`, `--json`

`check` / `fix`

compare a `schema.yaml` with a live OpenAPI spec and list the drift

`install <@vendor/name>`

fetch, verify and extract a package

`--to`, `--runtime`, `--dest`

`test-call`, `chat`

sandbox test call and chat

OPVS-run today; see [Preflight](https://opvs.ai/docs/guides/vendors/preflight.md#4-a-real-model-call)

Always pass `--skills-dir` to `generate` and `validate`, and `--api-url https://market.opvs.ai` to `publish`: their built-in defaults are OPVS's own development setup.

```bash
npm install -g @opvs-ai/skills
opvs-skills validate leads --skills-dir ./skills
opvs-skills publish ./leads-package --dry-run --private-key "./keys/acme-signing.key"
# → validates the manifest and signs locally; prints the error and exits non-zero on a bad field
```

**Errors**

Message

Trigger

Fix

`admin key required — set OPVS_MARKETPLACE_ADMIN_KEY or pass --admin-key`

a real publish without a partner key

set the variable or pass `--admin-key`

connection refused to `localhost:8600`

`publish` without `--api-url`

pass `--api-url https://market.opvs.ai`

`install failed: … has no bundle recorded (manifest-only package)`

`install` of a marketplace package (known issue, 8 Nov 2026)

read the skill with `tool_read` over MCP instead

`404 brand not found` from `harvest`

the workspace has not installed your package

harvest only workspaces in your footprint

### Settings the CLI reads

Variable

Used by

Meaning

`OPVS_MARKETPLACE_ADMIN_KEY`

`publish`

your partner key (same as `--admin-key`)

`OPVS_PARTNER_KEY`

`harvest`

your partner key (same as `--partner-key`)

`OPVS_API_URL`

`install`, `doctor`, `harvest`

the API address; default `https://api.opvs.ai`

any name you choose

`publish --private-key @env:NAME`

your signing key

### A typical publish

```bash
export OPVS_MARKETPLACE_ADMIN_KEY=opvs_pk_…
export OPVS_SIGNING_KEY=…                       # from your CI secret
opvs-skills validate leads --skills-dir ./skills
opvs-skills publish ./leads-package --dry-run --private-key @env:OPVS_SIGNING_KEY
opvs-skills publish ./leads-package --private-key @env:OPVS_SIGNING_KEY --api-url https://market.opvs.ai
opvs-skills doctor @acme/leads
```

## Errors

A refused publish returns `422` with `error: security_review_failed`, a `score` and `findings` (`severity`, `code`, `message`, `path`). See [Security review](https://opvs.ai/docs/guides/vendors/security-review.md#reading-a-refusal).