Vendor API and CLI reference

ReferenceUpdated 5 min read
View as Markdown
On this page

The CLI wraps most of these calls. The full marketplace API is also on Marketplace Registry.

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

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

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.

POST

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

body {"reason": "…"}, 1–1024 characters. See Required upgrades.

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

# 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

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

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.

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

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.

Did this answer your question?
Need help? support@opvs.aiChangelogLLM? Read llms.txt