API

Planning operations

Goal to Pareto plan, build briefs, external discovery, MCP config.

Goal to Pareto plan, build briefs, external discovery, MCP config. Paths are relative to https://reuseforge.com/api/v1.

Operations in this area
Operation	Method	Path
Plan a goal	`POST`	`/plans`
Get a plan	`GET`	`/plans/{plan_id}`
Build brief for the parts to build	`GET`	`/plans/{plan_id}/brief`
Discover external candidates	`GET`	`/discover`
MCP configuration for a goal	`GET`	`/mcp-config`
List connectors	`GET`	`/connectors`

Plan a goal

POST /plans Enabled on reuseforge.com

Turns a goal and an optional budget into requirements, a Pareto front of plans over (quality up, cost down, risk down) and a recommended plan, each with explanations. Every requirement is either covered by reusing a candidate (free or paid) or by building it from blueprints (arXiv papers). Shared paid items are counted once.

The result is stored for 24 hours under id (pln_...); pass it to create_order, build_brief and get_mcp_config. With online: true the planner also queries external connectors; if some fail, the plan is still returned with partial: true and per-connector status in sources. Anonymous callers are limited to 5 plans a minute.

Plan a goal: facts
Property	Value
Operation ID	`plan_goal`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`plan`: 5/min per IP and 40/day anonymous, 20/min per token and 500/day with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.plan_goal(...)`
JavaScript SDK	`client.planGoal(...)`
CLI	`rf plan`
MCP tool	`plan_goal`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Plan a goal: parameters
Name	In	Type	Required	Description
`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 PlanRequest

Plan a goal: request fields
Field	Type	Required	Description
`goal`	`string`	yes
`budget_cents`	`integer` or `null`	no	Null or omitted means no budget.
`online`	`boolean`	no	Also query external connectors. Default `false`.
`connectors`	array of `string`	no	Restrict external discovery.
`llm`	`boolean`	no	Decompose the goal with an LLM instead of the keyword taxonomy. Default `false`.
`per_requirement`	`integer`	no	Default `4`.
`constraints`	`object`	no
`constraints.exclude_paid`	`boolean`	no	Default `false`.
`constraints.allowed_licenses`	array of `string`	no
`constraints.max_risk`	`number`	no
`constraints.kinds`	array of `BlockKind`	no
`constraints.deny_licenses`	array of `string`	no	Licence ids to refuse. Case-insensitive; a trailing `` matches a prefix (`CC-BY-NC`).
`constraints.prefer_free`	`boolean`	no	Recommend the best plan without paid items when it scores within 0.10 of the overall best. Default `false`.
`constraints.require_verified`	`boolean`	no	Only reuse blocks from sellers with a verified purchase or a verified badge, and from external sources. Default `false`.
`constraints.max_options_per_requirement`	`integer`	no	Overrides `per_requirement` for this plan.

Responses

Plan a goal: responses
Status	Meaning	Body
201 Created	The stored plan.	`application/json`: `Plan`
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`
413	The body or a file exceeds a limit published in `get_api_index`.	`Problem`. Codes: `payload_too_large`
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`
502	An upstream source (connector, chain RPC) failed or timed out. Retry with backoff.	`Problem`. Codes: `upstream_error`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/plans' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "goal": "RAG chatbot over my PDF invoices with a dashboard and crypto checkout",
  "budget_cents": 5000,
  "online": true,
  "constraints": {
    "exclude_paid": false,
    "allowed_licenses": [
      "MIT",
      "Apache-2.0",
      "BSD-3-Clause",
      "Commercial-Single-Project"
    ],
    "max_risk": 0.6
  }
}'

Python

python

import reuseforge

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

result = client.plan_goal(
    goal="RAG chatbot over my PDF invoices with a dashboard and crypto checkout",
    budget_cents=5000,
    online=True,
    constraints={
            "exclude_paid": False,
            "allowed_licenses": ["MIT", "Apache-2.0", "BSD-3-Clause", "Commercial-Single-Project"],
            "max_risk": 0.6,
        },
)
print(result["id"])

JavaScript

javascript

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

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

const result = await client.planGoal({
  goal: "RAG chatbot over my PDF invoices with a dashboard and crypto checkout",
  budget_cents: 5000,
  online: true,
  constraints: {
    exclude_paid: false,
    allowed_licenses: ["MIT", "Apache-2.0", "BSD-3-Clause", "Commercial-Single-Project"],
    max_risk: 0.6,
  },
});
console.log(result.id);

CLI

bash

rf plan 'RAG chatbot over my PDF invoices with a dashboard and crypto checkout' --budget 50 --online

# rf plan <goal>... [options]
# all options: rf plan --help

Response 201 Created:

json

{
  "id": "pln_goalinvoice2",
  "object": "plan",
  "goal": "RAG chatbot over my PDF invoices with a dashboard and crypto checkout",
  "budget_cents": 5000,
  "currency": "USD",
  "created_at": "2026-11-03T10:00:00Z",
  "expires_at": "2026-11-04T10:00:00Z",
  "requirements": [
    {
      "capability": "document-parsing",
      "description": "document parsing (pdf, invoices)",
      "keywords": [
        "pdf",
        "invoices"
      ]
    },
    {
      "capability": "retrieval-rag",
      "description": "retrieval rag (rag, documents)",
      "keywords": [
        "rag",
        "documents"
      ]
    },
    {
      "capability": "crypto-payments",
      "description": "crypto payments (crypto, escrow)",
      "keywords": [
        "crypto",
        "escrow"
      ]
    }
  ],
  "pareto_front": [
    {
      "index": 0,
      "objectives": {
        "quality": 0.69,
        "cost_cents": 2000,
        "risk": 0.17
      },
      "paid_total_cents": 1200,
      "build_total_cents": 800,
      "steps": [
        {
          "requirement": "document-parsing",
          "action": "use",
          "candidate": {
            "id": "itm_invoiceextr2",
            "name": "Invoice extractor",
            "kind": "skill",
            "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.",
            "url": "https://reuseforge.com/app/acme/invoice-extractor",
            "capabilities": [
              "document-parsing",
              "data-analysis"
            ],
            "license": "MIT",
            "price_cents": 0,
            "currency": "USD",
            "version": "1.4.0",
            "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c",
            "owner": "acme",
            "origin": "reuseforge",
            "signals": {
              "stars": 1860,
              "downloads": 9120,
              "tests_pass_rate": 0.97
            },
            "rating": 4.6,
            "rating_count": 18,
            "project_id": null,
            "item": "acme/invoice-extractor",
            "quality": 0.83,
            "risk": 0.0,
            "payout_rails": []
          },
          "quality": 0.83,
          "cost_cents": 0,
          "risk": 0.0,
          "blueprints": []
        },
        {
          "requirement": "retrieval-rag",
          "action": "use",
          "candidate": {
            "id": "itm_ragharness22",
            "name": "Invoice RAG harness",
            "kind": "harness",
            "summary": "Agent harness that indexes invoices, answers spend questions with citations and exports a dashboard.",
            "url": "https://reuseforge.com/app/janedoe/invoice-rag-harness",
            "capabilities": [
              "retrieval-rag",
              "llm-chat",
              "data-analysis"
            ],
            "license": "Commercial-Single-Project",
            "price_cents": 1200,
            "currency": "USD",
            "version": "0.9.2",
            "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c",
            "owner": "janedoe",
            "origin": "reuseforge",
            "signals": {
              "stars": 37,
              "downloads": 64,
              "tests_pass_rate": 0.91
            },
            "rating": 4.3,
            "rating_count": 3,
            "project_id": null,
            "item": "janedoe/invoice-rag-harness",
            "quality": 0.74,
            "risk": 0.0,
            "payout_rails": [
              "base-usdc",
              "btc"
            ]
          },
          "quality": 0.74,
          "cost_cents": 1200,
          "risk": 0.0,
          "blueprints": []
        },
        {
          "requirement": "crypto-payments",
          "action": "build",
          "candidate": null,
          "quality": 0.5,
          "cost_cents": 800,
          "risk": 0.5,
          "blueprints": [
            {
              "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
              "url": "https://arxiv.org/abs/2005.11401"
            }
          ]
        }
      ],
      "paid_items": [
        {
          "item": "janedoe/invoice-rag-harness",
          "item_id": "itm_ragharness22",
          "name": "Invoice RAG harness",
          "version": "0.9.2",
          "seller": "janedoe",
          "price_cents": 1200,
          "project_id": null
        }
      ]
    },
    {
      "index": 1,
      "objectives": {
        "quality": 0.5,
        "cost_cents": 800,
        "risk": 0.17
      },
      "paid_total_cents": 0,
      "build_total_cents": 800,
      "steps": [
        {
          "requirement": "document-parsing",
          "action": "use",
          "candidate": {
            "id": "itm_invoiceextr2",
            "name": "Invoice extractor",
            "kind": "skill",
            "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.",
            "url": "https://reuseforge.com/app/acme/invoice-extractor",
            "capabilities": [
              "document-parsing",
              "data-analysis"
            ],
            "license": "MIT",
            "price_cents": 0,
            "currency": "USD",
            "version": "1.4.0",
            "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c",
            "owner": "acme",
            "origin": "reuseforge",
            "signals": {
              "stars": 1860,
              "downloads": 9120,
              "tests_pass_rate": 0.97
            },
            "rating": 4.6,
            "rating_count": 18,
            "project_id": null,
            "item": "acme/invoice-extractor",
            "quality": 0.83,
            "risk": 0.0,
            "payout_rails": []
          },
          "quality": 0.83,
          "cost_cents": 0,
          "risk": 0.0,
          "blueprints": []
        },
        {
          "requirement": "retrieval-rag",
          "action": "build",
          "candidate": null,
          "quality": 0.5,
          "cost_cents": 800,
          "risk": 0.5,
          "blueprints": []
        },
        {
          "requirement": "crypto-payments",
          "action": "build",
          "candidate": null,
          "quality": 0.5,
          "cost_cents": 800,
          "risk": 0.5,
          "blueprints": [
            {
              "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
              "url": "https://arxiv.org/abs/2005.11401"
            }
          ]
        }
      ],
      "paid_items": []
    }
  ],
  "recommended": {
    "index": 0,
    "objectives": {
      "quality": 0.69,
      "cost_cents": 2000,
      "risk": 0.17
    },
    "paid_total_cents": 1200,
    "build_total_cents": 800,
    "steps": [
      {
        "requirement": "document-parsing",
        "action": "use",
        "candidate": {
          "id": "itm_invoiceextr2",
          "name": "Invoice extractor",
          "kind": "skill",
          "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.",
          "url": "https://reuseforge.com/app/acme/invoice-extractor",
          "capabilities": [
            "document-parsing",
            "data-analysis"
          ],
          "license": "MIT",
          "price_cents": 0,
          "currency": "USD",
          "version": "1.4.0",
          "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c",
          "owner": "acme",
          "origin": "reuseforge",
          "signals": {
            "stars": 1860,
            "downloads": 9120,
            "tests_pass_rate": 0.97
          },
          "rating": 4.6,
          "rating_count": 18,
          "project_id": null,
          "item": "acme/invoice-extractor",
          "quality": 0.83,
          "risk": 0.0,
          "payout_rails": []
        },
        "quality": 0.83,
        "cost_cents": 0,
        "risk": 0.0,
        "blueprints": []
      },
      {
        "requirement": "retrieval-rag",
        "action": "use",
        "candidate": {
          "id": "itm_ragharness22",
          "name": "Invoice RAG harness",
          "kind": "harness",
          "summary": "Agent harness that indexes invoices, answers spend questions with citations and exports a dashboard.",
          "url": "https://reuseforge.com/app/janedoe/invoice-rag-harness",
          "capabilities": [
            "retrieval-rag",
            "llm-chat",
            "data-analysis"
          ],
          "license": "Commercial-Single-Project",
          "price_cents": 1200,
          "currency": "USD",
          "version": "0.9.2",
          "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c",
          "owner": "janedoe",
          "origin": "reuseforge",
          "signals": {
            "stars": 37,
            "downloads": 64,
            "tests_pass_rate": 0.91
          },
          "rating": 4.3,
          "rating_count": 3,
          "project_id": null,
          "item": "janedoe/invoice-rag-harness",
          "quality": 0.74,
          "risk": 0.0,
          "payout_rails": [
            "base-usdc",
            "btc"
          ]
        },
        "quality": 0.74,
        "cost_cents": 1200,
        "risk": 0.0,
        "blueprints": []
      },
      {
        "requirement": "crypto-payments",
        "action": "build",
        "candidate": null,
        "quality": 0.5,
        "cost_cents": 800,
        "risk": 0.5,
        "blueprints": [
          {
            "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
            "url": "https://arxiv.org/abs/2005.11401"
          }
        ]
      }
    ],
    "paid_items": [
      {
        "item": "janedoe/invoice-rag-harness",
        "item_id": "itm_ragharness22",
        "name": "Invoice RAG harness",
        "version": "0.9.2",
        "seller": "janedoe",
        "price_cents": 1200,
        "project_id": null
      }
    ]
  },
  "recommended_index": 0,
  "explanations": [
    {
      "scope": "plan",
      "ref": "0",
      "kind": "rationale",
      "text": "Highest quality within the $50.00 budget: reuses a verified free extractor and buys one tested harness for $12.00."
    },
    {
      "scope": "requirement",
      "ref": "crypto-payments",
      "kind": "warning",
      "text": "No reusable block found for crypto-payments. Budgeted $8.00 of agent tokens to build it from the linked paper."
    },
    {
      "scope": "option",
      "ref": "1",
      "kind": "tradeoff",
      "text": "Saves $12.00 but drops quality from 0.69 to 0.50 because the RAG layer is built from scratch."
    }
  ],
  "sources": [
    {
      "connector": "reuseforge",
      "status": "ok",
      "count": 6,
      "duration_ms": 41
    },
    {
      "connector": "github",
      "status": "ok",
      "count": 3,
      "duration_ms": 612
    },
    {
      "connector": "arxiv",
      "status": "ok",
      "count": 2,
      "duration_ms": 388
    }
  ],
  "note": null,
  "partial": false
}

Get a plan

GET /plans/{plan_id} Enabled on reuseforge.com

A plan created in the last 24 hours. The id is unguessable and acts as a capability; anyone holding it can read the plan. Expired plans return 410.

Get a plan: facts
Property	Value
Operation ID	`get_plan`
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_plan(...)`
JavaScript SDK	`client.getPlan(...)`
CLI	`rf plans get`
MCP tool	`get_plan`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Get a plan: parameters
Name	In	Type	Required	Description
`plan_id`	path	`string`	yes

Responses

Get a plan: responses
Status	Meaning	Body
200 OK	The plan.	`application/json`: `Plan`
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/plans/pln_goalinvoice2'

Python

python

import reuseforge

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

result = client.get_plan("pln_goalinvoice2")
print(result["id"])

JavaScript

javascript

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

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

const result = await client.getPlan("pln_goalinvoice2");
console.log(result.id);

CLI

bash

rf plans get pln_goalinvoice2

# rf plans get <plan_id>
# all options: rf plans get --help

Response 200 OK:

json

{
  "id": "pln_goalinvoice2",
  "object": "plan",
  "goal": "RAG chatbot over my PDF invoices with a dashboard and crypto checkout",
  "budget_cents": 5000,
  "currency": "USD",
  "created_at": "2026-11-03T10:00:00Z",
  "expires_at": "2026-11-04T10:00:00Z",
  "requirements": [
    {
      "capability": "document-parsing",
      "description": "document parsing (pdf, invoices)",
      "keywords": [
        "pdf",
        "invoices"
      ]
    },
    {
      "capability": "retrieval-rag",
      "description": "retrieval rag (rag, documents)",
      "keywords": [
        "rag",
        "documents"
      ]
    },
    {
      "capability": "crypto-payments",
      "description": "crypto payments (crypto, escrow)",
      "keywords": [
        "crypto",
        "escrow"
      ]
    }
  ],
  "pareto_front": [
    {
      "index": 0,
      "objectives": {
        "quality": 0.69,
        "cost_cents": 2000,
        "risk": 0.17
      },
      "paid_total_cents": 1200,
      "build_total_cents": 800,
      "steps": [
        {
          "requirement": "document-parsing",
          "action": "use",
          "candidate": {
            "id": "itm_invoiceextr2",
            "name": "Invoice extractor",
            "kind": "skill",
            "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.",
            "url": "https://reuseforge.com/app/acme/invoice-extractor",
            "capabilities": [
              "document-parsing",
              "data-analysis"
            ],
            "license": "MIT",
            "price_cents": 0,
            "currency": "USD",
            "version": "1.4.0",
            "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c",
            "owner": "acme",
            "origin": "reuseforge",
            "signals": {
              "stars": 1860,
              "downloads": 9120,
              "tests_pass_rate": 0.97
            },
            "rating": 4.6,
            "rating_count": 18,
            "project_id": null,
            "item": "acme/invoice-extractor",
            "quality": 0.83,
            "risk": 0.0,
            "payout_rails": []
          },
          "quality": 0.83,
          "cost_cents": 0,
          "risk": 0.0,
          "blueprints": []
        },
        {
          "requirement": "retrieval-rag",
          "action": "use",
          "candidate": {
            "id": "itm_ragharness22",
            "name": "Invoice RAG harness",
            "kind": "harness",
            "summary": "Agent harness that indexes invoices, answers spend questions with citations and exports a dashboard.",
            "url": "https://reuseforge.com/app/janedoe/invoice-rag-harness",
            "capabilities": [
              "retrieval-rag",
              "llm-chat",
              "data-analysis"
            ],
            "license": "Commercial-Single-Project",
            "price_cents": 1200,
            "currency": "USD",
            "version": "0.9.2",
            "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c",
            "owner": "janedoe",
            "origin": "reuseforge",
            "signals": {
              "stars": 37,
              "downloads": 64,
              "tests_pass_rate": 0.91
            },
            "rating": 4.3,
            "rating_count": 3,
            "project_id": null,
            "item": "janedoe/invoice-rag-harness",
            "quality": 0.74,
            "risk": 0.0,
            "payout_rails": [
              "base-usdc",
              "btc"
            ]
          },
          "quality": 0.74,
          "cost_cents": 1200,
          "risk": 0.0,
          "blueprints": []
        },
        {
          "requirement": "crypto-payments",
          "action": "build",
          "candidate": null,
          "quality": 0.5,
          "cost_cents": 800,
          "risk": 0.5,
          "blueprints": [
            {
              "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
              "url": "https://arxiv.org/abs/2005.11401"
            }
          ]
        }
      ],
      "paid_items": [
        {
          "item": "janedoe/invoice-rag-harness",
          "item_id": "itm_ragharness22",
          "name": "Invoice RAG harness",
          "version": "0.9.2",
          "seller": "janedoe",
          "price_cents": 1200,
          "project_id": null
        }
      ]
    },
    {
      "index": 1,
      "objectives": {
        "quality": 0.5,
        "cost_cents": 800,
        "risk": 0.17
      },
      "paid_total_cents": 0,
      "build_total_cents": 800,
      "steps": [
        {
          "requirement": "document-parsing",
          "action": "use",
          "candidate": {
            "id": "itm_invoiceextr2",
            "name": "Invoice extractor",
            "kind": "skill",
            "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.",
            "url": "https://reuseforge.com/app/acme/invoice-extractor",
            "capabilities": [
              "document-parsing",
              "data-analysis"
            ],
            "license": "MIT",
            "price_cents": 0,
            "currency": "USD",
            "version": "1.4.0",
            "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c",
            "owner": "acme",
            "origin": "reuseforge",
            "signals": {
              "stars": 1860,
              "downloads": 9120,
              "tests_pass_rate": 0.97
            },
            "rating": 4.6,
            "rating_count": 18,
            "project_id": null,
            "item": "acme/invoice-extractor",
            "quality": 0.83,
            "risk": 0.0,
            "payout_rails": []
          },
          "quality": 0.83,
          "cost_cents": 0,
          "risk": 0.0,
          "blueprints": []
        },
        {
          "requirement": "retrieval-rag",
          "action": "build",
          "candidate": null,
          "quality": 0.5,
          "cost_cents": 800,
          "risk": 0.5,
          "blueprints": []
        },
        {
          "requirement": "crypto-payments",
          "action": "build",
          "candidate": null,
          "quality": 0.5,
          "cost_cents": 800,
          "risk": 0.5,
          "blueprints": [
            {
              "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
              "url": "https://arxiv.org/abs/2005.11401"
            }
          ]
        }
      ],
      "paid_items": []
    }
  ],
  "recommended": {
    "index": 0,
    "objectives": {
      "quality": 0.69,
      "cost_cents": 2000,
      "risk": 0.17
    },
    "paid_total_cents": 1200,
    "build_total_cents": 800,
    "steps": [
      {
        "requirement": "document-parsing",
        "action": "use",
        "candidate": {
          "id": "itm_invoiceextr2",
          "name": "Invoice extractor",
          "kind": "skill",
          "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.",
          "url": "https://reuseforge.com/app/acme/invoice-extractor",
          "capabilities": [
            "document-parsing",
            "data-analysis"
          ],
          "license": "MIT",
          "price_cents": 0,
          "currency": "USD",
          "version": "1.4.0",
          "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c",
          "owner": "acme",
          "origin": "reuseforge",
          "signals": {
            "stars": 1860,
            "downloads": 9120,
            "tests_pass_rate": 0.97
          },
          "rating": 4.6,
          "rating_count": 18,
          "project_id": null,
          "item": "acme/invoice-extractor",
          "quality": 0.83,
          "risk": 0.0,
          "payout_rails": []
        },
        "quality": 0.83,
        "cost_cents": 0,
        "risk": 0.0,
        "blueprints": []
      },
      {
        "requirement": "retrieval-rag",
        "action": "use",
        "candidate": {
          "id": "itm_ragharness22",
          "name": "Invoice RAG harness",
          "kind": "harness",
          "summary": "Agent harness that indexes invoices, answers spend questions with citations and exports a dashboard.",
          "url": "https://reuseforge.com/app/janedoe/invoice-rag-harness",
          "capabilities": [
            "retrieval-rag",
            "llm-chat",
            "data-analysis"
          ],
          "license": "Commercial-Single-Project",
          "price_cents": 1200,
          "currency": "USD",
          "version": "0.9.2",
          "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c",
          "owner": "janedoe",
          "origin": "reuseforge",
          "signals": {
            "stars": 37,
            "downloads": 64,
            "tests_pass_rate": 0.91
          },
          "rating": 4.3,
          "rating_count": 3,
          "project_id": null,
          "item": "janedoe/invoice-rag-harness",
          "quality": 0.74,
          "risk": 0.0,
          "payout_rails": [
            "base-usdc",
            "btc"
          ]
        },
        "quality": 0.74,
        "cost_cents": 1200,
        "risk": 0.0,
        "blueprints": []
      },
      {
        "requirement": "crypto-payments",
        "action": "build",
        "candidate": null,
        "quality": 0.5,
        "cost_cents": 800,
        "risk": 0.5,
        "blueprints": [
          {
            "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
            "url": "https://arxiv.org/abs/2005.11401"
          }
        ]
      }
    ],
    "paid_items": [
      {
        "item": "janedoe/invoice-rag-harness",
        "item_id": "itm_ragharness22",
        "name": "Invoice RAG harness",
        "version": "0.9.2",
        "seller": "janedoe",
        "price_cents": 1200,
        "project_id": null
      }
    ]
  },
  "recommended_index": 0,
  "explanations": [
    {
      "scope": "plan",
      "ref": "0",
      "kind": "rationale",
      "text": "Highest quality within the $50.00 budget: reuses a verified free extractor and buys one tested harness for $12.00."
    },
    {
      "scope": "requirement",
      "ref": "crypto-payments",
      "kind": "warning",
      "text": "No reusable block found for crypto-payments. Budgeted $8.00 of agent tokens to build it from the linked paper."
    },
    {
      "scope": "option",
      "ref": "1",
      "kind": "tradeoff",
      "text": "Saves $12.00 but drops quality from 0.69 to 0.50 because the RAG layer is built from scratch."
    }
  ],
  "sources": [
    {
      "connector": "reuseforge",
      "status": "ok",
      "count": 6,
      "duration_ms": 41
    },
    {
      "connector": "github",
      "status": "ok",
      "count": 3,
      "duration_ms": 612
    },
    {
      "connector": "arxiv",
      "status": "ok",
      "count": 2,
      "duration_ms": 388
    }
  ],
  "note": null,
  "partial": false
}

Build brief for the parts to build

GET /plans/{plan_id}/brief Enabled on reuseforge.com

A markdown brief an autonomous coding agent can execute for the build steps of a plan option, with blueprints, the items it must integrate with, recommended MCP servers and rules. Defaults to the recommended option.

Build brief for the parts to build: facts
Property	Value
Operation ID	`build_brief`
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.build_brief(...)`
JavaScript SDK	`client.buildBrief(...)`
CLI	`rf plans brief`
MCP tool	`build_brief`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Build brief for the parts to build: parameters
Name	In	Type	Required	Description
`plan_id`	path	`string`	yes
`option`	query	`integer`	no	Index into `pareto_front`. Defaults to `recommended_index`.

Responses

Build brief for the parts to build: responses
Status	Meaning	Body
200 OK	The brief.	`application/json`: `Brief`
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`
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/plans/pln_goalinvoice2/brief'

Python

python

import reuseforge

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

result = client.build_brief("pln_goalinvoice2")
print(result)

JavaScript

javascript

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

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

const result = await client.buildBrief("pln_goalinvoice2");
console.log(result);

CLI

bash

rf plans brief pln_goalinvoice2

# rf plans brief <plan_id> [options]
# all options: rf plans brief --help

Response 200 OK:

json

{
  "plan_id": "pln_goalinvoice2",
  "option": 0,
  "brief": "# Build brief\n\nGoal: RAG chatbot over my PDF invoices with a dashboard and crypto checkout\n\n## Already covered (integrate, do not rebuild)\n- document-parsing: Invoice extractor (MIT) https://reuseforge.com/app/acme/invoice-extractor\n- retrieval-rag: Invoice RAG harness (Commercial-Single-Project) https://reuseforge.com/app/janedoe/invoice-rag-harness\n\n## You must build\n\n### crypto-payments  (budget ~$8.00 of agent tokens)\n- Blueprint: Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks https://arxiv.org/abs/2005.11401\n",
  "build_steps": [
    {
      "requirement": "crypto-payments",
      "budget_cents": 800,
      "blueprints": [
        {
          "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
          "url": "https://arxiv.org/abs/2005.11401"
        }
      ]
    }
  ],
  "mcp_servers": [
    "filesystem",
    "stripe"
  ]
}

Discover external candidates

GET /discover Enabled on reuseforge.com

Queries the external connectors (GitHub, MCP registry, arXiv, Hugging Face, npm, PyPI and others; see list_connectors) in parallel and returns normalised candidates with risk signals. At most 12 outbound calls are made per request. One failing connector never fails the request: its sources entry carries the error.

Discover external candidates: facts
Property	Value
Operation ID	`discover_external`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`discover`: 5/min per IP and 40/day anonymous, 10/min per token and 300/day with a token
Python SDK	`client.discover_external(...)`
JavaScript SDK	`client.discoverExternal(...)`
CLI	`rf discover`
MCP tool	`discover_external`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Discover external candidates: parameters
Name	In	Type	Required	Description
`q`	query	`string`	yes
`connectors`	query	array of `string`	no	Restrict to these connector names (comma separated). Default is every ready block source.
`kind`	query	array of `BlockKind`	no
`limit`	query	`integer`	no	Maximum results per connector. Default `3`.

Responses

Discover external candidates: responses
Status	Meaning	Body
200 OK	Candidates and per-connector status.	`application/json`: `DiscoverResult`
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`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`
502	An upstream source (connector, chain RPC) failed or timed out. Retry with backoff.	`Problem`. Codes: `upstream_error`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/discover?q=pdf%20invoice%20extraction'

Python

python

import reuseforge

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

result = client.discover_external(q="pdf invoice extraction")
print(result["id"])

JavaScript

javascript

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

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

const result = await client.discoverExternal({ q: "pdf invoice extraction" });
console.log(result.id);

CLI

bash

rf discover 'pdf invoice extraction'

# rf discover <query>... [options]
# all options: rf discover --help

Response 200 OK:

json

{
  "data": [
    {
      "id": "blk_4f1c9a77be02d315",
      "name": "Unstructured-IO/unstructured",
      "kind": "repo",
      "summary": "Open-source components for ingesting and pre-processing PDFs, images and documents.",
      "url": "https://github.com/Unstructured-IO/unstructured",
      "capabilities": [
        "document-parsing"
      ],
      "license": "Apache-2.0",
      "price_cents": 0,
      "currency": "USD",
      "version": "0.0.0",
      "content_hash": "",
      "owner": "Unstructured-IO",
      "origin": "github",
      "signals": {
        "stars": 11200,
        "forks": 880,
        "open_issues": 134,
        "dependents": 2300,
        "scorecard": 6.8,
        "vulns_total": 0,
        "vulns_critical_high": 0,
        "archived": 0,
        "days_since_update": 3
      },
      "rating": 0,
      "rating_count": 0,
      "project_id": null,
      "item": null,
      "quality": 0.61,
      "risk": 0.0,
      "payout_rails": []
    },
    {
      "id": "blk_a02b6e19c4d7f853",
      "name": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
      "kind": "paper",
      "summary": "Combines a pretrained seq2seq model with a dense retriever over Wikipedia.",
      "url": "https://arxiv.org/abs/2005.11401",
      "capabilities": [
        "retrieval-rag"
      ],
      "license": "arXiv-nonexclusive",
      "price_cents": 0,
      "currency": "USD",
      "version": "0.0.0",
      "content_hash": "",
      "owner": "",
      "origin": "arxiv",
      "signals": {
        "citations": 9100
      },
      "rating": 0,
      "rating_count": 0,
      "project_id": null,
      "item": null,
      "quality": 0.5,
      "risk": 0.5,
      "payout_rails": []
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "sources": [
    {
      "connector": "github",
      "status": "ok",
      "count": 1,
      "duration_ms": 540
    },
    {
      "connector": "arxiv",
      "status": "ok",
      "count": 1,
      "duration_ms": 402
    },
    {
      "connector": "huggingface",
      "status": "error",
      "count": 0,
      "duration_ms": 10012,
      "error": "upstream timed out"
    }
  ]
}

MCP configuration for a goal

GET /mcp-config Enabled on reuseforge.com

The .mcp.json fragment (Figma, Stripe, Playwright and others) an agent needs to execute a goal. Provide a plan, a goal or explicit capabilities. Secrets are never included; headers reference environment variables.

MCP configuration for a goal: facts
Property	Value
Operation ID	`get_mcp_config`
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_mcp_config(...)`
JavaScript SDK	`client.getMcpConfig(...)`
CLI	`rf mcp-config`
MCP tool	`get_mcp_config`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

MCP configuration for a goal: parameters
Name	In	Type	Required
`plan_id`	query	`string`	no
`goal`	query	`string`	no
`capabilities`	query	array of `string`	no

Responses

MCP configuration for a goal: responses
Status	Meaning	Body
200 OK	The configuration.	`application/json`: `McpConfig`
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`
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/mcp-config'

Python

python

import reuseforge

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

result = client.get_mcp_config()
print(result)

JavaScript

javascript

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

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

const result = await client.getMcpConfig();
console.log(result);

CLI

bash

rf mcp-config

# rf mcp-config [options]
# all options: rf mcp-config --help

Response 200 OK:

json

{
  "mcpServers": {
    "stripe": {
      "type": "http",
      "url": "https://mcp.stripe.com"
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    }
  },
  "servers": [
    {
      "name": "stripe",
      "purpose": "Payments, subscriptions, invoices",
      "oauth": true,
      "verified": true,
      "token_env": "STRIPE_API_KEY"
    },
    {
      "name": "filesystem",
      "purpose": "Safe file access inside the project folder",
      "oauth": false,
      "verified": true,
      "token_env": null
    }
  ],
  "capabilities": [
    "payments",
    "document-parsing"
  ]
}

List connectors

GET /connectors Enabled on reuseforge.com

Block sources the planner and discover_external can query, and agent-side MCP servers that can be handed to a buyer's agent.

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

Responses

List connectors: responses
Status	Meaning	Body
200 OK	The connectors.	`application/json`: `ConnectorPage`
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/connectors'

Python

python

import reuseforge

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

result = client.list_connectors()
print(result["name"])

JavaScript

javascript

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

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

const result = await client.listConnectors();
console.log(result.name);

CLI

bash

rf connectors list

# rf connectors list [options]
# all options: rf connectors list --help

Response 200 OK:

json

{
  "data": [
    {
      "name": "reuseforge",
      "type": "builtin",
      "role": "block_source",
      "ready": true,
      "origin": "reuseforge",
      "description": "Items published on ReuseForge.",
      "kinds": [
        "repo",
        "skill",
        "harness",
        "mcp_server",
        "model",
        "dataset",
        "prompt",
        "template"
      ],
      "capabilities": [],
      "verified": true,
      "token_env": null,
      "oauth": false
    },
    {
      "name": "github",
      "type": "builtin",
      "role": "block_source",
      "ready": true,
      "origin": "github",
      "description": "Repositories with stars, forks, issues and OpenSSF scorecard.",
      "kinds": [
        "repo"
      ],
      "capabilities": [],
      "verified": true,
      "token_env": "GITHUB_TOKEN",
      "oauth": false
    },
    {
      "name": "arxiv",
      "type": "builtin",
      "role": "block_source",
      "ready": true,
      "origin": "arxiv",
      "description": "Papers used as build blueprints.",
      "kinds": [
        "paper"
      ],
      "capabilities": [],
      "verified": true,
      "token_env": null,
      "oauth": false
    },
    {
      "name": "stripe",
      "type": "mcp-http",
      "role": "agent_server",
      "ready": true,
      "origin": "stripe",
      "description": "Payments, subscriptions, invoices",
      "kinds": [],
      "capabilities": [
        "payments"
      ],
      "verified": true,
      "token_env": "STRIPE_API_KEY",
      "oauth": true
    }
  ],
  "next_cursor": null,
  "has_more": false
}