API

Reviews operations

Reviews by verified buyers.

Reviews by verified buyers. Paths are relative to https://reuseforge.com/api/v1.

Operations in this area
Operation	Method	Path
List reviews	`GET`	`/items/{owner}/{slug}/reviews`
Review an item	`POST`	`/items/{owner}/{slug}/reviews`
Delete your review	`DELETE`	`/items/{owner}/{slug}/reviews/mine`

List reviews

GET /items/{owner}/{slug}/reviews Enabled on reuseforge.com

Reviews of an item, newest first by default. Reviews a moderator removed and reviews by suspended accounts are not listed or counted (total).

List reviews: facts
Property	Value
Operation ID	`list_reviews`
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.list_reviews(...)`
JavaScript SDK	`client.listReviews(...)`
CLI	`rf reviews list`
MCP tool	`list_reviews`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

List reviews: 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.
`sort`	query	`string: newest, highest, lowest`	no	Default `"newest"`.
`cursor`	query	`string`	no	Opaque cursor from the previous page's `next_cursor`.
`limit`	query	`integer`	no	Page size. Default `30`.

Responses

List reviews: responses
Status	Meaning	Body
200 OK	A page of reviews.	`application/json`: `ReviewPage`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
410	The resource existed and is permanently unavailable (retracted item, expired plan).	`Problem`. Codes: `gone`, `plan_expired`
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/items/acme/invoice-extractor/reviews'

Python

python

import reuseforge

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

for entry in client.list_reviews("acme/invoice-extractor"):  # iterating fetches further pages on demand
    print(entry["id"])

JavaScript

javascript

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

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

for await (const entry of client.listReviews("acme/invoice-extractor")) {  // iterating fetches further pages on demand
  console.log(entry.id);
}

CLI

bash

rf reviews list acme/invoice-extractor

# rf reviews list <item> [options]
# all options: rf reviews list --help

Response 200 OK:

json

{
  "data": [
    {
      "id": "rev_samharness22",
      "object": "review",
      "item": "janedoe/invoice-rag-harness",
      "author": {
        "id": "acc_samdevuser22",
        "type": "user",
        "handle": "samdev",
        "display_name": "Sam Okafor",
        "verified": false,
        "avatar_url": ""
      },
      "rating": 4,
      "title": "Worked after one config tweak",
      "body": "Indexed 400 invoices in under a minute. The citation links are the best part. Docs skip the Windows path setup.",
      "verified_purchase": true,
      "basis": "purchase",
      "created_at": "2026-11-02T18:20:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Review an item

POST /items/{owner}/{slug}/reviews Enabled on reuseforge.com

One review per account per item, from a verified buyer only. Paid items require a released order that contains the item (basis: purchase). Free items require that your account has fetched the install descriptor or bundle (basis: install). Owners cannot review their own items. Remove yours with delete_review to write a new one. If a moderator removed your review, you cannot post a new one: 403 review_removed.

Review an item: facts
Property	Value
Operation ID	`create_review`
Authentication	Bearer token holding `items:write`
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.create_review(...)`
JavaScript SDK	`client.createReview(...)`
CLI	`rf reviews create`
MCP tool	`create_review`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Review an item: 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.
`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`.

Request body

application/json, required, schema ReviewCreate

Review an item: request fields
Field	Type	Required
`rating`	`integer`	yes
`title`	`string`	no
`body`	`string`	no

Responses

Review an item: responses
Status	Meaning	Body
201 Created	The review.	`application/json`: `Review`
400	The request is malformed (bad JSON, unknown or mistyped parameter, invalid cursor).	`Problem`. Codes: `invalid_request`, `invalid_json`, `invalid_parameter`, `invalid_cursor`, `idempotency_key_required`
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`
410	The resource existed and is permanently unavailable (retracted item, expired plan).	`Problem`. Codes: `gone`, `plan_expired`
422	The body is well-formed JSON but invalid (`validation_failed` with per-field `errors`), or a business rule rejects it (`payment_invalid`, `webhook_url_forbidden`, `idempotency_key_reuse`).	`Problem`. Codes: `validation_failed`, `payment_invalid`, `rail_unsupported`, `idempotency_key_reuse`, `webhook_url_forbidden`, `invalid_signature`, `integrity_mismatch`
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/reviews' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "rating": 4,
  "title": "Worked after one config tweak",
  "body": "Indexed 400 invoices in under a minute. The citation links are the best part. Docs skip the Windows path setup."
}'

Python

python

import reuseforge

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

result = client.create_review(
    "acme/invoice-extractor",
    rating=4,
    title="Worked after one config tweak",
    body="Indexed 400 invoices in under a minute. The citation links are the best part. Docs skip the Windows path setup.",
)
print(result["id"])

JavaScript

javascript

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

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

const result = await client.createReview("acme/invoice-extractor", {
  rating: 4,
  title: "Worked after one config tweak",
  body: "Indexed 400 invoices in under a minute. The citation links are the best part. Docs skip the Windows path setup.",
});
console.log(result.id);

CLI

bash

rf reviews create acme/invoice-extractor --rating 4 --title 'Worked after one config tweak' --body 'Indexed 400 invoices in under a minute. The citation links are the best part. Docs skip the Windows path setup.'

# rf reviews create <item> [options]
# all options: rf reviews create --help

Response 201 Created:

json

{
  "id": "rev_samharness22",
  "object": "review",
  "item": "janedoe/invoice-rag-harness",
  "author": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "rating": 4,
  "title": "Worked after one config tweak",
  "body": "Indexed 400 invoices in under a minute. The citation links are the best part. Docs skip the Windows path setup.",
  "verified_purchase": true,
  "basis": "purchase",
  "created_at": "2026-11-02T18:20:00Z"
}

Delete your review

DELETE /items/{owner}/{slug}/reviews/mine Enabled on reuseforge.com

Idempotent. A review a moderator removed cannot be deleted by its author (it stays as a tombstone); that answers 403 review_removed.

Delete your review: facts
Property	Value
Operation ID	`delete_review`
Authentication	Bearer token holding `items:write`
Rate tier	`write`: not allowed anonymous, 120/min per token with a token
Python SDK	`client.delete_review(...)`
JavaScript SDK	`client.deleteReview(...)`
CLI	`rf reviews delete`
MCP tool	`delete_review`
Deployments	reuseforge.com: enabled. Python node: not implemented (answers `501`).

Parameters

Delete your review: 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.

Responses

Delete your review: responses
Status	Meaning	Body
204 No Content	Deleted.	no body
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`
410	The resource existed and is permanently unavailable (retracted item, expired plan).	`Problem`. Codes: `gone`, `plan_expired`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X DELETE 'https://reuseforge.com/api/v1/items/acme/invoice-extractor/reviews/mine' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN"

Python

python

import reuseforge

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

client.delete_review("acme/invoice-extractor")

JavaScript

javascript

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

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

await client.deleteReview("acme/invoice-extractor");

CLI

bash

rf reviews delete acme/invoice-extractor

# rf reviews delete <item>
# all options: rf reviews delete --help

Response 204 No Content with an empty body.