API

Publishing

Publish a skill, harness or MCP server with reuseforge.json and rf publish or the API: manifest reference, versions, pricing, licensing, verification, install.

Publishing is two steps: create the item (its name, kind, price and license) and publish a version (immutable files plus a manifest). rf publish does both from a project directory; the API has one operation for each.

The five-minute path

cd my-skill
rf init --kind skill                # scaffolds reuseforge.json (detects SKILL.md, package.json, pyproject.toml, .mcp.json)
rf publish --dry-run                # validates, lists every file, shows the content hash and the idempotency key; sends nothing
rf publish                          # creates the item if missing, uploads version 0.1.0
rf publish --verify --wait          # later releases: also request the platform's checks and wait for the result

Needed: a token with items:write (to create the item) and items:publish (to publish versions); see authentication. rf publish scans for secrets and refuses to upload files that look like credentials (private key headers, rf_ tokens, .env files) unless you pass --allow-secrets, which you should almost never do. It never changes the price of an existing item and uses a deterministic Idempotency-Key, so repeating an interrupted publish cannot create a second version.

Item kinds

The manifest: reuseforge.json

A project describes what it publishes in reuseforge.json at its root. Only name, version and kind are required. Unknown keys are rejected. The schema is /docs/api/schemas/reuseforge.schema.json (JSON Schema 2020-12); point your editor at it with "$schema".

{
  "$schema": "https://reuseforge.com/docs/api/schemas/reuseforge.schema.json",
  "name": "acme/invoice-extractor",
  "version": "1.4.0",
  "kind": "skill",
  "title": "Invoice extractor",
  "summary": "Extracts vendor, totals and line items from PDF invoices into JSON.",
  "license": "MIT",
  "repository": "https://github.com/acme/invoice-extractor",
  "capabilities": ["document-parsing"],
  "tags": ["pdf", "invoices"],
  "pricing": { "model": "free" },
  "ignore": ["tests/fixtures/**"],
  "preview": ["README.md", "SKILL.md"],
  "dependencies": { "acme/pdf-text-layer": "^2.1.0" },
  "changelog": "Handles multi-page invoices."
}

An MCP server item adds an mcp section that tells installers how to start it:

{
  "name": "acme/ledger-mcp",
  "version": "0.3.0",
  "kind": "mcp_server",
  "license": "Apache-2.0",
  "mcp": {
    "transport": "stdio",
    "command": "node",
    "args": ["server.js"],
    "env": { "LEDGER_API_KEY": "${LEDGER_API_KEY}" }
  }
}

env and headers values are ${VAR} placeholders only: an installer never writes a secret into your configuration. The full key reference follows, generated from the schema.

pricing

test

requires

mcp

How to start or reach the MCP server this item ships (kind mcp_server). env and headers values must be ${VAR} placeholders, never secrets.

install.<target>

Keys of install are install targets (generic, claude-code, cursor, codex, mcp-json); each value may contain:

Versions

• Semantic versions. MAJOR.MINOR.PATCH, optionally with a prerelease suffix (1.5.0-rc.1). latest prefers stable releases and uses the highest prerelease only when an item has no stable version; ranges skip prereleases unless asked for.
• Immutable. A version can never be overwritten; republishing the same number answers 409 already_exists. Fix a mistake by publishing a higher version and yanking the bad one.
• Yanking. update_version with yanked: true and a yanked_reason hides a version from latest and new resolution and warns installers, but never deletes content, so existing lockfiles still resolve. Only changelog, yanked and yanked_reason can change after publishing.
• Limits. At most 100 files, 512 KiB per file and 2 MiB per version (the live numbers are in GET /api/v1/). Paths are relative and /-separated, without .., a leading /, a backslash, NUL, case-only duplicates, and normalised to NFC. Binary files travel as base64.
• What the CLI includes. Everything not ignored: the manifest's files (include globs) and ignore, plus a built-in ignore list (.git, node_modules, .venv, __pycache__, .DS_Store, reuseforge.lock, .env*).
• Events. Publishing fires item.version.published (and item.published for the first public version); see webhooks.

The content hash

content_hash is sha256: plus the hex SHA-256 of a text with one line per file, <sha256 hex of the file bytes> <path>\n (two spaces, exactly what sha256sum prints), sorted by path in UTF-8 byte order. Send it with publish_version and the server recomputes it, answering 422 integrity_mismatch if it differs. Installers verify it before writing a single file.

import hashlib

def content_hash(files):                      # files: {"SKILL.md": b"...", "src/run.py": b"..."}
    lines = [f"{hashlib.sha256(data).hexdigest()}  {path}\n" for path, data in sorted(files.items(), key=lambda kv: kv[0].encode("utf-8"))]
    return "sha256:" + hashlib.sha256("".join(lines).encode("utf-8")).hexdigest()

Both SDKs ship content_hash(files) / contentHash(files) and verify_bundle. Shared test vectors are in the repository under api/conformance/content-hash-vectors.json.

Publish with the API

# 1. create the item (metadata only)
curl -X POST https://reuseforge.com/api/v1/items -H "Authorization: Bearer $REUSEFORGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"slug": "invoice-extractor", "kind": "skill", "title": "Invoice extractor", "summary": "Extracts totals from PDF invoices.", "license": "MIT"}'

# 2. publish a version; files carry their text (or base64 for binary files)
curl -X POST https://reuseforge.com/api/v1/items/acme/invoice-extractor/versions -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"version": "1.4.0", "files": [{"path": "SKILL.md", "content": "# Invoice extractor\n", "encoding": "utf8"}], "changelog": "First release."}'

import reuseforge

client = reuseforge.Client()
client.create_item(slug="invoice-extractor", kind="skill", title="Invoice extractor", summary="Extracts totals from PDF invoices.", license="MIT")
files = [{"path": "SKILL.md", "content": "# Invoice extractor\n", "encoding": "utf8"}]
client.publish_version("acme/invoice-extractor", version="1.4.0", files=files, changelog="First release.")

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge();
await client.createItem({ slug: 'invoice-extractor', kind: 'skill', title: 'Invoice extractor', summary: 'Extracts totals from PDF invoices.', license: 'MIT' });
await client.publishVersion('acme/invoice-extractor', { version: '1.4.0', files: [{ path: 'SKILL.md', content: '# Invoice extractor\n', encoding: 'utf8' }], changelog: 'First release.' });

rf publish          # does both from the project directory

In the API a version's dependencies is a list of {item, range} objects, while the manifest writes the same thing as a map of owner/slug to range. The exact body fields (files[].encoding is utf8 or base64, manifest, content_hash, changelog) are in the reference for publish_version and create_item. New items are draft until their first version is published, unless the item only points at an external source.

Pricing

• The price belongs to the item, not to a version. The manifest's pricing is informational: rf publish warns when it differs from the item and never changes it. Change the price explicitly with rf items update --price 12 (or update_item).
• Paid items need a verified email and a payout address. Payout addresses can only be set in the web app, never through the API, so a stolen token cannot redirect your earnings.
• Escrow and fees. The buyer's money is held until they accept (or the acceptance window ends). The platform fee (fee_bps, default 100 basis points, 1 percent) is deducted from your proceeds at release: seller_amount_cents = price_cents - fee_cents. The buyer pays exactly the price.
• Previews. preview globs name files readable without buying (usually the README and the SKILL.md front matter). Everything else answers 402 payment_required until the buyer's order is delivered.
• Entitlement. Access to a paid item starts when the order is delivered, before the money is released, and covers every version of the item.

The orders side is not enabled on reuseforge.com yet (see the availability table), so today paid listings are for the self-hosted node and for planning.

Licensing

license is an SPDX expression (MIT, Apache-2.0 OR MIT). Use LicenseRef-Proprietary for paid closed items. Buyers and the planner filter on it (the planner's constraints.allowed_licenses), and installers record it in reuseforge.lock. The verification run checks that a license is present. Say what the buyer may do in your README; the platform does not provide legal advice.

Verification

request_verification asks the platform to check a stored version. The hosted runner is static-v1: it runs inside the API, completes before the response is sent, and re-checks file hashes, limits, the manifest, the license, secrets, binaries, the SKILL.md front matter (for skills), the MCP configuration (for MCP servers) and the README. It does not execute your tests: tests_total and tests_passed count static checks, tests_pass_rate stays null, and planner signals are never changed by it. A sandbox runner that executes test.command and attests a real pass rate (the runner values platform, community and seller) does not exist yet. Nothing in the API presents static checks as test results.

rf verify request acme/invoice-extractor 1.4.0      # or publish with: rf publish --verify --wait
rf verify get vrf_...

Subscribe to verification.completed (webhooks) instead of polling get_verification.

Install descriptors

get_install_descriptor(item, version, target) returns a recipe: which files go where, the config patches to merge, and display-only commands. The client fetches content with get_version_bundle and applies the recipe. The descriptor never contains secrets and never asks a client to run code.

Targets are generic, claude-code, cursor, codex and mcp-json. If you omit target the server chooses generic; the CLI detects .claude/, .cursor/ and .codex/ or AGENTS.md and otherwise asks.

A manifest install.<target> entry overrides any cell. The claude-code layouts and .mcp.json follow documented conventions. The Cursor .mdc and Codex paths follow those tools' public conventions but were not verified against the running tools; they are isolated in the override mechanism so they can be corrected without an API change.

Installer safety rules (the CLI and both SDKs enforce them): destinations resolve inside the project root, with traversal and symlink escapes refused; a file that differs from the lock's recorded hash is never overwritten without --force; every file sha256 and the bundle content_hash are verified before anything is written; writes are atomic; setuid and setgid are stripped and modes capped at 0755. Where config files merge, objects merge deeply and a conflicting key stops the install (or is skipped without --force) instead of being overwritten.

Archives and plugin marketplaces for tools that do not speak this API are on Distribution formats.

Last updated: 2026-11-03