API

Verification operations

Test attestations that feed the risk and quality signals.

Test attestations that feed the risk and quality signals. Paths are relative to https://reuseforge.com/api/v1.

Operations in this area
Operation	Method	Path
Request a verification run	`POST`	`/items/{owner}/{slug}/versions/{version}/verifications`
Get a verification	`GET`	`/verifications/{verification_id}`

Request a verification run

POST /items/{owner}/{slug}/versions/{version}/verifications Enabled on reuseforge.com

Asks the platform to verify a version. Returns 202 with a stored Verification; poll get_verification or subscribe to verification.completed. The hosted runner is static-v1: it runs inside the API within a bounded CPU budget and completes before the response is sent (the record is already passed or failed), re-checking file hashes, the manifest, license and secrets and, per kind, SKILL.md front matter and MCP configuration. It does not execute the publisher's tests: tests_total / 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 tests_pass_rate is a separate runner value and is not available yet.

Request a verification run: facts
Property	Value
Operation ID	`request_verification`
Authentication	Bearer token holding `items:publish`
Rate tier	`write`: not allowed anonymous, 120/min per token with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.request_verification(...)`
JavaScript SDK	`client.requestVerification(...)`
CLI	`rf verify request`
MCP tool	`request_verification`
Deployments	reuseforge.com: enabled. Python node: not implemented (answers `501`).

Parameters

Request a verification run: parameters
Name	In	Type	Required	Description
`owner`	path	`string`	yes	Handle of the owning user or organization.
`slug`	path	`string`	yes	Item slug, unique per owner.
`version`	path	`string`	yes	An exact semantic version or `latest`.
`Idempotency-Key`	header	`string`	no	Client-chosen unique key (1 to 255 printable ASCII characters, a UUID is ideal). A repeat of the same request with the same key within 24 hours returns the first response with `Idempotent-Replayed: true`. The same key with a different body returns 422 `idempotency_key_reuse`; a repeat while the first call is still running returns 409 `idempotency_in_progress`.

Responses

Request a verification run: responses
Status	Meaning	Body
202 Accepted	Accepted. Asynchronous runners return `queued`; the `static-v1` runner returns the finished record.	`application/json`: `Verification`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/items/acme/invoice-extractor/versions/1.4.0/verifications' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.request_verification("acme/invoice-extractor", "1.4.0")
print(result["id"])

JavaScript

javascript

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

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.requestVerification("acme/invoice-extractor", "1.4.0");
console.log(result.id);

CLI

bash

rf verify request acme/invoice-extractor 1.4.0

# rf verify request <item> [version] [options]
# all options: rf verify request --help

Response 202 Accepted:

json

{
  "id": "vrf_testrun22222",
  "object": "verification",
  "item": "acme/invoice-extractor",
  "version": "1.4.0",
  "state": "queued",
  "runner": "platform",
  "tests_total": null,
  "tests_passed": null,
  "tests_pass_rate": null,
  "summary": null,
  "created_at": "2026-10-28T09:11:00Z",
  "completed_at": null
}

Get a verification

GET /verifications/{verification_id} Enabled on reuseforge.com

State and result of a verification run.

Get a verification: facts
Property	Value
Operation ID	`get_verification`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.get_verification(...)`
JavaScript SDK	`client.getVerification(...)`
CLI	`rf verify get`
MCP tool	`get_verification`
Deployments	reuseforge.com: enabled. Python node: not implemented (answers `501`).

Parameters

Get a verification: parameters
Name	In	Type	Required	Description
`verification_id`	path	`string`	yes

Responses

Get a verification: responses
Status	Meaning	Body
200 OK	The verification.	`application/json`: `Verification`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/verifications/vrf_b3k8w2n5q7c1'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.get_verification("vrf_b3k8w2n5q7c1")
print(result["id"])

JavaScript

javascript

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

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.getVerification("vrf_b3k8w2n5q7c1");
console.log(result.id);

CLI

bash

rf verify get vrf_b3k8w2n5q7c1

# rf verify get <verification_id>
# all options: rf verify get --help

Response 200 OK:

json

{
  "id": "vrf_testrun22222",
  "object": "verification",
  "item": "acme/invoice-extractor",
  "version": "1.4.0",
  "state": "passed",
  "runner": "platform",
  "tests_total": 64,
  "tests_passed": 62,
  "tests_pass_rate": 0.97,
  "summary": "62 of 64 tests passed on Python 3.12.",
  "created_at": "2026-10-28T09:11:00Z",
  "completed_at": "2026-10-28T09:12:40Z"
}