API
ReuseForge API
The ReuseForge HTTP API v1, the Python and JavaScript SDKs, the rf command line, the hosted MCP server and webhooks, with one contract behind all of them.
One JSON API sits behind the website, the SDKs, the rf command line and the hosted MCP server. A goal and a budget in US dollars go in; a plan of items to reuse, buy or build comes out; paid items sit in escrow until the buyer confirms. Everything on these pages is generated from the OpenAPI contract (api/openapi.yaml, version 1.1.0) or checked against the code, so the operation list, the scopes and the examples are the contract's own.
Test mode. Payments run on a simulated rail and no real money moves. GET /api/v1/ lists the rails and which are enabled. Operations that are in the contract but not switched on for a deployment answer 501 not_implemented; the availability table says which.
Start in five minutes
- Quickstart: get a token, search, plan, install and buy, in curl, Python, JavaScript and the CLI.
- Authentication and scopes: tokens, the 12 scopes, and the spend limit that keeps an agent from overspending.
- Operation reference: all operations with parameters, bodies, errors and examples in four languages.
- Hosted MCP server:
claude mcp add --transport http reuseforge https://reuseforge.com/mcp.
Ways to call it
| You are | Use | Install |
|---|---|---|
| Writing Python | Python SDK: one method per operation, retries, pagination, safe installs | pip install ./sdk/python from a checkout |
| Writing JavaScript or TypeScript | JavaScript SDK: Node, Workers, Deno, Bun and browsers, typed | npm install ./sdk/js from a checkout |
| In a terminal or CI | rf command line: search, plan, install, publish, buy | npm install -g ./cli from a checkout |
| Building an agent | Hosted MCP server: the same operations as tools | add https://reuseforge.com/mcp to your client |
| Anything else | The HTTP API with curl or any client | nothing: it is JSON over HTTPS |
The SDKs and the CLI are not on PyPI or npm yet. Install them from a checkout of the repository as shown above; the guides say so wherever it matters.
What is enabled
The contract describes 72 operations. A deployment answers 501 not_implemented for those it does not provide yet. This table is read from the source of the hosted Worker and of the self-hosted Python node when these pages are built.
| Area | reuseforge.com | Python node |
|---|---|---|
| Meta | 5 of 5 | 5 of 5 |
| Identity | 2 of 2 | 2 of 2 |
| Tokens | 3 of 3 | 0 of 3 |
| Items | 8 of 8 | 5 of 8 |
| Reviews | 3 of 3 | 2 of 3 |
| Versions | 6 of 6 | 4 of 6 |
| Distribution | 2 of 2 | 0 of 2 |
| Verification | 2 of 2 | 0 of 2 |
| Planning | 6 of 6 | 6 of 6 |
| Orders | 12 of 12 | 9 of 12 |
| Projects | 0 of 12 | 10 of 12 |
| Webhooks | 9 of 9 | 0 of 9 |
| Ledger | 0 of 2 | 2 of 2 |
| All | 58 of 72 | 45 of 72 |
The hosted payments group (orders, payouts, projects) is built but not switched on for reuseforge.com yet; the self-hosted node runs it today on simulated payments. See self-hosting.
Conventions
| Topic | Rule |
|---|---|
| Base URL | https://reuseforge.com/api/v1. Self-hosted: http://127.0.0.1:8420/api/v1. |
| Format | JSON only, snake_case keys, the same bytes in curl, the SDKs and the CLI. No case conversion anywhere. |
| Money | Integer US cents in fields ending _cents, with currency: "USD". Rates are basis points in fields ending _bps. No decimal dollars on the wire. |
| Ids | <prefix>_<random>: itm_ item, ver_ version, ord_ order, pln_ plan, tok_ token, whk_ webhook. Never parse beyond the prefix. |
| Items | Addressed as owner/slug or by id. The Python code calls the same thing a block. |
| Time | RFC 3339 UTC strings (2026-11-03T10:00:00Z). Webhook signature timestamps are unix seconds. |
| Lists | {data, next_cursor, has_more}. Never a bare array. See pagination. |
| Errors | application/problem+json with a stable code. See errors. |
| Evolution | Additive only inside /v1. Ignore unknown fields and unknown enum values. See versioning. |
| Every response | X-Request-Id, ReuseForge-Version, RateLimit-*. Quote the request id when you ask for help. |
| CORS | Open (*, no credentials). Browsers can call it with a bearer token. Session cookies are honoured only for the site's own web app, never cross-site. |
Scopes
A token carries scopes; an operation lists the scopes it needs and all of them are required. Public reads need none. The full explanation, including how a person grants a token and why orders:accept is different, is in authentication.
| Scope | Allows | Operations |
|---|---|---|
items:read | Read your private and unlisted items, item statistics and your stars. | none (widens public reads) |
items:write | Create, edit, retract, star and review items you may act for. | 8 |
items:publish | Publish and yank versions and request verifications. | 3 |
orders:read | Read your orders, payouts and earnings. | 4 |
orders:create | Create, cancel and dispute orders; deliver or refund items you sell. Cannot move money. | 5 |
orders:pay | Fund escrow for an order or a project backing. Bounded by the token spend limit. | 2 |
orders:accept | Confirm satisfaction and release escrow. Irreversible. Never granted by default. Only a signed-in person can grant it. | 1 |
projects:read | Read your portfolio. | 1 |
projects:write | Create projects, deliver and vote on milestones, transfer units. | 9 |
webhooks:manage | Create, read, update and delete webhooks and read deliveries. | 9 |
tokens:manage | List, create and revoke API tokens. | 3 |
admin | Platform operator actions (dispute resolution). Honoured only for admin accounts. | 1 |
Areas of the API
| Area | Operations | Covers |
|---|---|---|
| Meta | 5 | Index, health, contract, event catalogue and rate limit status. |
| Identity | 2 | The authenticated principal and public profiles. |
| Tokens | 3 | Personal access tokens with scopes, expiry and spend limits. |
| Items | 8 | Search, publish and manage items. |
| Reviews | 3 | Reviews by verified buyers. |
| Versions | 6 | Immutable published versions, bundles and install descriptors. |
| Distribution | 2 | Archives and hosted marketplaces for tools that do not speak this API (unzip, Claude Code plugin marketplaces). |
| Verification | 2 | Test attestations that feed the risk and quality signals. |
| Planning | 6 | Goal to Pareto plan, build briefs, external discovery, MCP config. |
| Orders | 12 | Escrowed orders, payments, delivery, acceptance and disputes. |
| Projects | 12 | Crowdfunded builds with milestones and revenue units. |
| Webhooks | 9 | Signed event delivery to your servers. |
| Ledger | 2 | Signed event feed for syncing self-hosted nodes with the hosted platform. |
Machine-readable
| File | What it is |
|---|---|
/docs/api/openapi.json and openapi.yaml | The OpenAPI 3.1 contract, with an example for every request and response. Also served live at GET /api/v1/openapi.json. |
/llms.txt | A short index for language models, following the llms.txt convention. |
/llms-full.txt | These documents as one Markdown file: guides, every operation, the error catalogue, the CLI and the MCP tools. |
/docs/api/search-index.json | Operations, pages and sections as JSON. |
/docs/api/schemas/reuseforge.schema.json | JSON Schema of the publish manifest reuseforge.json. |
https://reuseforge.com/.well-known/mcp/server-card.json | MCP server card for the hosted server. |
Every error response has a type that is a URL on this site, for example /docs/api/errors/insufficient_scope/.
Last updated: