{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "ReuseForge API", "version": "1.1.0", "summary": "Share, find, buy and sell reusable code, skills, harnesses, MCP servers, models and papers.", "description": "The ReuseForge API v1 is the public contract behind the website, the `reuseforge` CLI (alias `rf`),\nthe Python and JavaScript SDKs and the hosted MCP server. Design record: `api/DESIGN.md`.\n\nA goal and a USD budget go in; a Pareto-optimal plan (quality up, cost down, risk down) of items to\nreuse, buy or build comes out. Paid items sit in escrow until the buyer confirms.\n\n**Conventions (all of them are normative)**\n\n* Base path `/api/v1`. JSON only (`application/json`); errors are `application/problem+json` (RFC 9457).\n* Resources are `items`, addressed as `owner/slug` or by id (`itm_...`). Ids are `_`.\n* **Money is an integer number of US cents** in fields ending `_cents`, next to `currency: \"USD\"`.\n Rates are integer basis points in fields ending `_bps`. There are no decimal dollar fields anywhere.\n* Timestamps are RFC 3339 UTC strings (`2026-11-03T10:00:00Z`). Webhook signature timestamps are unix seconds.\n* Collections return `{data, next_cursor, has_more}`; pass `next_cursor` back as `cursor`. Never a bare array.\n* Enums can grow in a minor release: clients must tolerate unknown enum values and unknown fields.\n* Unsafe `POST`s accept `Idempotency-Key` (kept 24 hours). It is required where money moves.\n* Every response carries `X-Request-Id`, `ReuseForge-Version` and the `RateLimit-*` headers.\n* Authentication is optional for public reads and a personal access token (`Authorization: Bearer rf_...`)\n otherwise. Scopes are listed in `x-scope-catalog`. Releasing escrow needs the explicit `orders:accept` scope.\n", "termsOfService": "https://reuseforge.com/terms", "contact": { "name": "ReuseForge developers", "url": "https://reuseforge.com/docs/api" }, "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "servers": [ { "url": "https://reuseforge.com/api/v1", "description": "Production" }, { "url": "http://localhost:8787/api/v1", "description": "wrangler dev" }, { "url": "http://127.0.0.1:8420/api/v1", "description": "Self-hosted Python node (python -m repoblock serve)" } ], "externalDocs": { "description": "API guide, SDKs and CLI", "url": "https://reuseforge.com/docs/api" }, "tags": [ { "name": "meta", "description": "Index, health, contract, event catalogue and rate limit status." }, { "name": "identity", "description": "The authenticated principal and public profiles." }, { "name": "tokens", "description": "Personal access tokens with scopes, expiry and spend limits." }, { "name": "items", "description": "Search, publish and manage items." }, { "name": "reviews", "description": "Reviews by verified buyers." }, { "name": "versions", "description": "Immutable published versions, bundles and install descriptors." }, { "name": "distribution", "description": "Archives and hosted marketplaces for tools that do not speak this API (unzip, Claude Code plugin marketplaces)." }, { "name": "verification", "description": "Test attestations that feed the risk and quality signals." }, { "name": "planning", "description": "Goal to Pareto plan, build briefs, external discovery, MCP config." }, { "name": "orders", "description": "Escrowed orders, payments, delivery, acceptance and disputes." }, { "name": "projects", "description": "Crowdfunded builds with milestones and revenue units." }, { "name": "webhooks", "description": "Signed event delivery to your servers." }, { "name": "ledger", "description": "Signed event feed for syncing self-hosted nodes with the hosted platform." } ], "security": [ {}, { "bearerAuth": [] } ], "x-scope-catalog": { "items:read": "Read your private and unlisted items, item statistics and your stars.", "items:write": "Create, edit, retract, star and review items you may act for.", "items:publish": "Publish and yank versions and request verifications.", "orders:read": "Read your orders, payouts and earnings.", "orders:create": "Create, cancel and dispute orders; deliver or refund items you sell. Cannot move money.", "orders:pay": "Fund escrow for an order or a project backing. Bounded by the token spend limit.", "orders:accept": "Confirm satisfaction and release escrow. Irreversible. Never granted by default.", "projects:read": "Read your portfolio.", "projects:write": "Create projects, deliver and vote on milestones, transfer units.", "webhooks:manage": "Create, read, update and delete webhooks and read deliveries.", "tokens:manage": "List, create and revoke API tokens.", "admin": "Platform operator actions (dispute resolution). Honoured only for admin accounts." }, "x-rate-limit-tiers": { "read": { "anonymous": "60/min per IP", "authenticated": "600/min per token" }, "write": { "anonymous": "not allowed", "authenticated": "120/min per token" }, "plan": { "anonymous": "5/min per IP and 40/day", "authenticated": "20/min per token and 500/day" }, "discover": { "anonymous": "5/min per IP and 40/day", "authenticated": "10/min per token and 300/day" }, "payments": { "anonymous": "not allowed", "authenticated": "30/min per token" } }, "x-fixtures": { "acct_acme": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "acct_jane": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "acct_sam": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "item_invoice": { "id": "itm_invoiceextr2", "object": "item", "owner": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "slug": "invoice-extractor", "full_name": "acme/invoice-extractor", "kind": "skill", "title": "Invoice extractor", "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.", "visibility": "public", "status": "active", "license": "MIT", "pricing_model": "free", "price_cents": 0, "currency": "USD", "source": { "provider": "github", "url": "https://github.com/acme/invoice-extractor", "ref": "acme/invoice-extractor" }, "homepage_url": "https://acme.example/invoice-extractor", "html_url": "https://reuseforge.com/app/acme/invoice-extractor", "capabilities": [ "document-parsing", "data-analysis" ], "tags": [ "pdf", "invoices", "ocr" ], "latest_version": "1.4.0", "verification": { "state": "passed", "version": "1.4.0", "tests_pass_rate": 0.97, "verified_at": "2026-10-28T09:12:40Z" }, "stats": { "stars": 412, "downloads": 9120, "reviews": 18, "sales": 0 }, "signals": { "stars": 1860, "downloads": 9120, "tests_pass_rate": 0.97, "forks": 143, "open_issues": 12, "days_since_update": 6 }, "rating": 4.6, "rating_count": 18, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-03-02T14:05:11Z", "updated_at": "2026-10-28T09:10:02Z" }, "item_harness": { "id": "itm_ragharness22", "object": "item", "owner": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "slug": "invoice-rag-harness", "full_name": "janedoe/invoice-rag-harness", "kind": "harness", "title": "Invoice RAG harness", "summary": "Agent harness that indexes invoices, answers spend questions with citations and exports a dashboard.", "visibility": "public", "status": "active", "license": "Commercial-Single-Project", "pricing_model": "fixed", "price_cents": 1200, "currency": "USD", "source": { "provider": "manual", "url": "", "ref": "" }, "homepage_url": "", "html_url": "https://reuseforge.com/app/janedoe/invoice-rag-harness", "capabilities": [ "retrieval-rag", "llm-chat", "data-analysis" ], "tags": [ "rag", "invoices", "dashboard" ], "latest_version": "0.9.2", "verification": { "state": "passed", "version": "0.9.2", "tests_pass_rate": 0.91, "verified_at": "2026-10-30T16:41:05Z" }, "stats": { "stars": 37, "downloads": 64, "reviews": 3, "sales": 11 }, "signals": { "stars": 37, "downloads": 64, "tests_pass_rate": 0.91, "days_since_update": 4 }, "rating": 4.3, "rating_count": 3, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-09-12T08:00:00Z", "updated_at": "2026-10-30T16:40:12Z" }, "item_mcp": { "id": "itm_stripemcp222", "object": "item", "owner": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "slug": "stripe-checkout-mcp", "full_name": "acme/stripe-checkout-mcp", "kind": "mcp_server", "title": "Stripe checkout MCP", "summary": "MCP server that creates Stripe Checkout sessions and reads payment status for an agent.", "visibility": "public", "status": "active", "license": "Apache-2.0", "pricing_model": "free", "price_cents": 0, "currency": "USD", "source": { "provider": "github", "url": "https://github.com/acme/stripe-checkout-mcp", "ref": "acme/stripe-checkout-mcp" }, "homepage_url": "", "html_url": "https://reuseforge.com/app/acme/stripe-checkout-mcp", "capabilities": [ "payments", "backend-api" ], "tags": [ "stripe", "checkout", "mcp" ], "latest_version": "2.1.0", "verification": null, "stats": { "stars": 96, "downloads": 1204, "reviews": 5, "sales": 0 }, "signals": { "stars": 96, "downloads": 1204, "forks": 11, "open_issues": 3, "days_since_update": 21 }, "rating": 4.8, "rating_count": 5, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-06-20T10:30:00Z", "updated_at": "2026-10-13T12:00:00Z" }, "version_invoice": { "id": "ver_xinvoice2345", "object": "item_version", "item": "acme/invoice-extractor", "item_id": "itm_invoiceextr2", "version": "1.4.0", "changelog": "Adds multi-currency totals and a --strict mode.", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "size_bytes": 48213, "file_count": 3, "dependencies": [ { "item": "acme/pdf-text-layer", "range": "^2.0.0" } ], "yanked": false, "yanked_reason": null, "prerelease": false, "archive_sha256": "a3c0f5bd09a1d7b4e2f8c61d9b7e45a0c1f3d2e8b6a49f7c05d1e3b28a6c4f90", "manifest": null, "created_by": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "created_at": "2026-10-28T09:10:02Z" }, "files_invoice": [ { "path": "SKILL.md", "size_bytes": 2210, "sha256": "0d513c7b5ef7777ab855c1d1608db8916080485038901daa59524757549540a2", "content_type": "text/markdown", "preview": true }, { "path": "src/extract.py", "size_bytes": 41876, "sha256": "75737d9d063bc4d4ac1613bc16d49e275727cf548a7e6eb029ac6087d22a24c6", "content_type": "text/x-python", "preview": false }, { "path": "README.md", "size_bytes": 4127, "sha256": "42c59af8a4bae559bc5a5d5d3f06f02ee30e2afcd9f2d0c39b38ccee6d0fa9b8", "content_type": "text/markdown", "preview": true } ], "verification_invoice": { "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" }, "review_sam": { "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" }, "cand_invoice": { "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": [] }, "cand_harness": { "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" ] }, "cand_github": { "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": [] }, "cand_paper": { "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": [] }, "plan_step_use": { "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": [] }, "plan_step_harness": { "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": [] }, "plan_step_build": { "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_item_harness": { "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 }, "plan_option_a": { "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 } ] }, "plan_option_b": { "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": [] }, "plan_main": { "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 }, "payment_awaiting": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "awaiting_payment", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000", "tx_ref": null, "confirmations": 0, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "payment_confirmed": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "oi_pending": { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null }, "oi_delivered": { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "delivered", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": null }, "oi_released": { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "released", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": "accepted" }, "oi_disputed": { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "disputed", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": { "reason": "The harness crashes on startup with the documented config (KeyError: embedder).", "opened_at": "2026-11-03T10:40:00Z" }, "resolution": null, "release_reason": null }, "oi_refunded": { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "refunded", "price_cents": 1200, "fee_cents": 0, "seller_amount_cents": 0, "project_id": null, "delivery": null, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": null, "dispute": null, "resolution": { "seller_bps": 0, "refund_cents": 1200, "note": "Seller did not deliver before the deadline.", "resolved_at": "2026-11-10T10:09:00Z" }, "release_reason": null }, "payout_seller": { "id": "pyo_sellerpay222", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "seller", "recipient": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "address": "0xA11cE0000000000000000000000000000000b0b2", "rail": "base-usdc", "amount_cents": 1188, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null }, "payout_fee": { "id": "pyo_platformfee2", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "platform_fee", "recipient": null, "address": "0xFee0000000000000000000000000000000000001", "rail": "base-usdc", "amount_cents": 12, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null }, "order_awaiting": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "awaiting_payment", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "awaiting_payment", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000", "tx_ref": null, "confirmations": 0, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": null, "settled_at": null, "payouts": [], "next_actions": [ { "type": "send_payment", "description": "Transfer 12.00 USDC on Base Sepolia to the escrow contract, then call pay_order with the transaction hash.", "chain_id": 84532, "to": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "data": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000" } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:05:00Z" }, "order_funded": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:07:12Z" }, "order_delivered": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "delivered", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [ { "type": "review_delivery", "description": "Test the delivered item, then call accept_order to release payment or dispute_order before 2026-11-10T10:08:30Z." } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:08:30Z" }, "order_settled": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "released", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": "accepted" } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-03T11:20:45Z", "payouts": [ { "id": "pyo_sellerpay222", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "seller", "recipient": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "address": "0xA11cE0000000000000000000000000000000b0b2", "rail": "base-usdc", "amount_cents": 1188, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null }, { "id": "pyo_platformfee2", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "platform_fee", "recipient": null, "address": "0xFee0000000000000000000000000000000000001", "rail": "base-usdc", "amount_cents": 12, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T11:21:10Z" }, "order_disputed": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "disputed", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": { "reason": "The harness crashes on startup with the documented config (KeyError: embedder).", "opened_at": "2026-11-03T10:40:00Z" }, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:40:00Z" }, "order_refunded": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "refunded", "price_cents": 1200, "fee_cents": 0, "seller_amount_cents": 0, "project_id": null, "delivery": null, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": null, "dispute": null, "resolution": { "seller_bps": 0, "refund_cents": 1200, "note": "Seller did not deliver before the deadline.", "resolved_at": "2026-11-10T10:09:00Z" }, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 0, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-10T10:09:00Z", "payouts": [ { "id": "pyo_buyerrefun22", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "refund", "recipient": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "rail": "base-usdc", "amount_cents": 1200, "currency": "USD", "state": "sent", "tx_ref": "0x4c1d9e7b2a6f08d35e9a1b7c4d2e6f80a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2", "sent_at": "2026-11-10T10:10:30Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-10T10:10:30Z" }, "milestone_approved": { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, "milestone_submitted": { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, "milestone_pending": { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } }, "project_funded": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null }, "project_open": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "open", "goal_cents": 500000, "raised_cents": 0, "pending_cents": 0, "progress": 0.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": null, "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 0 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 0 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 0 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null }, "backing_sam": { "id": "bck_samreconpldg", "object": "backing", "project_id": "prj_reconharnes2", "backer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "amount_cents": 300000, "currency": "USD", "state": "confirmed", "units": 480000000000, "payment": { "rail": "simulated", "network": null, "asset": "USD", "status": "confirmed", "amount_cents": 300000, "amount_atomic": "300000", "address": "escrow:rb-hosted", "memo": "bck_samreconpldg", "uri": null, "tx_ref": "sim_tx_5d1f08a9c3e2", "confirmations": 1, "required_confirmations": 1, "expires_at": null, "refund_address": null, "simulated": true }, "created_at": "2026-10-12T17:20:00Z" }, "token_agent": { "id": "tok_agentreader2", "object": "token", "name": "ci-agent", "prefix": "rf_k3Tz9q", "scopes": [ "items:read", "items:publish", "orders:create", "orders:pay" ], "spend_limit_cents": 5000, "spent_cents": 1200, "created_at": "2026-10-20T09:00:00Z", "last_used_at": "2026-11-03T10:07:00Z", "expires_at": "2027-01-18T09:00:00Z" }, "webhook_main": { "id": "whk_ordersandpub", "object": "webhook", "url": "https://hooks.acme.example/reuseforge", "description": "Production order and publish events", "events": [ "item.published", "item.version.published", "order.created", "order.funded", "order.released" ], "account": "acme", "status": "enabled", "disabled_reason": null, "api_version": "1", "consecutive_failures": 0, "last_delivery_at": "2026-11-03T10:08:31Z", "last_success_at": "2026-11-03T10:08:31Z", "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-10-01T12:00:00Z" }, "delivery_ok": { "id": "whd_deliveryok22", "object": "webhook_delivery", "webhook_id": "whk_ordersandpub", "event_id": "evt_orderfunded2", "event_type": "order.funded", "attempt": 1, "state": "succeeded", "scheduled_at": "2026-11-03T10:07:12Z", "delivered_at": "2026-11-03T10:07:13Z", "response_status": 200, "response_ms": 184, "response_excerpt": "ok", "error": null, "next_attempt_at": null }, "ledger_event": { "id": "3c6e1f0b9a7d42885e1c0a9f3b2d4e6a8c0b1d3f5a7c9e2b4d6f8a0c1e3b5d79", "body": { "kind": "block.publish", "author": "rb1Qm3pX0vN8cT2yJ4kL6hD9sA1fG5wE7uB3iZ0oR2tY", "data": { "name": "Invoice extractor", "kind": "skill", "summary": "Extracts vendor totals and line items from PDF invoices.", "url": "https://github.com/acme/invoice-extractor", "capabilities": [ "document-parsing" ], "license": "MIT", "price_usd": 0, "version": "1.4.0" }, "lamport": 1042, "parents": [ "8a1d0c7e5b3f9a2d4c6e8b0a1d3f5c7e9b2a4d6f8c0e1a3b5d7f9c2e4a6b8d01" ], "ts": 1793700000 }, "sig": "4Z8mQeV1xJr0Sk9TnC3bHdW5yLfA7uPoGi2EtRaN6vXcM1sKjDq8YhBlOw0UzFg3ItPe5CnSvHrA9dJk2LmQxT4bWy7NuE1ZoGf6RiCa" }, "rate_limit_read": { "tier": "read", "limit": 600, "remaining": 597, "reset_seconds": 41, "window_seconds": 60, "policy": "600;w=60" }, "payment_pending": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "pending_confirmations", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 1, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "order_pending": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "awaiting_payment", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "pending_confirmations", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 1, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": null, "settled_at": null, "payouts": [], "next_actions": [ { "type": "wait", "description": "Payment seen with 1 of 3 confirmations. Poll get_order or wait for the order.funded webhook." } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:06:20Z" }, "order_cancelled": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "cancelled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "awaiting_payment", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000", "tx_ref": null, "confirmations": 0, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": null, "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:09:00Z" } }, "paths": { "/": { "get": { "operationId": "get_api_index", "tags": [ "meta" ], "summary": "API index", "description": "Entry point with links to every top-level collection, the enabled payment rails, current limits and any announced deprecations. Safe to call without credentials.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "api index", "responses": { "200": { "description": "The index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" }, "examples": { "default": { "value": { "name": "ReuseForge API", "api_version": "1.1.0", "major": "v1", "documentation_url": "https://reuseforge.com/docs/api", "openapi_url": "https://reuseforge.com/api/v1/openapi.json", "links": { "items": "/api/v1/items", "plans": "/api/v1/plans", "orders": "/api/v1/orders", "projects": "/api/v1/projects", "webhooks": "/api/v1/webhooks", "tokens": "/api/v1/tokens", "ledger": "/api/v1/ledger/events", "mcp": "https://reuseforge.com/mcp" }, "auth": { "type": "bearer", "token_prefix": "rf_", "scope_catalog_url": "https://reuseforge.com/docs/api#scopes" }, "test_mode": true, "rails": [ { "id": "simulated", "network": null, "enabled": true, "test_mode": true }, { "id": "base-usdc", "network": "base-sepolia", "enabled": true, "test_mode": true }, { "id": "base-usdt", "network": "base-sepolia", "enabled": false, "test_mode": true }, { "id": "btc", "network": "testnet4", "enabled": false, "test_mode": true } ], "limits": { "page_max": 100, "max_files": 100, "max_file_bytes": 524288, "max_version_bytes": 2097152, "max_request_bytes": 3145728, "goal_max_chars": 4000, "plan_ttl_seconds": 86400, "idempotency_ttl_seconds": 86400, "webhook_endpoints_max": 20, "tokens_max": 50 }, "deprecations": [] } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/health": { "get": { "operationId": "get_health", "tags": [ "meta" ], "summary": "Health check", "description": "Cheap liveness and dependency check for monitors. Returns 200 when the API can serve requests and 503 when it cannot reach its database.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "api health", "responses": { "200": { "description": "Healthy or degraded (degraded still serves).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "examples": { "default": { "value": { "status": "ok", "time": "2026-11-03T10:00:00Z", "version": "1.1.0", "components": { "database": "ok", "cache": "ok", "connectors": "ok" } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/openapi.{format}": { "get": { "operationId": "get_openapi_document", "tags": [ "meta" ], "summary": "This contract", "description": "The OpenAPI 3.1 document served by this deployment, as JSON or YAML. Cacheable; honours `If-None-Match`.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "api openapi", "parameters": [ { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "json", "yaml" ] } }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The OpenAPI document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" }, "examples": { "default": { "value": { "openapi": "3.1.0", "info": { "title": "ReuseForge API", "version": "1.1.0" }, "paths": {} } } } }, "application/yaml": { "schema": { "type": "string" }, "examples": { "default": { "value": "openapi: 3.1.0\ninfo:\n title: ReuseForge API\n version: 1.1.0\n" } } } } }, "304": { "description": "Not modified." }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/event-types": { "get": { "operationId": "list_event_types", "tags": [ "meta" ], "summary": "Webhook event catalogue", "description": "Every event type that can be delivered to webhooks, with the resource carried in `data.object`.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "list_event_types", "title": "List event types", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "events types", "responses": { "200": { "description": "The catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypePage" }, "examples": { "default": { "value": { "data": [ { "type": "item.published", "description": "A new item became publicly available.", "object": "item" }, { "type": "item.version.published", "description": "A new version of an item was published.", "object": "item_version" }, { "type": "order.funded", "description": "Escrow for an order was confirmed funded.", "object": "order" }, { "type": "payout.sent", "description": "A payout to a seller, platform fee or refund was sent.", "object": "payout" } ], "next_cursor": null, "has_more": false } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rate-limit": { "get": { "operationId": "get_rate_limits", "tags": [ "meta" ], "summary": "Rate limit status", "description": "Your current allowance in every tier. Does not itself consume allowance.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_rate_limits", "title": "Get rate limits", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "api rate-limit", "responses": { "200": { "description": "Allowance per tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitStatus" }, "examples": { "default": { "value": { "principal": "token", "tiers": [ { "tier": "read", "limit": 600, "remaining": 597, "reset_seconds": 41, "window_seconds": 60, "policy": "600;w=60" }, { "tier": "write", "limit": 120, "remaining": 120, "reset_seconds": 60, "window_seconds": 60, "policy": "120;w=60" }, { "tier": "plan", "limit": 20, "remaining": 19, "reset_seconds": 33, "window_seconds": 60, "policy": "20;w=60" }, { "tier": "discover", "limit": 10, "remaining": 10, "reset_seconds": 60, "window_seconds": 60, "policy": "10;w=60" }, { "tier": "payments", "limit": 30, "remaining": 30, "reset_seconds": 60, "window_seconds": 60, "policy": "30;w=60" } ] } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/me": { "get": { "operationId": "get_me", "tags": [ "identity" ], "summary": "Who am I", "description": "The authenticated account, the credential used (scopes, spend limit) and the organizations you can act for.", "security": [ { "bearerAuth": [] } ], "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_me", "title": "Who am I", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "whoami", "responses": { "200": { "description": "The principal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "examples": { "default": { "value": { "id": "acc_samdevuser22", "object": "account", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "avatar_url": "", "email": "sam@example.com", "email_verified": true, "role": "user", "created_at": "2026-08-14T07:30:00Z", "auth": { "via": "token", "scopes": [ "items:read", "items:publish", "orders:create", "orders:pay" ], "token_id": "tok_agentreader2", "spend_limit_cents": 5000, "spent_cents": 1200 }, "orgs": [ { "account": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "role": "write" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accounts/{handle}": { "get": { "operationId": "get_account", "tags": [ "identity" ], "summary": "Get a public profile", "description": "Public profile of a user or organization.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_account", "title": "Get account", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "accounts get", "parameters": [ { "$ref": "#/components/parameters/Handle" } ], "responses": { "200": { "description": "The profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "examples": { "default": { "value": { "id": "acc_acmelabsorg2", "object": "account", "type": "org", "handle": "acme", "display_name": "Acme Labs", "bio": "Document automation building blocks for agents.", "avatar_url": "", "website": "https://acme.example", "location": "Berlin", "links": { "github": "acme", "huggingface": "acme-labs" }, "verified": true, "followers_count": 318, "following_count": 4, "stats": { "items": 14, "stars_received": 2210 }, "created_at": "2026-01-11T09:00:00Z" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tokens": { "get": { "operationId": "list_tokens", "tags": [ "tokens" ], "summary": "List API tokens", "description": "Active tokens of the authenticated account. Secrets are never returned after creation.", "security": [ { "bearerAuth": [ "tokens:manage" ] } ], "x-scopes": [ "tokens:manage" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "tokens list", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPage" }, "examples": { "default": { "value": { "data": [ { "id": "tok_agentreader2", "object": "token", "name": "ci-agent", "prefix": "rf_k3Tz9q", "scopes": [ "items:read", "items:publish", "orders:create", "orders:pay" ], "spend_limit_cents": 5000, "spent_cents": 1200, "created_at": "2026-10-20T09:00:00Z", "last_used_at": "2026-11-03T10:07:00Z", "expires_at": "2027-01-18T09:00:00Z" } ], "next_cursor": null, "has_more": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "create_token", "tags": [ "tokens" ], "summary": "Create an API token", "description": "Mints a personal access token. The secret (`token`) is returned once.\n\nSafety rules: a token can only mint tokens whose scopes are a subset of its own and whose spend limit is not larger.\n`orders:accept` (release escrow) is never included unless listed explicitly, and an unlimited spend limit\n(`spend_limit_cents: null`) is only honoured for an interactive session. When `orders:pay` is requested and\nthe limit is omitted, the default is 5000 cents.\n", "security": [ { "bearerAuth": [ "tokens:manage" ] } ], "x-scopes": [ "tokens:manage" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": false, "x-cli": "tokens create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreate" }, "examples": { "agent": { "summary": "A budget-limited agent token that cannot release escrow", "value": { "name": "ci-agent", "scopes": [ "items:read", "items:publish", "orders:create", "orders:pay" ], "expires_in_days": 90, "spend_limit_cents": 5000 } } } } } }, "responses": { "201": { "description": "The token, including its one-time secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenWithSecret" }, "examples": { "default": { "value": { "id": "tok_agentreader2", "object": "token", "name": "ci-agent", "prefix": "rf_k3Tz9q", "scopes": [ "items:read", "items:publish", "orders:create", "orders:pay" ], "spend_limit_cents": 5000, "spent_cents": 0, "created_at": "2026-10-20T09:00:00Z", "last_used_at": null, "expires_at": "2027-01-18T09:00:00Z", "token": "rf_k3Tz9qXw1LmN8vB4cD7eF2gH5jK6pR0sTuV3yZaQb" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tokens/{token_id}": { "delete": { "operationId": "revoke_token", "tags": [ "tokens" ], "summary": "Revoke an API token", "description": "Revokes immediately. Idempotent: revoking an already revoked token returns 204.", "security": [ { "bearerAuth": [ "tokens:manage" ] } ], "x-scopes": [ "tokens:manage" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": false, "x-cli": "tokens revoke", "parameters": [ { "$ref": "#/components/parameters/TokenId" } ], "responses": { "204": { "description": "Revoked." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items": { "get": { "operationId": "search_items", "tags": [ "items" ], "summary": "Search and list items", "description": "Full-text search (when `q` is given) and filtered listing of public, active items. Signed-in callers also see\ntheir own private and unlisted items when `owner` names themselves or an organization they belong to.\nDefault sort is `relevance` with `q` and `trending` without.\n", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "search_items", "title": "Search items", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "items search", "parameters": [ { "name": "q", "in": "query", "description": "Search text. Matches title, summary, tags, capabilities and owner.", "schema": { "type": "string", "maxLength": 200 }, "example": "invoice pdf extraction" }, { "name": "kind", "in": "query", "description": "Restrict to these kinds (comma separated).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ItemKind" }, "maxItems": 8 } }, { "name": "capability", "in": "query", "description": "Capability ids from the planner taxonomy (comma separated, all must match).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 8 } }, { "name": "tag", "in": "query", "schema": { "type": "string", "maxLength": 64 } }, { "name": "license", "in": "query", "description": "SPDX identifier (comma separated for any-of).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 10 } }, { "name": "max_price_cents", "in": "query", "description": "Only items priced at or below this many cents.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000 } }, { "name": "free_only", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "verified", "in": "query", "description": "When true, only items whose latest version has a passing verification.", "schema": { "type": "boolean" } }, { "name": "min_rating", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 5 } }, { "name": "owner", "in": "query", "description": "Owner handle (user or organization).", "schema": { "type": "string", "maxLength": 39 } }, { "name": "sort", "in": "query", "schema": { "$ref": "#/components/schemas/ItemSort" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of items. `readme` and `viewer` are omitted in lists.", "headers": { "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPage" }, "examples": { "default": { "value": { "data": [ { "id": "itm_invoiceextr2", "object": "item", "owner": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "slug": "invoice-extractor", "full_name": "acme/invoice-extractor", "kind": "skill", "title": "Invoice extractor", "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.", "visibility": "public", "status": "active", "license": "MIT", "pricing_model": "free", "price_cents": 0, "currency": "USD", "source": { "provider": "github", "url": "https://github.com/acme/invoice-extractor", "ref": "acme/invoice-extractor" }, "homepage_url": "https://acme.example/invoice-extractor", "html_url": "https://reuseforge.com/app/acme/invoice-extractor", "capabilities": [ "document-parsing", "data-analysis" ], "tags": [ "pdf", "invoices", "ocr" ], "latest_version": "1.4.0", "verification": { "state": "passed", "version": "1.4.0", "tests_pass_rate": 0.97, "verified_at": "2026-10-28T09:12:40Z" }, "stats": { "stars": 412, "downloads": 9120, "reviews": 18, "sales": 0 }, "signals": { "stars": 1860, "downloads": 9120, "tests_pass_rate": 0.97, "forks": 143, "open_issues": 12, "days_since_update": 6 }, "rating": 4.6, "rating_count": 18, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-03-02T14:05:11Z", "updated_at": "2026-10-28T09:10:02Z" }, { "id": "itm_ragharness22", "object": "item", "owner": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "slug": "invoice-rag-harness", "full_name": "janedoe/invoice-rag-harness", "kind": "harness", "title": "Invoice RAG harness", "summary": "Agent harness that indexes invoices, answers spend questions with citations and exports a dashboard.", "visibility": "public", "status": "active", "license": "Commercial-Single-Project", "pricing_model": "fixed", "price_cents": 1200, "currency": "USD", "source": { "provider": "manual", "url": "", "ref": "" }, "homepage_url": "", "html_url": "https://reuseforge.com/app/janedoe/invoice-rag-harness", "capabilities": [ "retrieval-rag", "llm-chat", "data-analysis" ], "tags": [ "rag", "invoices", "dashboard" ], "latest_version": "0.9.2", "verification": { "state": "passed", "version": "0.9.2", "tests_pass_rate": 0.91, "verified_at": "2026-10-30T16:41:05Z" }, "stats": { "stars": 37, "downloads": 64, "reviews": 3, "sales": 11 }, "signals": { "stars": 37, "downloads": 64, "tests_pass_rate": 0.91, "days_since_update": 4 }, "rating": 4.3, "rating_count": 3, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-09-12T08:00:00Z", "updated_at": "2026-10-30T16:40:12Z" } ], "next_cursor": "eyJvIjoyLCJzIjoicmVsZXZhbmNlIn0", "has_more": true, "total": 37 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "create_item", "tags": [ "items" ], "summary": "Create an item", "description": "Creates an item (metadata only). Publish content with `publish_version`. New items are `draft` until their first\nversion is published unless the item only points at an external `source`. Paid items require a verified email\nand a payout address. `owner` defaults to you; set it to an organization handle you have `write` role on.\n", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "create_item", "title": "Create item", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }, "x-cli": "items create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreate" }, "examples": { "free_skill": { "summary": "A free skill published for an organization", "value": { "owner": "acme", "slug": "pdf-text-layer", "kind": "skill", "title": "PDF text layer", "summary": "Recovers a reading-order text layer from scanned PDFs.", "readme": "# PDF text layer\n\nRecovers reading order from scans.", "license": "MIT", "pricing_model": "free", "price_cents": 0, "capabilities": [ "document-parsing" ], "tags": [ "pdf", "ocr" ], "source": { "provider": "github", "url": "https://github.com/acme/pdf-text-layer", "ref": "acme/pdf-text-layer" } } } } } } }, "responses": { "201": { "description": "The created item.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" }, "examples": { "default": { "value": { "id": "itm_pdftextlayer", "object": "item", "owner": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "slug": "pdf-text-layer", "full_name": "acme/pdf-text-layer", "kind": "skill", "title": "PDF text layer", "summary": "Recovers a reading-order text layer from scanned PDFs.", "readme": "# PDF text layer\n\nRecovers reading order from scans.", "visibility": "public", "status": "draft", "license": "MIT", "pricing_model": "free", "price_cents": 0, "currency": "USD", "source": { "provider": "github", "url": "https://github.com/acme/pdf-text-layer", "ref": "acme/pdf-text-layer" }, "homepage_url": "", "html_url": "https://reuseforge.com/app/acme/pdf-text-layer", "capabilities": [ "document-parsing" ], "tags": [ "pdf", "ocr" ], "latest_version": null, "verification": null, "stats": { "stars": 0, "downloads": 0, "reviews": 0, "sales": 0 }, "signals": {}, "rating": null, "rating_count": 0, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-11-03T10:20:00Z", "updated_at": "2026-11-03T10:20:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "get_item", "tags": [ "items" ], "summary": "Get an item", "description": "Returns the item with its README and, when signed in, your `viewer` state. Supports `ETag` / `If-None-Match`. A retracted item that had been publicly listed returns 410 to everyone except its owners; an item that was never listed (draft, archived or private when it was retracted) stays 404, so a retraction reveals nothing about it.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_item", "title": "Get item", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "items get", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" }, "examples": { "default": { "value": { "id": "itm_ragharness22", "object": "item", "owner": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "slug": "invoice-rag-harness", "full_name": "janedoe/invoice-rag-harness", "kind": "harness", "title": "Invoice RAG harness", "summary": "Agent harness that indexes invoices, answers spend questions with citations and exports a dashboard.", "readme": "# Invoice RAG harness\n\nIndex a folder of invoices and ask questions.\n\n## Quick start\n\n rf install janedoe/invoice-rag-harness\n", "visibility": "public", "status": "active", "license": "Commercial-Single-Project", "pricing_model": "fixed", "price_cents": 1200, "currency": "USD", "source": { "provider": "manual", "url": "", "ref": "" }, "homepage_url": "", "html_url": "https://reuseforge.com/app/janedoe/invoice-rag-harness", "capabilities": [ "retrieval-rag", "llm-chat", "data-analysis" ], "tags": [ "rag", "invoices", "dashboard" ], "latest_version": "0.9.2", "verification": { "state": "passed", "version": "0.9.2", "tests_pass_rate": 0.91, "verified_at": "2026-10-30T16:41:05Z" }, "stats": { "stars": 37, "downloads": 64, "reviews": 3, "sales": 11 }, "signals": { "stars": 37, "downloads": 64, "tests_pass_rate": 0.91, "days_since_update": 4 }, "rating": 4.3, "rating_count": 3, "demo": false, "forked_from": null, "project_id": null, "viewer": { "starred": false, "can_edit": false, "entitled": false }, "created_at": "2026-09-12T08:00:00Z", "updated_at": "2026-10-30T16:40:12Z" } } } } } }, "304": { "description": "Not modified. The `If-None-Match` ETag is still current." }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "update_item", "tags": [ "items" ], "summary": "Update an item", "description": "JSON Merge Patch style update of mutable metadata: omitted fields are unchanged, present fields replace the stored\nvalue (arrays and `source` members are replaced, not merged). `null` is not accepted; send an empty string (or an empty\narray for `tags` and `capabilities`) to clear a field. `slug`, `kind` and `owner` cannot change. `If-Match` is required\nand takes the ETag of a `get_item` or earlier `update_item` response: it holds as long as nothing you can edit changed\nsince, even when counters (stars, downloads, reviews) moved; otherwise 412 with `current_etag`. A retracted item\nreturns 409 `invalid_state`. Price changes never affect orders that already exist.\n", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": { "tool": "update_item", "title": "Update item", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "items update", "parameters": [ { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/ItemUpdate" }, "examples": { "homepage": { "value": { "homepage_url": "https://acme.example/invoice-extractor" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ItemUpdate" }, "examples": { "homepage": { "value": { "homepage_url": "https://acme.example/invoice-extractor" } } } } } }, "responses": { "200": { "description": "The updated item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" }, "examples": { "default": { "value": { "id": "itm_invoiceextr2", "object": "item", "owner": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "slug": "invoice-extractor", "full_name": "acme/invoice-extractor", "kind": "skill", "title": "Invoice extractor", "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.", "visibility": "public", "status": "active", "license": "MIT", "pricing_model": "free", "price_cents": 0, "currency": "USD", "source": { "provider": "github", "url": "https://github.com/acme/invoice-extractor", "ref": "acme/invoice-extractor" }, "homepage_url": "https://acme.example/invoice-extractor", "html_url": "https://reuseforge.com/app/acme/invoice-extractor", "capabilities": [ "document-parsing", "data-analysis" ], "tags": [ "pdf", "invoices", "ocr" ], "latest_version": "1.4.0", "verification": { "state": "passed", "version": "1.4.0", "tests_pass_rate": 0.97, "verified_at": "2026-10-28T09:12:40Z" }, "stats": { "stars": 412, "downloads": 9120, "reviews": 18, "sales": 0 }, "signals": { "stars": 1860, "downloads": 9120, "tests_pass_rate": 0.97, "forks": 143, "open_issues": 12, "days_since_update": 6 }, "rating": 4.6, "rating_count": 18, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-03-02T14:05:11Z", "updated_at": "2026-10-28T09:10:02Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "retract_item", "tags": [ "items" ], "summary": "Retract an item", "description": "Removes the item from search and sets `status` to `retracted`. Versions already bought stay downloadable by their buyers. Fires `item.retracted`. Idempotent.", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": { "tool": "retract_item", "title": "Retract item", "readOnly": false, "destructive": true, "idempotent": true, "openWorld": false }, "x-cli": "items retract", "responses": { "204": { "description": "Retracted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/star": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" } ], "put": { "operationId": "star_item", "tags": [ "items" ], "summary": "Star an item", "description": "Idempotent. Starring twice leaves one star.", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": { "tool": "star_item", "title": "Star item", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "items star", "responses": { "200": { "description": "The new state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarState" }, "examples": { "default": { "value": { "item": "acme/invoice-extractor", "starred": true, "stars_count": 413 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "unstar_item", "tags": [ "items" ], "summary": "Remove your star", "description": "Idempotent.", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": { "tool": "unstar_item", "title": "Unstar item", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "items unstar", "responses": { "200": { "description": "The new state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarState" }, "examples": { "default": { "value": { "item": "acme/invoice-extractor", "starred": false, "stars_count": 412 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/reviews": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "list_reviews", "tags": [ "reviews" ], "summary": "List reviews", "description": "Reviews of an item, newest first by default. Reviews a moderator removed and reviews by suspended accounts are not listed or counted (`total`).", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "list_reviews", "title": "List reviews", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "reviews list", "parameters": [ { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "highest", "lowest" ], "default": "newest" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of reviews.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewPage" }, "examples": { "default": { "value": { "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 } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "create_review", "tags": [ "reviews" ], "summary": "Review an item", "description": "One review per account per item, from a verified buyer only. Paid items require a released order that contains\nthe item (`basis: purchase`). Free items require that your account has fetched the install descriptor or bundle\n(`basis: install`). Owners cannot review their own items. Remove yours with `delete_review` to write a new one. If a moderator\nremoved your review, you cannot post a new one: **403 `review_removed`**.\n", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "create_review", "title": "Review item", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }, "x-cli": "reviews create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCreate" }, "examples": { "default": { "value": { "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." } } } } } }, "responses": { "201": { "description": "The review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" }, "examples": { "default": { "value": { "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" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/reviews/mine": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" } ], "delete": { "operationId": "delete_review", "tags": [ "reviews" ], "summary": "Delete your review", "description": "Idempotent. A review a moderator removed cannot be deleted by its author (it stays as a tombstone); that answers 403 `review_removed`.", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": { "tool": "delete_review", "title": "Delete my review", "readOnly": false, "destructive": true, "idempotent": true, "openWorld": false }, "x-cli": "reviews delete", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/stats": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "get_item_stats", "tags": [ "items" ], "summary": "Item statistics", "description": "Public totals for anyone. Owners and organization members additionally receive the daily series; `revenue_cents` is added for owners and organization admins when the payments ledger reports a figure.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_item_stats", "title": "Get item stats", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "items stats", "parameters": [ { "name": "days", "in": "query", "description": "Length of the daily series for owners.", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemStats" }, "examples": { "default": { "value": { "item": "janedoe/invoice-rag-harness", "totals": { "views": 5410, "downloads": 64, "stars": 37, "reviews": 3, "sales": 11, "revenue_cents": 13068 }, "days": [ { "day": "2026-11-01", "views": 188, "downloads": 3, "stars": 1 }, { "day": "2026-11-02", "views": 203, "downloads": 2, "stars": 0 } ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/install": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "get_install_descriptor", "tags": [ "versions" ], "summary": "Install descriptor", "description": "A machine-readable recipe for installing a version into a specific agent environment: files to write, config to\nmerge, commands to show, and the `reuseforge.lock` entry. Free items work anonymously. Paid items return **402\n`payment_required`** with an `order_hint` until your account is entitled (an order for the item is delivered,\ndisputed or released and not refunded). A quarantined version answers **403 `version_quarantined`** (see `get_version_bundle`).\nThe descriptor itself contains no file contents: fetch them with `get_version_bundle`. Fetching it while signed in records an install, which makes you eligible to review free items.\n", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_install_descriptor", "title": "Get install descriptor", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "items descriptor", "parameters": [ { "name": "target", "in": "query", "description": "Where the item will be installed.", "schema": { "$ref": "#/components/schemas/InstallTarget" } }, { "name": "version", "in": "query", "description": "Exact version or `latest` (default).", "schema": { "type": "string", "default": "latest", "maxLength": 64 } } ], "responses": { "200": { "description": "The descriptor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallDescriptor" }, "examples": { "claude_code_skill": { "summary": "A free skill for Claude Code", "value": { "object": "install_descriptor", "item": "acme/invoice-extractor", "item_id": "itm_invoiceextr2", "kind": "skill", "version": "1.4.0", "target": "claude-code", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "license": "MIT", "price_cents": 0, "currency": "USD", "entitlement": { "required": false, "granted": true, "reason": "free", "order_id": null }, "bundle_url": "https://reuseforge.com/api/v1/items/acme/invoice-extractor/versions/1.4.0/bundle", "files": [ { "path": ".claude/skills/invoice-extractor/SKILL.md", "source_path": "SKILL.md", "sha256": "0d513c7b5ef7777ab855c1d1608db8916080485038901daa59524757549540a2", "size_bytes": 2210, "mode": "0644" }, { "path": ".claude/skills/invoice-extractor/src/extract.py", "source_path": "src/extract.py", "sha256": "75737d9d063bc4d4ac1613bc16d49e275727cf548a7e6eb029ac6087d22a24c6", "size_bytes": 41876, "mode": "0644" }, { "path": ".claude/skills/invoice-extractor/README.md", "source_path": "README.md", "sha256": "42c59af8a4bae559bc5a5d5d3f06f02ee30e2afcd9f2d0c39b38ccee6d0fa9b8", "size_bytes": 4127, "mode": "0644" } ], "config_patches": [], "commands": [], "lock_entry": { "name": "acme/invoice-extractor", "id": "itm_invoiceextr2", "version": "1.4.0", "kind": "skill", "target": "claude-code", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "license": "MIT", "source": "reuseforge", "order_id": null, "price_paid_cents": 0, "files": [ { "path": ".claude/skills/invoice-extractor/SKILL.md", "sha256": "0d513c7b5ef7777ab855c1d1608db8916080485038901daa59524757549540a2" }, { "path": ".claude/skills/invoice-extractor/src/extract.py", "sha256": "75737d9d063bc4d4ac1613bc16d49e275727cf548a7e6eb029ac6087d22a24c6" }, { "path": ".claude/skills/invoice-extractor/README.md", "sha256": "42c59af8a4bae559bc5a5d5d3f06f02ee30e2afcd9f2d0c39b38ccee6d0fa9b8" } ] }, "notes": [ "Restart Claude Code to load the skill." ], "warnings": [] } }, "mcp_json_server": { "summary": "An MCP server for a project-level .mcp.json", "value": { "object": "install_descriptor", "item": "acme/stripe-checkout-mcp", "item_id": "itm_stripemcp222", "kind": "mcp_server", "version": "2.1.0", "target": "mcp-json", "content_hash": "sha256:6f428a3cadf44480f268461731b1e1705dc6938ef91ca5aedf160d0040d3e90b", "license": "Apache-2.0", "price_cents": 0, "currency": "USD", "entitlement": { "required": false, "granted": true, "reason": "free", "order_id": null }, "bundle_url": "https://reuseforge.com/api/v1/items/acme/stripe-checkout-mcp/versions/2.1.0/bundle", "files": [], "config_patches": [ { "path": ".mcp.json", "format": "json", "merge": { "mcpServers": { "stripe-checkout": { "command": "npx", "args": [ "-y", "@acme/stripe-checkout-mcp@2.1.0" ], "env": { "STRIPE_API_KEY": "${STRIPE_API_KEY}" } } } } } ], "commands": [], "lock_entry": { "name": "acme/stripe-checkout-mcp", "id": "itm_stripemcp222", "version": "2.1.0", "kind": "mcp_server", "target": "mcp-json", "content_hash": "sha256:6f428a3cadf44480f268461731b1e1705dc6938ef91ca5aedf160d0040d3e90b", "license": "Apache-2.0", "source": "reuseforge", "order_id": null, "price_paid_cents": 0, "files": [] }, "notes": [ "Set STRIPE_API_KEY in your environment. The CLI never writes secrets into .mcp.json." ], "warnings": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/versions": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "list_versions", "tags": [ "versions" ], "summary": "List versions", "description": "Published versions, newest (by semantic version) first, including yanked ones (flagged).", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "list_versions", "title": "List versions", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "versions list", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of versions without file lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemVersionPage" }, "examples": { "default": { "value": { "data": [ { "id": "ver_xinvoice2345", "object": "item_version", "item": "acme/invoice-extractor", "item_id": "itm_invoiceextr2", "version": "1.4.0", "changelog": "Adds multi-currency totals and a --strict mode.", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "size_bytes": 48213, "file_count": 3, "dependencies": [ { "item": "acme/pdf-text-layer", "range": "^2.0.0" } ], "yanked": false, "yanked_reason": null, "prerelease": false, "archive_sha256": "a3c0f5bd09a1d7b4e2f8c61d9b7e45a0c1f3d2e8b6a49f7c05d1e3b28a6c4f90", "manifest": null, "created_by": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "created_at": "2026-10-28T09:10:02Z" } ], "next_cursor": null, "has_more": false } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "publish_version", "tags": [ "versions" ], "summary": "Publish a version", "description": "Publishes an immutable version. Versions are semantic versions (`MAJOR.MINOR.PATCH[-prerelease]`), must be unique\nper item and can never be overwritten; correct a mistake by publishing a higher version and yanking the bad one.\nLimits: 100 files, 512 KiB per file, 2 MiB per version (see `get_api_index`), and a storage quota per owning account over all its items\n(20 MB unverified, 200 MB verified email, 1 GB verified publisher); a version that does not fit answers **413 `quota_exceeded`** and stores nothing.\nThe version is scanned for malware patterns before the answer; a blocked version is quarantined (see `get_version_bundle`). Paths are relative, use `/`, and\nmay not contain `..`. If `content_hash` is sent, the server recomputes it and answers 422 on mismatch.\nFires `item.version.published` (and `item.published` for the first public version).\n", "security": [ { "bearerAuth": [ "items:publish" ] } ], "x-scopes": [ "items:publish" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "publish_version", "title": "Publish version", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }, "x-cli": "versions publish", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionCreate" }, "examples": { "skill": { "value": { "version": "1.4.0", "changelog": "Adds multi-currency totals and a --strict mode.", "files": [ { "path": "SKILL.md", "content": "---\nname: invoice-extractor\ndescription: Extract invoice fields from PDFs.\n---\n\nRun src/extract.py on a PDF.\n", "encoding": "utf8", "content_type": "text/markdown", "preview": true }, { "path": "src/extract.py", "content": "import sys\n\nprint('extract', sys.argv[1:])\n", "encoding": "utf8", "content_type": "text/x-python" } ], "dependencies": [ { "item": "acme/pdf-text-layer", "range": "^2.0.0" } ], "manifest": { "name": "acme/invoice-extractor", "version": "1.4.0", "kind": "skill" } } } } } } }, "responses": { "201": { "description": "The published version.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemVersion" }, "examples": { "default": { "value": { "id": "ver_xinvoice2345", "object": "item_version", "item": "acme/invoice-extractor", "item_id": "itm_invoiceextr2", "version": "1.4.0", "changelog": "Adds multi-currency totals and a --strict mode.", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "size_bytes": 48213, "file_count": 3, "dependencies": [ { "item": "acme/pdf-text-layer", "range": "^2.0.0" } ], "yanked": false, "yanked_reason": null, "prerelease": false, "archive_sha256": "a3c0f5bd09a1d7b4e2f8c61d9b7e45a0c1f3d2e8b6a49f7c05d1e3b28a6c4f90", "manifest": null, "created_by": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "created_at": "2026-10-28T09:10:02Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/versions/{version}": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" }, { "$ref": "#/components/parameters/VersionPath" } ], "get": { "operationId": "get_version", "tags": [ "versions" ], "summary": "Get a version", "description": "One version with its file list (paths, sizes, hashes; contents only through the bundle). `latest` resolves to the highest non-yanked, non-quarantined stable version, or, only when the item has no stable version, the highest live prerelease. For a quarantined version (see `get_version_bundle`) callers who do not manage the item receive the version without `files`, `manifest` and `verification`.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_version", "title": "Get version", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "versions get", "responses": { "200": { "description": "The version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemVersion" }, "examples": { "default": { "value": { "id": "ver_xinvoice2345", "object": "item_version", "item": "acme/invoice-extractor", "item_id": "itm_invoiceextr2", "version": "1.4.0", "changelog": "Adds multi-currency totals and a --strict mode.", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "size_bytes": 48213, "file_count": 3, "files": [ { "path": "SKILL.md", "size_bytes": 2210, "sha256": "0d513c7b5ef7777ab855c1d1608db8916080485038901daa59524757549540a2", "content_type": "text/markdown", "preview": true }, { "path": "src/extract.py", "size_bytes": 41876, "sha256": "75737d9d063bc4d4ac1613bc16d49e275727cf548a7e6eb029ac6087d22a24c6", "content_type": "text/x-python", "preview": false }, { "path": "README.md", "size_bytes": 4127, "sha256": "42c59af8a4bae559bc5a5d5d3f06f02ee30e2afcd9f2d0c39b38ccee6d0fa9b8", "content_type": "text/markdown", "preview": true } ], "dependencies": [ { "item": "acme/pdf-text-layer", "range": "^2.0.0" } ], "yanked": false, "yanked_reason": null, "prerelease": false, "manifest": null, "verification": { "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" }, "created_by": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "created_at": "2026-10-28T09:10:02Z" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "update_version", "tags": [ "versions" ], "summary": "Yank or restore a version", "description": "Yanking hides a version from `latest` resolution and warns installers, but never deletes content, so existing lockfiles still resolve. Only `changelog`, `yanked` and `yanked_reason` can change. Fires `item.updated`.", "security": [ { "bearerAuth": [ "items:publish" ] } ], "x-scopes": [ "items:publish" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": { "tool": "update_version", "title": "Yank or restore version", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "versions yank", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionUpdate" }, "examples": { "yank": { "value": { "yanked": true, "yanked_reason": "Crashes on invoices without a total line." } } } } } }, "responses": { "200": { "description": "The updated version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemVersion" }, "examples": { "default": { "value": { "id": "ver_xinvoice2345", "object": "item_version", "item": "acme/invoice-extractor", "item_id": "itm_invoiceextr2", "version": "1.4.0", "changelog": "Adds multi-currency totals and a --strict mode.", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "size_bytes": 48213, "file_count": 3, "dependencies": [], "yanked": true, "yanked_reason": "Crashes on invoices without a total line.", "prerelease": false, "manifest": null, "created_by": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "created_at": "2026-10-28T09:10:02Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/versions/{version}/bundle": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" }, { "$ref": "#/components/parameters/VersionPath" } ], "get": { "operationId": "get_version_bundle", "tags": [ "versions" ], "summary": "Download a version", "description": "All files of a version in one JSON document (at most 2 MiB of content, base64 for binary files). Clients must verify every `sha256` and the `content_hash`. Paid versions return 402 `payment_required` until you are entitled, except for files flagged `preview`. A **quarantined** version (the security scan blocked it and no administrator allowed it, or an administrator blocked it) answers **403 `version_quarantined`** to everybody except the owner, members of the owning account with write access and administrators; the check runs before the entitlement check.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "versions download", "responses": { "200": { "description": "The bundle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bundle" }, "examples": { "default": { "value": { "item": "acme/invoice-extractor", "version": "1.4.0", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "files": [ { "path": "SKILL.md", "content": "---\nname: invoice-extractor\ndescription: Extract invoice fields from PDFs.\n---\n\nRun src/extract.py on a PDF.\n", "encoding": "utf8", "sha256": "0d513c7b5ef7777ab855c1d1608db8916080485038901daa59524757549540a2", "size_bytes": 2210, "content_type": "text/markdown" } ] } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/versions/{version}/archive.zip": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" }, { "$ref": "#/components/parameters/VersionPath" } ], "get": { "operationId": "get_version_archive", "tags": [ "distribution" ], "summary": "Download a version as a ZIP archive", "description": "All files of a version as one **deterministic, store-only (uncompressed) ZIP**, for tools that understand archives but not\nthis API (`unzip`, Claude Code `archive` plugin sources, CI caches). The same version always yields byte-identical output, so\nits SHA-256 (`X-Content-SHA256`, also `ItemVersion.archive_sha256` once known) can be pinned: entries are sorted by UTF-8\npath bytes, timestamps are fixed to 1980-01-01 00:00:00, permissions are 0644 (0755 for files the publish manifest lists in\n`executable`), names are flagged UTF-8, there are no directory entries, extra fields or data descriptors.\n\n`layout` selects the variant. `plain` (default) holds the published files at their paths. `claude-plugin` wraps a `skill`,\n`prompt` or `mcp_server` item into a Claude Code plugin (`.claude-plugin/plugin.json`, `skills//...`,\n`commands/.md` or `.mcp.json`); other kinds answer 400. Each layout has its own digest.\n\nAccess is exactly that of `get_version_bundle`: free versions are open to everyone, paid versions return **402\n`payment_required`** with an `order_hint` until you are entitled. A version that has any non-preview file is never served\npartially: no entitlement means 402, not a smaller archive. A quarantined version answers **403 `version_quarantined`**, as for\n`get_version_bundle`, whatever `If-None-Match` says. `latest` resolves like `get_version`.\n`Content-Length` and `ETag` (the quoted SHA-256) are exact, so `If-None-Match` revalidation answers 304. A yanked version still\ndownloads and carries `X-RF-Yanked: 1`. A retracted free item answers **410**; a retracted paid item stays downloadable for the\naccounts that bought it.\n\nThe archive is built from the version's files and its **stored, validated** publish manifest only: a file named\n`reuseforge.json` is ordinary content and never configures the plugin, and a version published without a `manifest` has no\n`mcp` section, so an `mcp_server` version cannot take the `claude-plugin` layout. The `claude-plugin` layout is refused (400)\nonce the item's kind differs from the kind in the stored manifest. Names that would overwrite each other on a case-insensitive\nor normalising filesystem (`SKILL.md` and `Skill.md`, NFC and NFD spellings, a file that is also a directory) make the\nversion unarchivable: 400, without a `layout` pointer.\n", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "versions download --format zip", "parameters": [ { "$ref": "#/components/parameters/ArchiveLayout" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The archive.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "X-Content-SHA256": { "$ref": "#/components/headers/XContentSha256" }, "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" }, "Content-Length": { "$ref": "#/components/headers/ContentLength" } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" }, "examples": { "default": { "summary": "Binary ZIP (shown as text here)", "value": "PK\u0003\u0004 ... (store-only ZIP, 3 entries)" } } } } }, "304": { "description": "Not modified. Keeps `ETag` and `X-Content-SHA256`." }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/marketplaces/{owner}.json": { "parameters": [ { "$ref": "#/components/parameters/Owner" } ], "get": { "operationId": "get_marketplace", "tags": [ "distribution" ], "summary": "Claude Code plugin marketplace of an owner", "description": "A hosted [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugins/marketplace-reference) for one account.\nAdd it with `/plugin marketplace add https://reuseforge.com/api/v1/marketplaces/.json`, then\n`/plugin install @reuseforge-`.\n\nIt lists the owner's **public, free, active** items of kind `skill`, `prompt` or `mcp_server` that have a latest\nnon-yanked, non-prerelease, non-quarantined version. Retracted, archived, draft, private, unlisted and paid items never appear, and neither does a quarantined version (the entry falls back to the next stable release). Each entry's `source` is\n`{source: archive, url, sha256}`: the `claude-plugin` layout of `get_version_archive` for that exact version, pinned by\nits SHA-256, so Claude Code refuses a download that differs. An owner without matching items yields an empty `plugins`\nlist; a handle that does not exist is 404.\nThe marketplace `name` is `reuseforge-`. Entries whose plugin name would read as one of Anthropic's own are left out.\nA cold digest cache is filled for at most 8 versions per request; entries not pinned yet are omitted and\n`X-ReuseForge-Marketplace-Pending` reports how many, with a short cache lifetime so the list completes on the next fetch (a\n`304` repeats the header). A version whose build started and never finished is skipped for 15 minutes and given up after 3\nattempts; a version that cannot be packaged is left out. At most 100 plugins are listed, most downloaded first; when more\nitems qualify, `X-ReuseForge-Marketplace-Truncated: 100` says so. Entries carry `keywords` (the item's tags, also repeated as `tags`).\n", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "marketplaces get", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The marketplace document (the file Claude Code reads as `marketplace.json`).", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaudeMarketplace" }, "examples": { "default": { "value": { "name": "reuseforge-acme", "description": "Free skills, prompts and MCP servers published by acme on ReuseForge.", "owner": { "name": "Acme Inc.", "url": "https://reuseforge.com/app/acme" }, "plugins": [ { "name": "invoice-extractor", "source": { "source": "archive", "url": "https://reuseforge.com/api/v1/items/acme/invoice-extractor/versions/1.4.0/archive.zip?layout=claude-plugin", "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1" }, "description": "Extract line items and totals from invoice PDFs.", "version": "1.4.0", "category": "skill", "author": { "name": "Acme Inc." }, "homepage": "https://reuseforge.com/app/acme/invoice-extractor", "license": "MIT", "keywords": [ "invoices", "pdf" ] } ] } } } } } }, "304": { "description": "Not modified. Keeps `ETag` and `X-ReuseForge-Marketplace-Pending`." }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/items/{owner}/{slug}/versions/{version}/verifications": { "parameters": [ { "$ref": "#/components/parameters/Owner" }, { "$ref": "#/components/parameters/Slug" }, { "$ref": "#/components/parameters/VersionPath" } ], "post": { "operationId": "request_verification", "tags": [ "verification" ], "summary": "Request a verification run", "description": "Asks the platform to verify a version. Returns 202 with a stored `Verification`; poll `get_verification` or subscribe to\n`verification.completed`. The hosted runner is `static-v1`: it runs inside the API within a bounded CPU budget and\ncompletes before the response is sent (the record is already `passed` or `failed`), re-checking file hashes, the\nmanifest, license and secrets and, per kind, SKILL.md front matter and MCP configuration. It does **not** execute the\npublisher's tests: `tests_total` / `tests_passed` count static checks, `tests_pass_rate` stays `null`, and\nplanner signals are never changed by it. A sandbox runner that executes `test.command` and attests a real\n`tests_pass_rate` is a separate runner value and is not available yet.\n", "security": [ { "bearerAuth": [ "items:publish" ] } ], "x-scopes": [ "items:publish" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "request_verification", "title": "Request verification", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }, "x-cli": "verify request", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Accepted. Asynchronous runners return `queued`; the `static-v1` runner returns the finished record.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" }, "examples": { "default": { "value": { "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verifications/{verification_id}": { "get": { "operationId": "get_verification", "tags": [ "verification" ], "summary": "Get a verification", "description": "State and result of a verification run.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_verification", "title": "Get verification", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "verify get", "parameters": [ { "$ref": "#/components/parameters/VerificationId" } ], "responses": { "200": { "description": "The verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" }, "examples": { "default": { "value": { "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" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/plans": { "post": { "operationId": "plan_goal", "tags": [ "planning" ], "summary": "Plan a goal", "description": "Turns a goal and an optional budget into requirements, a Pareto front of plans over (quality up, cost down, risk down)\nand a recommended plan, each with explanations. Every requirement is either covered by reusing a candidate (free or\npaid) or by building it from blueprints (arXiv papers). Shared paid items are counted once.\n\nThe result is stored for 24 hours under `id` (`pln_...`); pass it to `create_order`, `build_brief` and `get_mcp_config`.\nWith `online: true` the planner also queries external connectors; if some fail, the plan is still returned with\n`partial: true` and per-connector status in `sources`. Anonymous callers are limited to 5 plans a minute.\n", "x-scopes": [], "x-rate-limit": "plan", "x-idempotent": true, "x-mcp": { "tool": "plan_goal", "title": "Plan a goal", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": true }, "x-cli": "plan", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRequest" }, "examples": { "default": { "value": { "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 } } } } } } }, "responses": { "201": { "description": "The stored plan.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "examples": { "default": { "value": { "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 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/plans/{plan_id}": { "get": { "operationId": "get_plan", "tags": [ "planning" ], "summary": "Get a plan", "description": "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.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_plan", "title": "Get plan", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "plans get", "parameters": [ { "$ref": "#/components/parameters/PlanId" } ], "responses": { "200": { "description": "The plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "examples": { "default": { "value": { "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 } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/plans/{plan_id}/brief": { "get": { "operationId": "build_brief", "tags": [ "planning" ], "summary": "Build brief for the parts to build", "description": "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.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "build_brief", "title": "Build brief", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "plans brief", "parameters": [ { "$ref": "#/components/parameters/PlanId" }, { "name": "option", "in": "query", "description": "Index into `pareto_front`. Defaults to `recommended_index`.", "schema": { "type": "integer", "minimum": 0, "maximum": 11 } } ], "responses": { "200": { "description": "The brief.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brief" }, "examples": { "default": { "value": { "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" ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/discover": { "get": { "operationId": "discover_external", "tags": [ "planning" ], "summary": "Discover external candidates", "description": "Queries the external connectors (GitHub, MCP registry, arXiv, Hugging Face, npm, PyPI and others; see `list_connectors`)\nin parallel and returns normalised candidates with risk signals. At most 12 outbound calls are made per request.\nOne failing connector never fails the request: its `sources` entry carries the error.\n", "x-scopes": [], "x-rate-limit": "discover", "x-idempotent": false, "x-mcp": { "tool": "discover_external", "title": "Discover external", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": true }, "x-cli": "discover", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 300 }, "example": "pdf invoice extraction" }, { "name": "connectors", "in": "query", "description": "Restrict to these connector names (comma separated). Default is every ready block source.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 12 } }, { "name": "kind", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKind" }, "maxItems": 11 } }, { "name": "limit", "in": "query", "description": "Maximum results per connector.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 } } ], "responses": { "200": { "description": "Candidates and per-connector status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverResult" }, "examples": { "default": { "value": { "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" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/mcp-config": { "get": { "operationId": "get_mcp_config", "tags": [ "planning" ], "summary": "MCP configuration for a goal", "description": "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.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_mcp_config", "title": "Get MCP config", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "mcp-config", "parameters": [ { "name": "plan_id", "in": "query", "schema": { "type": "string", "pattern": "^pln_[a-z2-7]{12}$" } }, { "name": "goal", "in": "query", "schema": { "type": "string", "maxLength": 500 } }, { "name": "capabilities", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 24 } } ], "responses": { "200": { "description": "The configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpConfig" }, "examples": { "default": { "value": { "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" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/connectors": { "get": { "operationId": "list_connectors", "tags": [ "planning" ], "summary": "List connectors", "description": "Block sources the planner and `discover_external` can query, and agent-side MCP servers that can be handed to a buyer's agent.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "list_connectors", "title": "List connectors", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "connectors list", "responses": { "200": { "description": "The connectors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorPage" }, "examples": { "default": { "value": { "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 } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders": { "get": { "operationId": "list_orders", "tags": [ "orders" ], "summary": "List your orders", "description": "Orders you bought (`role=buyer`, default) or sold (`role=seller`, only the order items you sell are shown). Newest first.", "security": [ { "bearerAuth": [ "orders:read" ] } ], "x-scopes": [ "orders:read" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "list_orders", "title": "List orders", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "orders list", "parameters": [ { "name": "role", "in": "query", "schema": { "type": "string", "enum": [ "buyer", "seller" ], "default": "buyer" } }, { "name": "state", "in": "query", "schema": { "$ref": "#/components/schemas/OrderState" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPage" }, "examples": { "default": { "value": { "data": [ { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "released", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": "accepted" } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-03T11:20:45Z", "payouts": [ { "id": "pyo_sellerpay222", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "seller", "recipient": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "address": "0xA11cE0000000000000000000000000000000b0b2", "rail": "base-usdc", "amount_cents": 1188, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null }, { "id": "pyo_platformfee2", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "platform_fee", "recipient": null, "address": "0xFee0000000000000000000000000000000000001", "rail": "base-usdc", "amount_cents": 12, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T11:21:10Z" } ], "next_cursor": null, "has_more": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "create_order", "tags": [ "orders" ], "summary": "Create an order", "description": "Quotes an order for paid items, either from a plan (`plan_id`, optional `option`; the plan's `paid_items` are\nordered) or from an explicit `items` list. Free items never need an order. The order starts `awaiting_payment`\nwith a `payment` object telling the buyer where to send money; prices, the fee rate and the windows are\nsnapshotted and never change afterwards. The quote expires at `payment.expires_at`.\n\nThe fee (`fee_bps`, default 100 = 1%) is deducted from the seller's proceeds at release; the buyer pays\n`total_cents`, which equals the sum of the item prices. `Idempotency-Key` is required.\n", "security": [ { "bearerAuth": [ "orders:create" ] } ], "x-scopes": [ "orders:create" ], "x-rate-limit": "payments", "x-idempotent": true, "x-mcp": { "tool": "create_order", "title": "Create order", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }, "x-cli": "orders create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" }, "examples": { "from_plan": { "summary": "Order the paid items of the recommended plan", "value": { "plan_id": "pln_goalinvoice2", "rail": "base-usdc", "wallet": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7" } }, "explicit": { "summary": "Order specific items", "value": { "items": [ { "item": "janedoe/invoice-rag-harness", "version": "0.9.2" } ], "rail": "simulated", "accept_window_days": 7 } } } } } }, "responses": { "201": { "description": "The quoted order.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "awaiting_payment", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "awaiting_payment", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000", "tx_ref": null, "confirmations": 0, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": null, "settled_at": null, "payouts": [], "next_actions": [ { "type": "send_payment", "description": "Transfer 12.00 USDC on Base Sepolia to the escrow contract, then call pay_order with the transaction hash.", "chain_id": 84532, "to": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "data": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000" } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:05:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{order_id}": { "get": { "operationId": "get_order", "tags": [ "orders" ], "summary": "Get an order", "description": "Buyers see the whole order. A seller sees only the items they sell. Time-based transitions (delivery deadline, acceptance window) are applied when an order is read, so the state is always current.", "security": [ { "bearerAuth": [ "orders:read" ] } ], "x-scopes": [ "orders:read" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_order", "title": "Get order", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "orders get", "parameters": [ { "$ref": "#/components/parameters/OrderId" } ], "responses": { "200": { "description": "The order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "delivered": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "delivered", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [ { "type": "review_delivery", "description": "Test the delivered item, then call accept_order to release payment or dispute_order before 2026-11-10T10:08:30Z." } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:08:30Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{order_id}/pay": { "post": { "operationId": "pay_order", "tags": [ "orders" ], "summary": "Fund an order", "description": "Tells the platform the buyer has paid and asks it to verify. On a real rail send the transaction hash\n(`tx_ref`); the platform checks the chain (amount, token, escrow address, confirmations). On the `simulated`\nrail send an empty body and the platform books a test deposit; simulated funds are never real money.\n\nReturns 200 with `state: funded` once the deposit has enough confirmations, or 202 with\n`payment.status: pending_confirmations`; poll `get_order` or wait for `order.funded`.\nThe token spend limit (`spend_limit_cents`) is enforced here and the amount is counted only on success.\n`Idempotency-Key` is required, so a retry after a timeout can never double-count a payment.\n", "security": [ { "bearerAuth": [ "orders:pay" ] } ], "x-scopes": [ "orders:pay" ], "x-rate-limit": "payments", "x-idempotent": true, "x-mcp": { "tool": "pay_order", "title": "Pay order", "readOnly": false, "destructive": true, "idempotent": false, "openWorld": true }, "x-cli": "orders pay", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayOrder" }, "examples": { "onchain": { "summary": "Submit a transaction hash", "value": { "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b" } }, "simulated": { "summary": "Simulated rail", "value": {} } } } } }, "responses": { "200": { "description": "Funded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:07:12Z" } } } } } }, "202": { "description": "Payment seen but not final; confirmations pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "pending": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "awaiting_payment", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "pending_confirmations", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 1, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": null, "settled_at": null, "payouts": [], "next_actions": [ { "type": "wait", "description": "Payment seen with 1 of 3 confirmations. Poll get_order or wait for the order.funded webhook." } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:06:20Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/orders/{order_id}/cancel": { "post": { "operationId": "cancel_order", "tags": [ "orders" ], "summary": "Cancel an unpaid order", "description": "Only orders still `awaiting_payment` can be cancelled. Idempotent.", "security": [ { "bearerAuth": [ "orders:create" ] } ], "x-scopes": [ "orders:create" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "cancel_order", "title": "Cancel order", "readOnly": false, "destructive": true, "idempotent": true, "openWorld": false }, "x-cli": "orders cancel", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The cancelled order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "cancelled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "awaiting_payment", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000", "tx_ref": null, "confirmations": 0, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": null, "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:09:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{order_id}/deliver": { "post": { "operationId": "deliver_order", "tags": [ "orders" ], "summary": "Deliver sold items (seller)", "description": "Seller side. Marks items of a funded order as delivered and starts the buyer's acceptance window. Items hosted on\nReuseForge (`access.type: item_version`) are delivered automatically when the order is funded; call this for\nitems whose content lives elsewhere (`url`, `message`). Fires `order.delivered` when every item is delivered.\nDeliveries are accepted until `deliver_by`; after that the buyer is refunded.\n", "security": [ { "bearerAuth": [ "orders:create" ] } ], "x-scopes": [ "orders:create" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "deliver_order", "title": "Deliver order items", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "orders deliver", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverOrder" }, "examples": { "default": { "value": { "items": [ { "item_id": "itm_ragharness22", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" } ] } } } } } }, "responses": { "200": { "description": "The order with the delivered items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "delivered", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [ { "type": "review_delivery", "description": "Test the delivered item, then call accept_order to release payment or dispute_order before 2026-11-10T10:08:30Z." } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:08:30Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{order_id}/accept": { "post": { "operationId": "accept_order", "tags": [ "orders" ], "summary": "Accept delivery and release escrow", "description": "Buyer confirms satisfaction; escrow for the delivered items is released to the sellers (minus the platform fee).\n**Irreversible.** Requires the explicit `orders:accept` scope, which is never part of default tokens, so an\nautonomous agent cannot confirm satisfaction on its own unless a human granted it. The body must contain\n`confirm: true`. Without `item_ids` every delivered item is accepted. If the buyer stays silent, the acceptance\nwindow expiring releases the funds automatically (`release_reason: window_expired`).\nOn self-custody rails the response may carry a `sign_transaction` entry in `next_actions` that the buyer's wallet must sign.\n", "security": [ { "bearerAuth": [ "orders:accept" ] } ], "x-scopes": [ "orders:accept" ], "x-rate-limit": "payments", "x-idempotent": true, "x-mcp": { "tool": "accept_order", "title": "Accept order and release payment", "readOnly": false, "destructive": true, "idempotent": true, "openWorld": true }, "x-cli": "orders accept", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptOrder" }, "examples": { "default": { "value": { "confirm": true, "note": "Tested against 400 invoices." } } } } } }, "responses": { "200": { "description": "Settled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "released", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": "accepted" } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-03T11:20:45Z", "payouts": [ { "id": "pyo_sellerpay222", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "seller", "recipient": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "address": "0xA11cE0000000000000000000000000000000b0b2", "rail": "base-usdc", "amount_cents": 1188, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null }, { "id": "pyo_platformfee2", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "platform_fee", "recipient": null, "address": "0xFee0000000000000000000000000000000000001", "rail": "base-usdc", "amount_cents": 12, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T11:21:10Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{order_id}/dispute": { "post": { "operationId": "dispute_order", "tags": [ "orders" ], "summary": "Dispute delivered items", "description": "Buyer freezes escrow for delivered (or overdue) items while an arbiter decides. Allowed inside the acceptance window. Needs only `orders:create`, so a restricted agent can always raise a problem even though it cannot release money.", "security": [ { "bearerAuth": [ "orders:create" ] } ], "x-scopes": [ "orders:create" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "dispute_order", "title": "Dispute order", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "orders dispute", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeOrder" }, "examples": { "default": { "value": { "reason": "The harness crashes on startup with the documented config (KeyError: embedder).", "evidence_urls": [ "https://gist.github.com/samdev/0f1e2d3c4b5a69788776655443322110" ] } } } } } }, "responses": { "200": { "description": "The order with disputed items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "disputed", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": { "reason": "The harness crashes on startup with the documented config (KeyError: embedder).", "opened_at": "2026-11-03T10:40:00Z" }, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:40:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{order_id}/items/{item_id}/refund": { "post": { "operationId": "refund_order_item", "tags": [ "orders" ], "summary": "Refund an item (seller)", "description": "Seller voluntarily returns the whole price of one item to the buyer. Allowed while the item is `pending`, `delivered` or `disputed`. The platform fee is not charged on refunds.", "security": [ { "bearerAuth": [ "orders:create" ] } ], "x-scopes": [ "orders:create" ], "x-rate-limit": "payments", "x-idempotent": true, "x-mcp": { "tool": "refund_order_item", "title": "Refund order item", "readOnly": false, "destructive": true, "idempotent": true, "openWorld": false }, "x-cli": "orders refund", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/OrderItemId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundItem" }, "examples": { "default": { "value": { "note": "Refunded after a failed delivery." } } } } } }, "responses": { "200": { "description": "The order with the refunded item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "refunded", "price_cents": 1200, "fee_cents": 0, "seller_amount_cents": 0, "project_id": null, "delivery": null, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": null, "dispute": null, "resolution": { "seller_bps": 0, "refund_cents": 1200, "note": "Seller did not deliver before the deadline.", "resolved_at": "2026-11-10T10:09:00Z" }, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 0, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-10T10:09:00Z", "payouts": [ { "id": "pyo_buyerrefun22", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "refund", "recipient": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "rail": "base-usdc", "amount_cents": 1200, "currency": "USD", "state": "sent", "tx_ref": "0x4c1d9e7b2a6f08d35e9a1b7c4d2e6f80a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2", "sent_at": "2026-11-10T10:10:30Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-10T10:10:30Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{order_id}/items/{item_id}/resolve": { "post": { "operationId": "resolve_order_item", "tags": [ "orders" ], "summary": "Resolve a dispute (arbiter)", "description": "Platform arbiter splits a disputed item between seller and buyer. `seller_bps` is the seller's share of the item price in basis points (10000 = pay the seller everything, 0 = refund the buyer). Requires the `admin` scope on an admin account.", "security": [ { "bearerAuth": [ "admin" ] } ], "x-scopes": [ "admin" ], "x-rate-limit": "payments", "x-idempotent": true, "x-mcp": false, "x-cli": "admin resolve", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/OrderItemId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveDispute" }, "examples": { "default": { "value": { "seller_bps": 0, "note": "Seller did not deliver before the deadline." } } } } } }, "responses": { "200": { "description": "The order after resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "default": { "value": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "refunded", "price_cents": 1200, "fee_cents": 0, "seller_amount_cents": 0, "project_id": null, "delivery": null, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": null, "dispute": null, "resolution": { "seller_bps": 0, "refund_cents": 1200, "note": "Seller did not deliver before the deadline.", "resolved_at": "2026-11-10T10:09:00Z" }, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 0, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-10T10:09:00Z", "payouts": [ { "id": "pyo_buyerrefun22", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "refund", "recipient": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "rail": "base-usdc", "amount_cents": 1200, "currency": "USD", "state": "sent", "tx_ref": "0x4c1d9e7b2a6f08d35e9a1b7c4d2e6f80a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2", "sent_at": "2026-11-10T10:10:30Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-10T10:10:30Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payouts": { "get": { "operationId": "list_payouts", "tags": [ "orders" ], "summary": "List payouts", "description": "Money sent to you: seller proceeds, refunds and project revenue shares. Platform fee rows are visible to the seller whose sale produced them.", "security": [ { "bearerAuth": [ "orders:read" ] } ], "x-scopes": [ "orders:read" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "list_payouts", "title": "List payouts", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "payouts list", "parameters": [ { "name": "kind", "in": "query", "schema": { "$ref": "#/components/schemas/PayoutKind" } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "failed" ] } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of payouts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutPage" }, "examples": { "default": { "value": { "data": [ { "id": "pyo_sellerpay222", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "seller", "recipient": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "address": "0xA11cE0000000000000000000000000000000b0b2", "rail": "base-usdc", "amount_cents": 1188, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null }, { "id": "pyo_platformfee2", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "platform_fee", "recipient": null, "address": "0xFee0000000000000000000000000000000000001", "rail": "base-usdc", "amount_cents": 12, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null } ], "next_cursor": null, "has_more": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/earnings": { "get": { "operationId": "get_earnings", "tags": [ "orders" ], "summary": "Seller earnings summary", "description": "Where your sales money is right now. Changing payout addresses is deliberately not part of the API; it needs an interactive session.", "security": [ { "bearerAuth": [ "orders:read" ] } ], "x-scopes": [ "orders:read" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_earnings", "title": "Get earnings", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "payouts earnings", "responses": { "200": { "description": "The summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Earnings" }, "examples": { "default": { "value": { "currency": "USD", "in_escrow_cents": 3600, "releasable_soon_cents": 1200, "available_cents": 0, "paid_out_cents": 11880, "fees_paid_cents": 120, "by_rail": [ { "rail": "base-usdc", "paid_out_cents": 11880 } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects": { "get": { "operationId": "list_projects", "tags": [ "projects" ], "summary": "List crowdfunded projects", "description": "Public listing of projects with funding progress. Newest first.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "list_projects", "title": "List projects", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "projects list", "parameters": [ { "name": "state", "in": "query", "schema": { "$ref": "#/components/schemas/ProjectState" } }, { "name": "proposer", "in": "query", "description": "Handle of the proposing account.", "schema": { "type": "string", "maxLength": 39 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of projects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPage" }, "examples": { "default": { "value": { "data": [ { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } ], "next_cursor": null, "has_more": false } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "create_project", "tags": [ "projects" ], "summary": "Propose a crowdfunded project", "description": "Opens a project: backers fund a goal, developers are hired for the deliverables, backers receive revenue units\nin proportion to their pledge and developers a pre-agreed share capped at 5000 bps. Developer `budget_bps` must\ntotal 10000 and milestone `bps` must total 10000. Milestones are approved by pledge-weighted vote and paid from\nescrow. Revenue units may be regulated securities where you live; payments run on the simulated or test rails\nuntil the operator enables real ones.\n", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "create_project", "title": "Create project", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }, "x-cli": "projects create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" }, "examples": { "default": { "value": { "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "goal_cents": 500000, "deadline_days": 30, "developers": [ { "account": "janedoe", "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "name": "Ingestion pipeline", "bps": 3000 }, { "name": "Reconciliation engine", "bps": 4000 }, { "name": "Dashboard and docs", "bps": 3000 } ] } } } } } }, "responses": { "201": { "description": "The open project.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "open", "goal_cents": 500000, "raised_cents": 0, "pending_cents": 0, "progress": 0.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": null, "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 0 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 0 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 0 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}": { "get": { "operationId": "get_project", "tags": [ "projects" ], "summary": "Get a project", "description": "Funding state, milestones with vote tallies, the cap table and dividends.", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_project", "title": "Get project", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "projects get", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/backings": { "post": { "operationId": "back_project", "tags": [ "projects" ], "summary": "Back a project", "description": "Pledges money to an open project. Pledges cannot exceed the remaining goal; the pledge that reaches the goal flips\nthe project to `funded`. Spends money, so the token needs `orders:pay` and the amount counts against its spend\nlimit. Pledges can be withdrawn with `withdraw_backing` until the project is funded. `Idempotency-Key` is required.\n", "security": [ { "bearerAuth": [ "projects:write", "orders:pay" ] } ], "x-scopes": [ "projects:write", "orders:pay" ], "x-rate-limit": "payments", "x-idempotent": true, "x-mcp": { "tool": "back_project", "title": "Back project", "readOnly": false, "destructive": true, "idempotent": false, "openWorld": true }, "x-cli": "projects back", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackProject" }, "examples": { "simulated": { "value": { "amount_cents": 300000, "rail": "simulated" } }, "onchain": { "value": { "amount_cents": 300000, "rail": "base-usdc", "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "wallet": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7" } } } } } }, "responses": { "201": { "description": "The backing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Backing" }, "examples": { "default": { "value": { "id": "bck_samreconpldg", "object": "backing", "project_id": "prj_reconharnes2", "backer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "amount_cents": 300000, "currency": "USD", "state": "confirmed", "units": 480000000000, "payment": { "rail": "simulated", "network": null, "asset": "USD", "status": "confirmed", "amount_cents": 300000, "amount_atomic": "300000", "address": "escrow:rb-hosted", "memo": "bck_samreconpldg", "uri": null, "tx_ref": "sim_tx_5d1f08a9c3e2", "confirmations": 1, "required_confirmations": 1, "expires_at": null, "refund_address": null, "simulated": true }, "created_at": "2026-10-12T17:20:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/backings/{backing_id}": { "delete": { "operationId": "withdraw_backing", "tags": [ "projects" ], "summary": "Withdraw a pledge", "description": "Returns a pledge to the backer and burns its units. Only while the project is `open`. Idempotent.", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "payments", "x-idempotent": false, "x-mcp": { "tool": "withdraw_backing", "title": "Withdraw backing", "readOnly": false, "destructive": true, "idempotent": true, "openWorld": false }, "x-cli": "projects withdraw", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/BackingId" } ], "responses": { "204": { "description": "Withdrawn." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/milestones/{index}/delivery": { "post": { "operationId": "deliver_milestone", "tags": [ "projects" ], "summary": "Deliver a milestone (developer)", "description": "A developer submits evidence (a link, commit or release) for a milestone. A new submission restarts the vote. A rejected milestone may be resubmitted at most three times.", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "deliver_milestone", "title": "Deliver milestone", "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }, "x-cli": "projects deliver", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/MilestoneIndex" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverMilestone" }, "examples": { "default": { "value": { "evidence": "https://github.com/janedoe/invoice-recon/pull/9" } } } } } }, "responses": { "200": { "description": "The project with the submitted milestone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/milestones/{index}/votes": { "post": { "operationId": "vote_milestone", "tags": [ "projects" ], "summary": "Vote on a milestone (backer)", "description": "Backers approve or reject a submitted milestone, weighted by pledge amount. More than half of the goal in approving weight approves at once. A backer can change their vote until the milestone is decided.", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "vote_milestone", "title": "Vote on milestone", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "projects vote", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/MilestoneIndex" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteMilestone" }, "examples": { "default": { "value": { "approve": true } } } } } }, "responses": { "200": { "description": "The project with updated tallies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/milestones/{index}/finalize": { "post": { "operationId": "finalize_milestone", "tags": [ "projects" ], "summary": "Finalize a milestone vote", "description": "Anyone may call this after the vote window has elapsed to apply the outcome (more approval than rejection approves; a tie with no votes goes to the arbiter). A no-op before the window ends or after a decision.", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "finalize_milestone", "title": "Finalize milestone", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "projects finalize", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/MilestoneIndex" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The project after finalization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/abort-votes": { "post": { "operationId": "vote_abort", "tags": [ "projects" ], "summary": "Vote to abort a funded project", "description": "Backers holding more than half of the pledges can abort a stalled project; unreleased funds are then refunded pro rata. Set `abort: false` to withdraw your vote.", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": { "tool": "vote_abort", "title": "Vote to abort project", "readOnly": false, "destructive": true, "idempotent": true, "openWorld": false }, "x-cli": "projects abort", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteAbort" }, "examples": { "default": { "value": { "abort": true } } } } } }, "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/transfers": { "post": { "operationId": "transfer_units", "tags": [ "projects" ], "summary": "Transfer revenue units", "description": "Moves units to another account. Allowed once the project is funded. Dividends already accrued stay with the sender. `Idempotency-Key` is required.", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "payments", "x-idempotent": true, "x-mcp": { "tool": "transfer_units", "title": "Transfer units", "readOnly": false, "destructive": true, "idempotent": false, "openWorld": false }, "x-cli": "projects transfer", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferUnits" }, "examples": { "default": { "value": { "to": "acme", "units": 10000000000 } } } } } }, "responses": { "200": { "description": "The project with the new cap table.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{project_id}/product": { "put": { "operationId": "attach_product", "tags": [ "projects" ], "summary": "Attach the finished product", "description": "The proposer links the completed project to the item it produced. From then on the item's sales are split across unit holders (after the platform fee). Items attached to a project accept stablecoin rails only.", "security": [ { "bearerAuth": [ "projects:write" ] } ], "x-scopes": [ "projects:write" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": { "tool": "attach_product", "title": "Attach product", "readOnly": false, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "projects attach", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachProduct" }, "examples": { "default": { "value": { "item": "janedoe/invoice-rag-harness" } } } } } }, "responses": { "200": { "description": "The project with its product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "default": { "value": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/portfolio": { "get": { "operationId": "get_portfolio", "tags": [ "projects" ], "summary": "Project portfolio", "description": "Stakes, dividends and net result of an account across projects. Positions are public ledger data; `holder` defaults to you.", "security": [ { "bearerAuth": [ "projects:read" ] } ], "x-scopes": [ "projects:read" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": { "tool": "get_portfolio", "title": "Get portfolio", "readOnly": true, "destructive": false, "idempotent": true, "openWorld": false }, "x-cli": "portfolio", "parameters": [ { "name": "holder", "in": "query", "description": "Handle of the account. Defaults to the caller.", "schema": { "type": "string", "maxLength": 39 } } ], "responses": { "200": { "description": "The portfolio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Portfolio" }, "examples": { "default": { "value": { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "currency": "USD", "invested_cents": 300000, "dividends_cents": 0, "net_cents": -300000, "positions": [ { "project_id": "prj_reconharnes2", "title": "Invoice reconciliation harness", "state": "funded", "invested_cents": 300000, "units": 480000000000, "ownership_bps": 4800, "dividends_cents": 0, "net_cents": -300000 } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks": { "get": { "operationId": "list_webhooks", "tags": [ "webhooks" ], "summary": "List webhooks", "description": "Webhook endpoints of the authenticated account (and of organizations you administer when `account` is given).", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "webhooks list", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of webhooks. Secrets are never listed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPage" }, "examples": { "default": { "value": { "data": [ { "id": "whk_ordersandpub", "object": "webhook", "url": "https://hooks.acme.example/reuseforge", "description": "Production order and publish events", "events": [ "item.published", "item.version.published", "order.created", "order.funded", "order.released" ], "account": "acme", "status": "enabled", "disabled_reason": null, "api_version": "1", "consecutive_failures": 0, "last_delivery_at": "2026-11-03T10:08:31Z", "last_success_at": "2026-11-03T10:08:31Z", "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-10-01T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "create_webhook", "tags": [ "webhooks" ], "summary": "Create a webhook", "description": "Registers an HTTPS endpoint. The signing secret (`secret`, `whsec_...`) is returned once; store it. The URL must be\nHTTPS on a public host (no IP literals, no private or link-local ranges, no credentials in the URL, port 443 or\n8443 only; plain `http://localhost` is accepted only by self-hosted nodes). Redirects are not followed. At most\n20 endpoints per account and one endpoint per URL (`409 already_exists`). The platform sends a `ping` event right after\ncreation.\n\nReceiving an event is reading the resource in it, so the credential also needs the read scope of every subscribed\ntype: `orders:read` for `order.*` and `payout.sent`, `items:read` for `item.*`, `review.created` and\n`verification.completed`, `projects:read` for `project.*`. `*` needs all three. Without them: `403 insufficient_scope`.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": false, "x-cli": "webhooks create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "examples": { "default": { "value": { "url": "https://hooks.acme.example/reuseforge", "description": "Production order and publish events", "events": [ "item.published", "item.version.published", "order.created", "order.funded", "order.released" ], "account": "acme" } } } } } }, "responses": { "201": { "description": "The webhook with its one-time secret.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" }, "examples": { "default": { "value": { "id": "whk_ordersandpub", "object": "webhook", "url": "https://hooks.acme.example/reuseforge", "description": "Production order and publish events", "events": [ "item.published", "item.version.published", "order.created", "order.funded", "order.released" ], "account": "acme", "status": "enabled", "disabled_reason": null, "api_version": "1", "consecutive_failures": 0, "last_delivery_at": null, "last_success_at": null, "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-10-01T12:00:00Z", "secret": "whsec_kq7x3n2m5v4b6c8d9f2g3h4j5k6m7n8p" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{webhook_id}": { "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "get": { "operationId": "get_webhook", "tags": [ "webhooks" ], "summary": "Get a webhook", "description": "One endpoint with its delivery health.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "webhooks get", "responses": { "200": { "description": "The webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "default": { "value": { "id": "whk_ordersandpub", "object": "webhook", "url": "https://hooks.acme.example/reuseforge", "description": "Production order and publish events", "events": [ "item.published", "item.version.published", "order.created", "order.funded", "order.released" ], "account": "acme", "status": "enabled", "disabled_reason": null, "api_version": "1", "consecutive_failures": 0, "last_delivery_at": "2026-11-03T10:08:31Z", "last_success_at": "2026-11-03T10:08:31Z", "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-10-01T12:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "update_webhook", "tags": [ "webhooks" ], "summary": "Update a webhook", "description": "Change the URL, events or description, or set `status` to `enabled` to re-enable an endpoint that was automatically disabled (the failure counter resets).\nAdding event types, and pointing an endpoint at another URL, need the read scope of the types it receives (see `create_webhook`);\nrenaming, narrowing and disabling need `webhooks:manage` only. A URL another endpoint of the account already uses is `409 already_exists`.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": false, "x-cli": "webhooks update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" }, "examples": { "reenable": { "value": { "status": "enabled" } } } } } }, "responses": { "200": { "description": "The updated webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "default": { "value": { "id": "whk_ordersandpub", "object": "webhook", "url": "https://hooks.acme.example/reuseforge", "description": "Production order and publish events", "events": [ "item.published", "item.version.published", "order.created", "order.funded", "order.released" ], "account": "acme", "status": "enabled", "disabled_reason": null, "api_version": "1", "consecutive_failures": 0, "last_delivery_at": "2026-11-03T10:08:31Z", "last_success_at": "2026-11-03T10:08:31Z", "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-10-01T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "delete_webhook", "tags": [ "webhooks" ], "summary": "Delete a webhook", "description": "Stops all future deliveries and drops pending retries. Idempotent.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": false, "x-cli": "webhooks delete", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{webhook_id}/rotate-secret": { "post": { "operationId": "rotate_webhook_secret", "tags": [ "webhooks" ], "summary": "Rotate the signing secret", "description": "Issues a new secret. For 24 hours every delivery carries two `v1` signatures (new first, old second) so receivers can switch without downtime; after that only the new secret signs.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": false, "x-cli": "webhooks rotate-secret", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The webhook with the new one-time secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" }, "examples": { "default": { "value": { "id": "whk_ordersandpub", "object": "webhook", "url": "https://hooks.acme.example/reuseforge", "description": "Production order and publish events", "events": [ "item.published", "item.version.published", "order.created", "order.funded", "order.released" ], "account": "acme", "status": "enabled", "disabled_reason": null, "api_version": "1", "consecutive_failures": 0, "last_delivery_at": "2026-11-03T10:08:31Z", "last_success_at": "2026-11-03T10:08:31Z", "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-11-03T10:30:00Z", "secret": "whsec_w4x9c2v7b1n6m3q8r5t0y2u4i6o8p1as", "previous_secret_expires_at": "2026-11-04T10:30:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{webhook_id}/test": { "post": { "operationId": "test_webhook", "tags": [ "webhooks" ], "summary": "Send a test ping", "description": "Synchronously delivers a signed `ping` event and returns the delivery result (success or the failure you would see in production). Does not count toward auto-disable.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "write", "x-idempotent": false, "x-mcp": false, "x-cli": "webhooks test", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "The delivery attempt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "examples": { "default": { "value": { "id": "whd_pingdelivery2", "object": "webhook_delivery", "webhook_id": "whk_ordersandpub", "event_id": "evt_pingevent222", "event_type": "ping", "attempt": 1, "state": "succeeded", "scheduled_at": "2026-11-03T10:31:00Z", "delivered_at": "2026-11-03T10:31:00Z", "response_status": 200, "response_ms": 96, "response_excerpt": "pong", "error": null, "next_attempt_at": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{webhook_id}/deliveries": { "get": { "operationId": "list_webhook_deliveries", "tags": [ "webhooks" ], "summary": "List deliveries", "description": "Delivery attempts for the last 30 days, newest first, with the response status and an excerpt of the receiver's reply.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "webhooks deliveries", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending", "retrying", "succeeded", "failed", "exhausted" ] } }, { "name": "event_type", "in": "query", "schema": { "$ref": "#/components/schemas/EventType" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of deliveries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryPage" }, "examples": { "default": { "value": { "data": [ { "id": "whd_deliveryok22", "object": "webhook_delivery", "webhook_id": "whk_ordersandpub", "event_id": "evt_orderfunded2", "event_type": "order.funded", "attempt": 1, "state": "succeeded", "scheduled_at": "2026-11-03T10:07:12Z", "delivered_at": "2026-11-03T10:07:13Z", "response_status": 200, "response_ms": 184, "response_excerpt": "ok", "error": null, "next_attempt_at": null } ], "next_cursor": null, "has_more": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver": { "post": { "operationId": "redeliver_webhook", "tags": [ "webhooks" ], "summary": "Redeliver an event", "description": "Re-sends the same event (same `evt_` id, fresh signature timestamp) as a new delivery attempt. Receivers must treat the event id as the idempotency key.\nThe credential needs the read scope of the event's type (see `create_webhook`); pings need none and count toward the\nper-minute ping limit of `test_webhook`. `409 invalid_state` while the delivery is still being attempted or the endpoint is\ndisabled, `410 gone` once the event is older than 30 days.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "x-scopes": [ "webhooks:manage" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": false, "x-cli": "webhooks redeliver", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/DeliveryId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "examples": { "default": { "value": { "id": "whd_redelivery222", "object": "webhook_delivery", "webhook_id": "whk_ordersandpub", "event_id": "evt_orderfunded2", "event_type": "order.funded", "attempt": 2, "state": "pending", "scheduled_at": "2026-11-03T10:40:00Z", "delivered_at": null, "response_status": null, "response_ms": null, "response_excerpt": null, "error": null, "next_attempt_at": "2026-11-03T10:40:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/ledger/events": { "get": { "operationId": "list_ledger_events", "tags": [ "ledger" ], "summary": "Read the signed event feed", "description": "The append-only feed of signed ledger events (item publications and retractions, reviews, attestations and project\nevents) used to synchronise self-hosted nodes with the hosted platform. Events are immutable and content-addressed;\ntake the union to merge. Pass `next_cursor` as `since` to continue; an empty `since` starts from the beginning.\nOrder events are served only to their participants.\n", "x-scopes": [], "x-rate-limit": "read", "x-idempotent": false, "x-mcp": false, "x-cli": "ledger pull", "parameters": [ { "name": "since", "in": "query", "description": "Opaque cursor returned as `next_cursor` by the previous call.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "kind", "in": "query", "description": "Only these event kinds (comma separated), for example `block.publish,review`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 20 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } } ], "responses": { "200": { "description": "Events in ledger order.", "headers": { "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEventPage" }, "examples": { "default": { "value": { "data": [ { "id": "3c6e1f0b9a7d42885e1c0a9f3b2d4e6a8c0b1d3f5a7c9e2b4d6f8a0c1e3b5d79", "body": { "kind": "block.publish", "author": "rb1Qm3pX0vN8cT2yJ4kL6hD9sA1fG5wE7uB3iZ0oR2tY", "data": { "name": "Invoice extractor", "kind": "skill", "summary": "Extracts vendor totals and line items from PDF invoices.", "url": "https://github.com/acme/invoice-extractor", "capabilities": [ "document-parsing" ], "license": "MIT", "price_usd": 0, "version": "1.4.0" }, "lamport": 1042, "parents": [ "8a1d0c7e5b3f9a2d4c6e8b0a1d3f5c7e9b2a4d6f8c0e1a3b5d7f9c2e4a6b8d01" ], "ts": 1793700000 }, "sig": "4Z8mQeV1xJr0Sk9TnC3bHdW5yLfA7uPoGi2EtRaN6vXcM1sKjDq8YhBlOw0UzFg3ItPe5CnSvHrA9dJk2LmQxT4bWy7NuE1ZoGf6RiCa" } ], "next_cursor": "lamport-1042", "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "post_ledger_events", "tags": [ "ledger" ], "summary": "Push signed events", "description": "Submits events from a peer node. Each event is verified (hash, Ed25519 signature) and folded independently:\ninvalid or unauthorised events are reported in `rejected` and never block the rest, and already known events count\nas `duplicates`. At most 500 events and 3 MiB per request.\n", "security": [ { "bearerAuth": [ "items:write" ] } ], "x-scopes": [ "items:write" ], "x-rate-limit": "write", "x-idempotent": true, "x-mcp": false, "x-cli": "ledger push", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEventsPush" }, "examples": { "default": { "value": { "events": [ { "id": "3c6e1f0b9a7d42885e1c0a9f3b2d4e6a8c0b1d3f5a7c9e2b4d6f8a0c1e3b5d79", "body": { "kind": "block.publish", "author": "rb1Qm3pX0vN8cT2yJ4kL6hD9sA1fG5wE7uB3iZ0oR2tY", "data": { "name": "Invoice extractor", "kind": "skill", "summary": "Extracts vendor totals and line items from PDF invoices.", "url": "https://github.com/acme/invoice-extractor", "capabilities": [ "document-parsing" ], "license": "MIT", "price_usd": 0, "version": "1.4.0" }, "lamport": 1042, "parents": [ "8a1d0c7e5b3f9a2d4c6e8b0a1d3f5c7e9b2a4d6f8c0e1a3b5d7f9c2e4a6b8d01" ], "ts": 1793700000 }, "sig": "4Z8mQeV1xJr0Sk9TnC3bHdW5yLfA7uPoGi2EtRaN6vXcM1sKjDq8YhBlOw0UzFg3ItPe5CnSvHrA9dJk2LmQxT4bWy7NuE1ZoGf6RiCa" } ] } } } } } }, "responses": { "200": { "description": "Result per batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerPushResult" }, "examples": { "default": { "value": { "added": 1, "duplicates": 0, "rejected": [ { "id": "0b7a2f4c6e8d1a3b5c7d9e0f2a4b6c8d1e3f5a7b9c0d2e4f6a8b1c3d5e7f9a0b", "code": "invalid_signature", "message": "Signature does not match the author key." } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "item.published": { "post": { "operationId": "on_item_published", "tags": [ "webhooks" ], "summary": "item.published", "description": "A public item became available (first public version published or a draft made active).", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublishedEvent" }, "examples": { "default": { "value": { "id": "evt_itempubl2222", "object": "event", "type": "item.published", "api_version": "1", "created_at": "2026-10-28T09:10:03Z", "account": "acme", "data": { "object": { "id": "itm_invoiceextr2", "object": "item", "owner": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "slug": "invoice-extractor", "full_name": "acme/invoice-extractor", "kind": "skill", "title": "Invoice extractor", "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.", "visibility": "public", "status": "active", "license": "MIT", "pricing_model": "free", "price_cents": 0, "currency": "USD", "source": { "provider": "github", "url": "https://github.com/acme/invoice-extractor", "ref": "acme/invoice-extractor" }, "homepage_url": "https://acme.example/invoice-extractor", "html_url": "https://reuseforge.com/app/acme/invoice-extractor", "capabilities": [ "document-parsing", "data-analysis" ], "tags": [ "pdf", "invoices", "ocr" ], "latest_version": "1.4.0", "verification": { "state": "passed", "version": "1.4.0", "tests_pass_rate": 0.97, "verified_at": "2026-10-28T09:12:40Z" }, "stats": { "stars": 412, "downloads": 9120, "reviews": 18, "sales": 0 }, "signals": { "stars": 1860, "downloads": 9120, "tests_pass_rate": 0.97, "forks": 143, "open_issues": 12, "days_since_update": 6 }, "rating": 4.6, "rating_count": 18, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-03-02T14:05:11Z", "updated_at": "2026-10-28T09:10:02Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "item.version.published": { "post": { "operationId": "on_item_version_published", "tags": [ "webhooks" ], "summary": "item.version.published", "description": "A new immutable version of an item was published.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemVersionPublishedEvent" }, "examples": { "default": { "value": { "id": "evt_versionpub22", "object": "event", "type": "item.version.published", "api_version": "1", "created_at": "2026-10-28T09:10:02Z", "account": "acme", "data": { "object": { "id": "ver_xinvoice2345", "object": "item_version", "item": "acme/invoice-extractor", "item_id": "itm_invoiceextr2", "version": "1.4.0", "changelog": "Adds multi-currency totals and a --strict mode.", "content_hash": "sha256:ea91565182d4a3fde4c71e4bc8ba34dd057a9717707652e8916f7559500f6c8c", "size_bytes": 48213, "file_count": 3, "dependencies": [ { "item": "acme/pdf-text-layer", "range": "^2.0.0" } ], "yanked": false, "yanked_reason": null, "prerelease": false, "archive_sha256": "a3c0f5bd09a1d7b4e2f8c61d9b7e45a0c1f3d2e8b6a49f7c05d1e3b28a6c4f90", "manifest": null, "created_by": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "created_at": "2026-10-28T09:10:02Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "item.updated": { "post": { "operationId": "on_item_updated", "tags": [ "webhooks" ], "summary": "item.updated", "description": "Item metadata or price changed, or a version was yanked or restored. data.previous_attributes lists the old values of changed top-level fields.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemUpdatedEvent" }, "examples": { "default": { "value": { "id": "evt_itemupdated2", "object": "event", "type": "item.updated", "api_version": "1", "created_at": "2026-10-28T09:10:02Z", "account": "acme", "data": { "object": { "id": "itm_invoiceextr2", "object": "item", "owner": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "slug": "invoice-extractor", "full_name": "acme/invoice-extractor", "kind": "skill", "title": "Invoice extractor", "summary": "Extracts vendor, totals and line items from PDF invoices into JSON using layout-aware OCR.", "visibility": "public", "status": "active", "license": "MIT", "pricing_model": "free", "price_cents": 0, "currency": "USD", "source": { "provider": "github", "url": "https://github.com/acme/invoice-extractor", "ref": "acme/invoice-extractor" }, "homepage_url": "https://acme.example/invoice-extractor", "html_url": "https://reuseforge.com/app/acme/invoice-extractor", "capabilities": [ "document-parsing", "data-analysis" ], "tags": [ "pdf", "invoices", "ocr" ], "latest_version": "1.4.0", "verification": { "state": "passed", "version": "1.4.0", "tests_pass_rate": 0.97, "verified_at": "2026-10-28T09:12:40Z" }, "stats": { "stars": 412, "downloads": 9120, "reviews": 18, "sales": 0 }, "signals": { "stars": 1860, "downloads": 9120, "tests_pass_rate": 0.97, "forks": 143, "open_issues": 12, "days_since_update": 6 }, "rating": 4.6, "rating_count": 18, "demo": false, "forked_from": null, "project_id": null, "created_at": "2026-03-02T14:05:11Z", "updated_at": "2026-10-28T09:10:02Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "review.created": { "post": { "operationId": "on_review_created", "tags": [ "webhooks" ], "summary": "review.created", "description": "A verified buyer reviewed an item you own.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCreatedEvent" }, "examples": { "default": { "value": { "id": "evt_reviewcreat2", "object": "event", "type": "review.created", "api_version": "1", "created_at": "2026-11-02T18:20:00Z", "account": "acme", "data": { "object": { "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" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "order.created": { "post": { "operationId": "on_order_created", "tags": [ "webhooks" ], "summary": "order.created", "description": "An order containing your items (as seller) or created by you (as buyer) was quoted.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreatedEvent" }, "examples": { "default": { "value": { "id": "evt_ordercreate2", "object": "event", "type": "order.created", "api_version": "1", "created_at": "2026-11-03T10:05:00Z", "account": "acme", "data": { "object": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "awaiting_payment", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "awaiting_payment", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000", "tx_ref": null, "confirmations": 0, "required_confirmations": 3, "expires_at": "2026-11-03T11:05:00Z", "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": null, "settled_at": null, "payouts": [], "next_actions": [ { "type": "send_payment", "description": "Transfer 12.00 USDC on Base Sepolia to the escrow contract, then call pay_order with the transaction hash.", "chain_id": 84532, "to": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "data": null, "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000" } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:05:00Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "order.funded": { "post": { "operationId": "on_order_funded", "tags": [ "webhooks" ], "summary": "order.funded", "description": "Escrow for the order was confirmed on the rail. Sellers should deliver now.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderFundedEvent" }, "examples": { "default": { "value": { "id": "evt_orderfunded2", "object": "event", "type": "order.funded", "api_version": "1", "created_at": "2026-11-03T10:07:12Z", "account": "acme", "data": { "object": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "pending", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": null, "deliver_by": null, "accept_by": null, "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:07:12Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "order.delivered": { "post": { "operationId": "on_order_delivered", "tags": [ "webhooks" ], "summary": "order.delivered", "description": "Every item of the order was delivered and the acceptance window started.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDeliveredEvent" }, "examples": { "default": { "value": { "id": "evt_orderdeliver", "object": "event", "type": "order.delivered", "api_version": "1", "created_at": "2026-11-03T10:08:30Z", "account": "acme", "data": { "object": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "delivered", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [ { "type": "review_delivery", "description": "Test the delivered item, then call accept_order to release payment or dispute_order before 2026-11-10T10:08:30Z." } ], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:08:30Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "order.released": { "post": { "operationId": "on_order_released", "tags": [ "webhooks" ], "summary": "order.released", "description": "Escrow was released to the sellers (accepted, window expired or resolved in the seller's favour).", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderReleasedEvent" }, "examples": { "default": { "value": { "id": "evt_orderrelease", "object": "event", "type": "order.released", "api_version": "1", "created_at": "2026-11-03T11:20:45Z", "account": "acme", "data": { "object": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "released", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": null, "resolution": null, "release_reason": "accepted" } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-03T11:20:45Z", "payouts": [ { "id": "pyo_sellerpay222", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "seller", "recipient": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "address": "0xA11cE0000000000000000000000000000000b0b2", "rail": "base-usdc", "amount_cents": 1188, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null }, { "id": "pyo_platformfee2", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "platform_fee", "recipient": null, "address": "0xFee0000000000000000000000000000000000001", "rail": "base-usdc", "amount_cents": 12, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T11:21:10Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "order.refunded": { "post": { "operationId": "on_order_refunded", "tags": [ "webhooks" ], "summary": "order.refunded", "description": "One or more items were refunded to the buyer.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRefundedEvent" }, "examples": { "default": { "value": { "id": "evt_orderrefunde", "object": "event", "type": "order.refunded", "api_version": "1", "created_at": "2026-11-10T10:09:00Z", "account": "acme", "data": { "object": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "settled", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "refunded", "price_cents": 1200, "fee_cents": 0, "seller_amount_cents": 0, "project_id": null, "delivery": null, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": null, "dispute": null, "resolution": { "seller_bps": 0, "refund_cents": 1200, "note": "Seller did not deliver before the deadline.", "resolved_at": "2026-11-10T10:09:00Z" }, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 0, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": "2026-11-10T10:09:00Z", "payouts": [ { "id": "pyo_buyerrefun22", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "refund", "recipient": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "rail": "base-usdc", "amount_cents": 1200, "currency": "USD", "state": "sent", "tx_ref": "0x4c1d9e7b2a6f08d35e9a1b7c4d2e6f80a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2", "sent_at": "2026-11-10T10:10:30Z", "project_id": null } ], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-10T10:10:30Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "order.disputed": { "post": { "operationId": "on_order_disputed", "tags": [ "webhooks" ], "summary": "order.disputed", "description": "The buyer disputed delivered items and escrow is frozen until an arbiter decides.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDisputedEvent" }, "examples": { "default": { "value": { "id": "evt_orderdispute", "object": "event", "type": "order.disputed", "api_version": "1", "created_at": "2026-11-03T10:40:00Z", "account": "acme", "data": { "object": { "id": "ord_tqjv5mw3k2na", "object": "order", "state": "funded", "buyer": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "items": [ { "item_id": "itm_ragharness22", "item": "janedoe/invoice-rag-harness", "title": "Invoice RAG harness", "version": "0.9.2", "seller": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "disputed", "price_cents": 1200, "fee_cents": 12, "seller_amount_cents": 1188, "project_id": null, "delivery": { "delivered_at": "2026-11-03T10:08:30Z", "access": { "type": "item_version", "version": "0.9.2" }, "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c" }, "deliver_by": "2026-11-10T10:08:00Z", "accept_by": "2026-11-10T10:08:30Z", "dispute": { "reason": "The harness crashes on startup with the documented config (KeyError: embedder).", "opened_at": "2026-11-03T10:40:00Z" }, "resolution": null, "release_reason": null } ], "subtotal_cents": 1200, "fee_bps": 100, "fee_cents": 12, "total_cents": 1200, "currency": "USD", "payment": { "rail": "base-usdc", "network": "base-sepolia", "asset": "USDC", "status": "confirmed", "amount_cents": 1200, "amount_atomic": "12000000", "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2", "memo": null, "uri": null, "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b", "confirmations": 3, "required_confirmations": 3, "expires_at": null, "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7", "simulated": false }, "plan_id": "pln_goalinvoice2", "accept_window_seconds": 604800, "deliver_window_seconds": 604800, "funded_at": "2026-11-03T10:07:12Z", "settled_at": null, "payouts": [], "next_actions": [], "created_at": "2026-11-03T10:05:00Z", "updated_at": "2026-11-03T10:40:00Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "project.funded": { "post": { "operationId": "on_project_funded", "tags": [ "webhooks" ], "summary": "project.funded", "description": "A crowdfunded project reached its goal and moved to funded.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFundedEvent" }, "examples": { "default": { "value": { "id": "evt_projfunded22", "object": "event", "type": "project.funded", "api_version": "1", "created_at": "2026-10-18T13:45:00Z", "account": "acme", "data": { "object": { "id": "prj_reconharnes2", "object": "project", "title": "Invoice reconciliation harness", "spec": "A harness that matches supplier invoices to purchase orders and flags mismatches, shipped as a reusable skill.", "deliverables": [ "reconciliation harness", "evaluation set" ], "proposer": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "state": "funded", "goal_cents": 500000, "raised_cents": 500000, "pending_cents": 0, "progress": 1.0, "currency": "USD", "created_at": "2026-10-05T08:00:00Z", "deadline_at": "2026-11-04T08:00:00Z", "funded_at": "2026-10-18T13:45:00Z", "developers": [ { "account": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "budget_bps": 10000, "equity_bps": 2000 } ], "milestones": [ { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 1, "name": "Reconciliation engine", "bps": 4000, "amount_cents": 200000, "state": "submitted", "evidence": "https://github.com/janedoe/invoice-recon/pull/9", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-11-02T12:00:00Z", "decided_at": null, "submissions": 1, "votes": { "approve_weight": 100000, "reject_weight": 0, "total_weight": 500000 } }, { "index": 2, "name": "Dashboard and docs", "bps": 3000, "amount_cents": 150000, "state": "pending", "evidence": null, "submitted_by": null, "submitted_at": null, "decided_at": null, "submissions": 0, "votes": { "approve_weight": 0, "reject_weight": 0, "total_weight": 500000 } } ], "cap_table": [ { "holder": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "units": 200000000000, "ownership_bps": 2000 }, { "holder": { "id": "acc_samdevuser22", "type": "user", "handle": "samdev", "display_name": "Sam Okafor", "verified": false, "avatar_url": "" }, "units": 480000000000, "ownership_bps": 4800 }, { "holder": { "id": "acc_acmelabsorg2", "type": "org", "handle": "acme", "display_name": "Acme Labs", "verified": true, "avatar_url": "" }, "units": 320000000000, "ownership_bps": 3200 } ], "total_units": 1000000000000, "dividends_cents": 0, "product": null, "share_token": null } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "payout.sent": { "post": { "operationId": "on_payout_sent", "tags": [ "webhooks" ], "summary": "payout.sent", "description": "A seller payout, platform fee, refund or revenue-share payout was sent.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutSentEvent" }, "examples": { "default": { "value": { "id": "evt_payoutsent22", "object": "event", "type": "payout.sent", "api_version": "1", "created_at": "2026-11-03T11:21:10Z", "account": "acme", "data": { "object": { "id": "pyo_sellerpay222", "object": "payout", "order_id": "ord_tqjv5mw3k2na", "item_id": "itm_ragharness22", "kind": "seller", "recipient": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "address": "0xA11cE0000000000000000000000000000000b0b2", "rail": "base-usdc", "amount_cents": 1188, "currency": "USD", "state": "sent", "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4", "sent_at": "2026-11-03T11:21:10Z", "project_id": null } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "verification.completed": { "post": { "operationId": "on_verification_completed", "tags": [ "webhooks" ], "summary": "verification.completed", "description": "A verification run finished (passed, failed or errored).", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationCompletedEvent" }, "examples": { "default": { "value": { "id": "evt_verifdone222", "object": "event", "type": "verification.completed", "api_version": "1", "created_at": "2026-10-28T09:12:40Z", "account": "acme", "data": { "object": { "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" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "item.retracted": { "post": { "operationId": "on_item_retracted", "tags": [ "webhooks" ], "summary": "item.retracted", "description": "A public item was retracted by its owner or a moderator and removed from search.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemRetractedEvent" }, "examples": { "default": { "value": { "id": "evt_itemretract2", "object": "event", "type": "item.retracted", "api_version": "1", "created_at": "2026-11-03T12:00:00Z", "account": "acme", "data": { "object": { "id": "itm_invoiceextr2", "object": "item", "full_name": "acme/invoice-extractor", "status": "retracted", "retracted_at": "2026-11-03T12:00:00Z" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "project.milestone.approved": { "post": { "operationId": "on_project_milestone_approved", "tags": [ "webhooks" ], "summary": "project.milestone.approved", "description": "A milestone was approved by the backers and its share of the goal was credited to the developers.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectMilestoneApprovedEvent" }, "examples": { "default": { "value": { "id": "evt_milestoneapp", "object": "event", "type": "project.milestone.approved", "api_version": "1", "created_at": "2026-10-21T15:30:00Z", "account": "janedoe", "data": { "object": { "index": 0, "name": "Ingestion pipeline", "bps": 3000, "amount_cents": 150000, "state": "approved", "evidence": "https://github.com/janedoe/invoice-recon/pull/4", "submitted_by": { "id": "acc_janedoeuser2", "type": "user", "handle": "janedoe", "display_name": "Jane Doe", "verified": false, "avatar_url": "https://avatars.githubusercontent.com/u/1000001" }, "submitted_at": "2026-10-20T09:00:00Z", "decided_at": "2026-10-21T15:30:00Z", "submissions": 1, "votes": { "approve_weight": 400000, "reject_weight": 0, "total_weight": 500000 } }, "project_id": "prj_reconharnes2" } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } }, "ping": { "post": { "operationId": "on_ping", "tags": [ "webhooks" ], "summary": "ping", "description": "Sent by test_webhook and once after a webhook is created. Not a subscribable event type.", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookDeliveryIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingEvent" }, "examples": { "default": { "value": { "id": "evt_pingevent222", "object": "event", "type": "ping", "api_version": "1", "created_at": "2026-11-03T10:31:00Z", "account": "acme", "data": { "object": { "object": "ping", "webhook_id": "whk_ordersandpub", "message": "Hello from ReuseForge" } } } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAck" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "rf_ personal access token", "description": "Personal access token created with `create_token` or in the web app: `Authorization: Bearer rf_...`.\nThe scopes a token holds decide which operations succeed (see `x-scope-catalog` and each operation's `x-scopes`;\nwhen several are listed, all are required). Public reads work without a token.\n" } }, "parameters": { "Cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page's `next_cursor`.", "schema": { "type": "string", "maxLength": 512 } }, "Limit": { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!-~]{1,255}$" } }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required here because the call moves or commits money. Same semantics as the optional header; omitting it returns 400 `idempotency_key_required`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!-~]{1,255}$" } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "The ETag of the representation you are changing. Mismatch returns 412, omission returns 428.", "schema": { "type": "string", "maxLength": 128 } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "description": "ETag from an earlier response; a match returns 304 without a body.", "schema": { "type": "string", "maxLength": 128 } }, "Owner": { "name": "owner", "in": "path", "required": true, "description": "Handle of the owning user or organization.", "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$" }, "example": "acme" }, "Slug": { "name": "slug", "in": "path", "required": true, "description": "Item slug, unique per owner.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" }, "example": "invoice-extractor" }, "Handle": { "name": "handle", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$" }, "example": "acme" }, "ArchiveLayout": { "name": "layout", "in": "query", "description": "`plain` (default): the published files as they are. `claude-plugin`: a Claude Code plugin wrapping a `skill`, `prompt` or `mcp_server` item.", "schema": { "type": "string", "enum": [ "plain", "claude-plugin" ], "default": "plain" } }, "VersionPath": { "name": "version", "in": "path", "required": true, "description": "An exact semantic version or `latest`.", "schema": { "type": "string", "pattern": "^(latest|[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?)$" }, "example": "1.4.0" }, "VerificationId": { "name": "verification_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vrf_[a-z0-9]{8,40}$" } }, "PlanId": { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pln_[a-z0-9]{8,40}$" }, "example": "pln_goalinvoice2" }, "OrderId": { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[a-z0-9]{8,40}$" }, "example": "ord_tqjv5mw3k2na" }, "OrderItemId": { "name": "item_id", "in": "path", "required": true, "description": "The item id (`itm_...`) of a line in the order.", "schema": { "type": "string", "pattern": "^itm_[a-z0-9]{8,40}$" }, "example": "itm_ragharness22" }, "ProjectId": { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_[a-z0-9]{8,40}$" }, "example": "prj_reconharnes2" }, "BackingId": { "name": "backing_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^bck_[a-z0-9]{8,40}$" } }, "MilestoneIndex": { "name": "index", "in": "path", "required": true, "description": "Zero-based milestone index.", "schema": { "type": "integer", "minimum": 0, "maximum": 31 } }, "TokenId": { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tok_[a-z0-9]{8,40}$" } }, "WebhookId": { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[a-z0-9]{8,40}$" } }, "DeliveryId": { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whd_[a-z0-9]{8,40}$" } }, "WebhookSignature": { "name": "ReuseForge-Signature", "in": "header", "required": true, "description": "`t=,v1=` (a second `v1` appears while a secret rotation overlaps). The MAC covers the string `.` and is keyed with the webhook secret. Reject timestamps more than 5 minutes from your clock.", "schema": { "type": "string", "maxLength": 300 }, "example": "t=1793700012,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, "WebhookEventIdHeader": { "name": "ReuseForge-Event-Id", "in": "header", "required": true, "description": "The `evt_` id. Constant across retries; use it for deduplication.", "schema": { "type": "string", "pattern": "^evt_[a-z0-9]{8,40}$" } }, "WebhookDeliveryIdHeader": { "name": "ReuseForge-Delivery-Id", "in": "header", "required": true, "description": "The `whd_` id of this delivery attempt.", "schema": { "type": "string", "pattern": "^whd_[a-z0-9]{8,40}$" } } }, "headers": { "XRequestId": { "description": "Unique id of this request. Quote it in support requests; it equals `request_id` in problem bodies.", "schema": { "type": "string", "pattern": "^req_[a-z0-9]{12,32}$" } }, "ApiVersion": { "description": "Full contract version that served the request.", "schema": { "type": "string", "example": "1.1.0" } }, "RateLimitLimit": { "description": "Requests allowed in the current window of the tier that applied.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window resets (delta seconds, per the IETF RateLimit header draft).", "schema": { "type": "integer" } }, "RateLimitPolicy": { "description": "Tier policy as `;w=`, for example `600;w=60`.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying. Sent with 429 and 503.", "schema": { "type": "integer", "minimum": 0 } }, "ETag": { "description": "Strong validator of the representation. Send it back as `If-None-Match` or `If-Match`.", "schema": { "type": "string" } }, "XContentSha256": { "description": "Lower-case hex SHA-256 of the response body. Pin it (Claude Code `archive` sources take it as `sha256`).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "ContentDisposition": { "description": "`attachment; filename=\"-.zip\"` for the `plain` layout and `-.claude-plugin.zip` for `claude-plugin` (plus `filename*` for non-ASCII).", "schema": { "type": "string" } }, "ContentLength": { "description": "Exact size of the body in bytes.", "schema": { "type": "integer", "minimum": 0 } }, "Link": { "description": "RFC 8288 pagination links, for example `; rel=\"next\"`. Present when `has_more` is true.", "schema": { "type": "string" } }, "Location": { "description": "Canonical URL of the created resource.", "schema": { "type": "string", "format": "uri-reference" } }, "IdempotentReplayed": { "description": "`true` when the response is a stored replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "Deprecation": { "description": "Present on deprecated operations: `@` of the deprecation date (RFC 9745).", "schema": { "type": "string" } }, "Sunset": { "description": "Present on deprecated operations: HTTP-date after which the operation may stop working (RFC 8594).", "schema": { "type": "string" } } }, "responses": { "WebhookAck": { "description": "Return any 2xx within 10 seconds to acknowledge. Anything else (or a timeout) schedules a retry. The body is ignored beyond a 1 KiB excerpt kept for debugging." }, "BadRequest": { "description": "The request is malformed (bad JSON, unknown or mistyped parameter, invalid cursor).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemInvalidParameter" } } } } }, "Unauthorized": { "description": "Missing, malformed, expired or revoked credentials.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "WWW-Authenticate": { "description": "Always `Bearer realm=\"reuseforge\"`.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemUnauthorized" } } } } }, "PaymentRequired": { "description": "The item is paid and the caller is not entitled. `order_hint` says exactly what to order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemPaymentRequired" } } } } }, "Forbidden": { "description": "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).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope": { "$ref": "#/components/examples/ProblemInsufficientScope" }, "spend": { "$ref": "#/components/examples/ProblemSpendLimit" } } } } }, "NotFound": { "description": "No such resource, or it is private and the caller may not know it exists.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemNotFound" } } } } }, "Conflict": { "description": "The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemConflict" } } } } }, "Gone": { "description": "The resource existed and is permanently unavailable (retracted item, expired plan).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemGone" } } } } }, "PreconditionFailed": { "description": "`If-Match` does not match the current ETag. `current_etag` carries the new one; re-read, merge, retry.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemPreconditionFailed" } } } } }, "PreconditionRequired": { "description": "The operation requires `If-Match`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemPreconditionRequired" } } } } }, "PayloadTooLarge": { "description": "The body or a file exceeds a limit published in `get_api_index`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemTooLarge" } } } } }, "Unprocessable": { "description": "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`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemValidation" } } } } }, "TooManyRequests": { "description": "Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemRateLimited" } } } } }, "InternalError": { "description": "Unexpected failure on our side. Safe to retry idempotent calls; quote `request_id` if it persists.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemInternal" } } } } }, "BadGateway": { "description": "An upstream source (connector, chain RPC) failed or timed out. Retry with backoff.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemUpstream" } } } } }, "ServiceUnavailable": { "description": "Temporarily unable to serve (maintenance or a dependency is down). Honour `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "default": { "$ref": "#/components/examples/ProblemUnavailable" } } } } } }, "examples": { "ProblemInvalidParameter": { "summary": "Invalid query parameter", "value": { "type": "https://reuseforge.com/docs/api/errors/invalid_parameter", "title": "Invalid parameter", "status": 400, "detail": "limit must be between 1 and 100.", "instance": "/api/v1/items", "code": "invalid_parameter", "request_id": "req_8f2k1m9x4q7z", "errors": [ { "pointer": "#/limit", "code": "out_of_range", "message": "must be between 1 and 100" } ] } }, "ProblemUnauthorized": { "summary": "Bad token", "value": { "type": "https://reuseforge.com/docs/api/errors/invalid_token", "title": "Invalid token", "status": 401, "detail": "The API token is invalid, expired or revoked.", "instance": "/api/v1/me", "code": "invalid_token", "request_id": "req_p3x9v1c7b2n4" } }, "ProblemPaymentRequired": { "summary": "Paid item without entitlement", "value": { "type": "https://reuseforge.com/docs/api/errors/payment_required", "title": "Payment required", "status": 402, "detail": "janedoe/invoice-rag-harness costs $12.00. Create and fund an order to unlock it.", "instance": "/api/v1/items/janedoe/invoice-rag-harness/install", "code": "payment_required", "request_id": "req_t6m2k8d4h1q9", "order_hint": { "reason": "item_not_purchased", "total_cents": 1200, "currency": "USD", "items": [ { "item": "janedoe/invoice-rag-harness", "item_id": "itm_ragharness22", "version": "0.9.2", "price_cents": 1200 } ], "create_order": { "method": "POST", "href": "/api/v1/orders", "body": { "items": [ { "item": "janedoe/invoice-rag-harness", "version": "0.9.2" } ] } } } } }, "ProblemInsufficientScope": { "summary": "Token lacks a scope", "value": { "type": "https://reuseforge.com/docs/api/errors/insufficient_scope", "title": "Insufficient scope", "status": 403, "detail": "This token cannot release escrow. It needs the orders:accept scope.", "instance": "/api/v1/orders/ord_tqjv5mw3k2na/accept", "code": "insufficient_scope", "request_id": "req_c4v8n2m6x1z3", "required_scopes": [ "orders:accept" ] } }, "ProblemSpendLimit": { "summary": "Token spend limit reached", "value": { "type": "https://reuseforge.com/docs/api/errors/spend_limit_exceeded", "title": "Spend limit exceeded", "status": 403, "detail": "Paying 12.00 USD would exceed this token's spend limit (5000 cents, 4900 already spent).", "instance": "/api/v1/orders/ord_tqjv5mw3k2na/pay", "code": "spend_limit_exceeded", "request_id": "req_k9j3h7g5f1d2" } }, "ProblemNotFound": { "summary": "Unknown item", "value": { "type": "https://reuseforge.com/docs/api/errors/not_found", "title": "Not found", "status": 404, "detail": "No item named acme/does-not-exist.", "instance": "/api/v1/items/acme/does-not-exist", "code": "not_found", "request_id": "req_8f2k1m9x4q7z" } }, "ProblemConflict": { "summary": "Duplicate", "value": { "type": "https://reuseforge.com/docs/api/errors/already_exists", "title": "Already exists", "status": 409, "detail": "Version 1.4.0 of acme/invoice-extractor already exists. Versions are immutable.", "instance": "/api/v1/items/acme/invoice-extractor/versions", "code": "already_exists", "request_id": "req_w2e4r6t8y1u3" } }, "ProblemGone": { "summary": "Expired plan", "value": { "type": "https://reuseforge.com/docs/api/errors/plan_expired", "title": "Plan expired", "status": 410, "detail": "Plans are kept for 24 hours. Plan the goal again.", "instance": "/api/v1/plans/pln_goalinvoice2", "code": "plan_expired", "request_id": "req_q1a2z3x4c5v6" } }, "ProblemPreconditionFailed": { "summary": "Stale ETag", "value": { "type": "https://reuseforge.com/docs/api/errors/precondition_failed", "title": "Precondition failed", "status": 412, "detail": "The item changed since you read it.", "instance": "/api/v1/items/acme/invoice-extractor", "code": "precondition_failed", "request_id": "req_l5k4j3h2g1f9", "current_etag": "\"7c1a9e04b2d85f36\"" } }, "ProblemPreconditionRequired": { "summary": "Missing If-Match", "value": { "type": "https://reuseforge.com/docs/api/errors/precondition_required", "title": "Precondition required", "status": 428, "detail": "Send the item's ETag in If-Match.", "instance": "/api/v1/items/acme/invoice-extractor", "code": "precondition_required", "request_id": "req_m8n7b6v5c4x2" } }, "ProblemTooLarge": { "summary": "Version too large", "value": { "type": "https://reuseforge.com/docs/api/errors/payload_too_large", "title": "Payload too large", "status": 413, "detail": "A version may contain at most 2097152 bytes of files (got 3401220).", "instance": "/api/v1/items/acme/invoice-extractor/versions", "code": "payload_too_large", "request_id": "req_d3f5g7h9j1k2" } }, "ProblemValidation": { "summary": "Field errors", "value": { "type": "https://reuseforge.com/docs/api/errors/validation_failed", "title": "Validation failed", "status": 422, "detail": "2 fields are invalid.", "instance": "/api/v1/items", "code": "validation_failed", "request_id": "req_z8x7c6v5b4n3", "errors": [ { "pointer": "#/slug", "code": "invalid_format", "message": "must match ^[a-z0-9][a-z0-9._-]{0,63}$" }, { "pointer": "#/price_cents", "code": "out_of_range", "message": "must be between 0 and 100000" } ] } }, "ProblemRateLimited": { "summary": "Rate limited", "value": { "type": "https://reuseforge.com/docs/api/errors/rate_limited", "title": "Rate limit exceeded", "status": 429, "detail": "You exceeded 20 requests per minute in the plan tier.", "instance": "/api/v1/plans", "code": "rate_limited", "request_id": "req_s1d2f3g4h5j6", "retry_after": 33 } }, "ProblemInternal": { "summary": "Server error", "value": { "type": "https://reuseforge.com/docs/api/errors/internal", "title": "Internal error", "status": 500, "detail": "Something went wrong on our side.", "instance": "/api/v1/items", "code": "internal", "request_id": "req_u7y6t5r4e3w2" } }, "ProblemUpstream": { "summary": "Upstream failure", "value": { "type": "https://reuseforge.com/docs/api/errors/upstream_error", "title": "Upstream error", "status": 502, "detail": "Base RPC did not answer; the transaction could not be verified yet.", "instance": "/api/v1/orders/ord_tqjv5mw3k2na/pay", "code": "upstream_error", "request_id": "req_o9i8u7y6t5r4", "retry_after": 5 } }, "ProblemUnavailable": { "summary": "Maintenance", "value": { "type": "https://reuseforge.com/docs/api/errors/unavailable", "title": "Service unavailable", "status": 503, "detail": "The database is unreachable.", "instance": "/api/v1/health", "code": "unavailable", "request_id": "req_a1s2d3f4g5h6", "retry_after": 30 } } }, "schemas": { "ErrorCode": { "type": "string", "description": "Stable, machine-readable error identifiers. New codes may be added in minor releases; branch on `code`, never on `title` or `detail`.", "enum": [ "invalid_request", "invalid_json", "invalid_parameter", "invalid_cursor", "validation_failed", "unsupported_media_type", "payload_too_large", "unauthorized", "invalid_token", "token_expired", "insufficient_scope", "forbidden", "account_suspended", "email_unverified", "spend_limit_exceeded", "purchase_required", "payment_required", "payment_invalid", "rail_unsupported", "not_found", "method_not_allowed", "gone", "plan_expired", "conflict", "already_exists", "invalid_state", "idempotency_key_required", "idempotency_key_reuse", "idempotency_in_progress", "precondition_failed", "precondition_required", "quota_exceeded", "version_quarantined", "review_removed", "rate_limited", "webhook_url_forbidden", "invalid_signature", "integrity_mismatch", "upstream_error", "upstream_timeout", "not_implemented", "internal", "unavailable" ] }, "FieldError": { "type": "object", "required": [ "pointer", "code", "message" ], "properties": { "pointer": { "type": "string", "description": "JSON Pointer fragment of the offending field in the request body (`#/slug`) or the query parameter name (`#/limit`)." }, "code": { "type": "string", "description": "Short reason such as `required`, `invalid_format`, `out_of_range`, `too_long`, `unknown_field`, `not_allowed`." }, "message": { "type": "string" } } }, "OrderHint": { "type": "object", "description": "Machine-actionable instructions that turn a 402 into a purchase.", "required": [ "reason", "total_cents", "currency", "items", "create_order" ], "properties": { "reason": { "type": "string", "enum": [ "item_not_purchased", "order_not_funded", "order_refunded" ] }, "total_cents": { "type": "integer", "minimum": 0 }, "currency": { "$ref": "#/components/schemas/Currency" }, "items": { "type": "array", "items": { "type": "object", "required": [ "item", "item_id", "price_cents" ], "properties": { "item": { "$ref": "#/components/schemas/ItemRef" }, "item_id": { "type": "string" }, "version": { "type": "string" }, "price_cents": { "type": "integer", "minimum": 0 } } } }, "order_id": { "type": [ "string", "null" ], "description": "Existing unpaid order that would unlock the item, if any." }, "create_order": { "type": "object", "required": [ "method", "href", "body" ], "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "href": { "type": "string" }, "body": { "type": "object" } } } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details, served as `application/problem+json`. Extension members depend on `code`.", "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "type": "string", "format": "uri-reference", "description": "Documentation URL for the error: `https://reuseforge.com/docs/api/errors/`." }, "title": { "type": "string", "description": "Short summary that is stable per code." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "description": "Human-readable explanation of this occurrence. Do not parse it." }, "instance": { "type": "string", "description": "Path of the request that failed." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "request_id": { "type": "string", "pattern": "^req_[a-z0-9]{12,32}$" }, "errors": { "type": "array", "description": "Per-field problems for `validation_failed`, `invalid_parameter` and `invalid_request`.", "items": { "$ref": "#/components/schemas/FieldError" } }, "retry_after": { "type": "integer", "minimum": 0, "description": "Seconds to wait. Mirrors `Retry-After`. Present for `rate_limited`, `unavailable`, `upstream_error`, `idempotency_in_progress`." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "Present for `insufficient_scope`." }, "order_hint": { "$ref": "#/components/schemas/OrderHint" }, "current_etag": { "type": "string", "description": "Present for `precondition_failed`." }, "state": { "type": "string", "description": "Present for `invalid_state`: the state that blocked the call." }, "limit_cents": { "type": "integer", "description": "Present for `spend_limit_exceeded`: the token's limit." }, "spent_cents": { "type": "integer", "description": "Present for `spend_limit_exceeded`: already spent." } }, "additionalProperties": true }, "Page": { "type": "object", "description": "Cursor page. Every collection endpoint returns this shape (with `data` narrowed to the item type).", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": {} }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page. Null on the last page." }, "has_more": { "type": "boolean" }, "total": { "type": "integer", "minimum": 0, "description": "Total matches when cheap to compute (search). May be an estimate." } } }, "Timestamp": { "type": "string", "format": "date-time" }, "Currency": { "type": "string", "enum": [ "USD" ], "description": "ISO 4217 code. Only USD in v1." }, "ItemRef": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?/[a-z0-9][a-z0-9._-]{0,63}$", "description": "Canonical item address `owner/slug`.", "examples": [ "acme/invoice-extractor" ] }, "ItemKind": { "type": "string", "description": "Kinds that can be published and sold on ReuseForge.", "enum": [ "repo", "skill", "harness", "mcp_server", "model", "dataset", "prompt", "template" ] }, "BlockKind": { "type": "string", "description": "Kinds the planner and connectors can return. Adds external-only kinds (`paper`, `build_task`, `design`) to `ItemKind`.", "enum": [ "repo", "skill", "harness", "mcp_server", "model", "dataset", "prompt", "template", "paper", "build_task", "design" ] }, "ItemSort": { "type": "string", "enum": [ "relevance", "trending", "stars", "downloads", "updated", "newest", "rating", "price_asc", "price_desc" ] }, "InstallTarget": { "type": "string", "description": "Where an item is installed. `generic` extracts into `./reuseforge///`. `mcp-json` produces a `.mcp.json` entry for `mcp_server` items.", "enum": [ "generic", "claude-code", "cursor", "codex", "mcp-json" ] }, "Signals": { "type": "object", "description": "Numeric quality and risk signals shared by hosted items and external candidates. All keys are optional and unknown keys must be tolerated.", "properties": { "stars": { "type": "number" }, "downloads": { "type": "number" }, "citations": { "type": "number" }, "tests_pass_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "forks": { "type": "number" }, "open_issues": { "type": "number" }, "dependents": { "type": "number" }, "vulns_total": { "type": "number" }, "vulns_critical_high": { "type": "number" }, "scorecard": { "type": "number", "minimum": 0, "maximum": 10, "description": "OpenSSF Scorecard aggregate." }, "archived": { "type": "number", "enum": [ 0, 1 ] }, "days_since_update": { "type": "number", "minimum": 0 } }, "additionalProperties": { "type": "number" } }, "ApiIndex": { "type": "object", "required": [ "name", "api_version", "major", "documentation_url", "openapi_url", "links", "auth", "test_mode", "rails", "limits", "deprecations" ], "properties": { "name": { "type": "string" }, "api_version": { "type": "string", "description": "Full contract semver." }, "major": { "type": "string", "enum": [ "v1" ] }, "documentation_url": { "type": "string", "format": "uri" }, "openapi_url": { "type": "string", "format": "uri" }, "links": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Relation name to URL (path or absolute)." }, "auth": { "type": "object", "required": [ "type", "token_prefix" ], "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token_prefix": { "type": "string" }, "scope_catalog_url": { "type": "string", "format": "uri" } } }, "test_mode": { "type": "boolean", "description": "True while payments are simulated or run on test networks." }, "rails": { "type": "array", "items": { "type": "object", "required": [ "id", "enabled", "test_mode" ], "properties": { "id": { "$ref": "#/components/schemas/PaymentRail" }, "network": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "test_mode": { "type": "boolean" } } } }, "limits": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Numeric limits clients should respect (`page_max`, `max_files`, `max_file_bytes`, `max_version_bytes`, `max_request_bytes`, `goal_max_chars`, `plan_ttl_seconds`, `idempotency_ttl_seconds`, `webhook_endpoints_max`, `tokens_max`)." }, "deprecations": { "type": "array", "items": { "type": "object", "required": [ "operation_id", "deprecated_at", "sunset_at" ], "properties": { "operation_id": { "type": "string" }, "deprecated_at": { "$ref": "#/components/schemas/Timestamp" }, "sunset_at": { "$ref": "#/components/schemas/Timestamp" }, "replacement": { "type": [ "string", "null" ] } } } } } }, "Health": { "type": "object", "required": [ "status", "time", "version", "components" ], "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "down" ] }, "time": { "$ref": "#/components/schemas/Timestamp" }, "version": { "type": "string" }, "components": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "ok", "degraded", "down" ] } } } }, "OpenApiDocument": { "type": "object", "required": [ "openapi", "info" ], "properties": { "openapi": { "type": "string" }, "info": { "type": "object" } }, "additionalProperties": true }, "EventTypeInfo": { "type": "object", "required": [ "type", "description", "object" ], "properties": { "type": { "$ref": "#/components/schemas/EventType" }, "description": { "type": "string" }, "object": { "type": "string", "description": "Value of `data.object.object` carried by the event." } } }, "EventTypePage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeInfo" } } } } ] }, "RateLimit": { "type": "object", "required": [ "tier", "limit", "remaining", "reset_seconds", "window_seconds", "policy" ], "properties": { "tier": { "type": "string", "enum": [ "read", "write", "plan", "discover", "payments" ] }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "reset_seconds": { "type": "integer" }, "window_seconds": { "type": "integer" }, "policy": { "type": "string", "examples": [ "600;w=60" ] }, "daily_limit": { "type": "integer" }, "daily_remaining": { "type": "integer" } } }, "RateLimitStatus": { "type": "object", "required": [ "principal", "tiers" ], "properties": { "principal": { "type": "string", "enum": [ "anonymous", "token", "session" ] }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/RateLimit" } } } }, "AccountRef": { "type": "object", "required": [ "id", "type", "handle" ], "properties": { "id": { "type": "string", "pattern": "^acc_[a-z0-9]{8,40}$" }, "type": { "type": "string", "enum": [ "user", "org" ] }, "handle": { "type": "string" }, "display_name": { "type": "string" }, "verified": { "type": "boolean", "description": "Platform-verified badge." }, "avatar_url": { "type": "string", "description": "Empty string means the client draws an identicon." } } }, "Account": { "type": "object", "required": [ "id", "object", "type", "handle", "display_name", "verified", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^acc_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "account" ] }, "type": { "type": "string", "enum": [ "user", "org" ] }, "handle": { "type": "string" }, "display_name": { "type": "string" }, "bio": { "type": "string" }, "avatar_url": { "type": "string" }, "website": { "type": "string" }, "location": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "verified": { "type": "boolean" }, "followers_count": { "type": "integer" }, "following_count": { "type": "integer" }, "stats": { "type": "object", "properties": { "items": { "type": "integer" }, "stars_received": { "type": "integer" } } }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "Me": { "type": "object", "required": [ "id", "object", "type", "handle", "display_name", "email_verified", "role", "auth", "orgs", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^acc_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "account" ] }, "type": { "type": "string", "enum": [ "user" ] }, "handle": { "type": "string" }, "display_name": { "type": "string" }, "avatar_url": { "type": "string" }, "email": { "type": "string", "format": "email" }, "email_verified": { "type": "boolean" }, "role": { "type": "string", "enum": [ "user", "admin" ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "auth": { "type": "object", "required": [ "via", "scopes" ], "properties": { "via": { "type": "string", "enum": [ "token", "session" ] }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "token_id": { "type": [ "string", "null" ] }, "spend_limit_cents": { "type": [ "integer", "null" ] }, "spent_cents": { "type": "integer" } } }, "orgs": { "type": "array", "items": { "type": "object", "required": [ "account", "role" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "role": { "type": "string", "enum": [ "owner", "admin", "write", "read" ] } } } } } }, "Scope": { "type": "string", "enum": [ "items:read", "items:write", "items:publish", "orders:read", "orders:create", "orders:pay", "orders:accept", "projects:read", "projects:write", "webhooks:manage", "tokens:manage", "admin" ] }, "Token": { "type": "object", "required": [ "id", "object", "name", "prefix", "scopes", "spend_limit_cents", "spent_cents", "created_at", "last_used_at", "expires_at" ], "properties": { "id": { "type": "string", "pattern": "^tok_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "token" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "prefix": { "type": "string", "description": "First characters of the secret, safe to show." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "spend_limit_cents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Lifetime cap on money this token may commit through `pay_order` and `back_project`. Null means unlimited." }, "spent_cents": { "type": "integer", "minimum": 0 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TokenWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Token" }, { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^rf_[A-Za-z0-9_-]{30,64}$", "description": "The secret. Shown once." } } } ] }, "TokenCreate": { "type": "object", "additionalProperties": false, "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Scope" } }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Default 90. A token with the `admin` scope defaults to 7 days and lasts at most 30; a longer request answers 422 `validation_failed`." }, "spend_limit_cents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Default 5000 when `orders:pay` is requested (the only scope that can commit money). Null (unlimited) is only honoured for interactive sessions." } } }, "TokenPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Token" } } } } ] }, "Verification": { "type": "object", "required": [ "id", "object", "item", "version", "state", "runner", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^vrf_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "verification" ] }, "item": { "$ref": "#/components/schemas/ItemRef" }, "version": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "passed", "failed", "error" ] }, "runner": { "type": "string", "enum": [ "static-v1", "platform", "community", "seller" ], "description": "`static-v1` is the in-API static checker (no publisher code is executed). `platform`, `community` and `seller` are attested test runs." }, "tests_total": { "type": [ "integer", "null" ], "description": "Test cases attested by the runner; for `static-v1` the number of static checks that ran." }, "tests_passed": { "type": [ "integer", "null" ] }, "tests_pass_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Only set by runners that executed tests. Always `null` for `static-v1`." }, "summary": { "type": [ "string", "null" ] }, "checks": { "type": "array", "description": "Per-check results of a static run (absent for attested runs).", "items": { "type": "object", "required": [ "id", "status", "message" ], "properties": { "id": { "type": "string", "description": "hashes, limits, manifest, license, secrets, binaries, skill, mcp, readme." }, "status": { "type": "string", "enum": [ "pass", "warn", "fail", "skip" ] }, "message": { "type": "string" }, "path": { "type": "string", "description": "The file the finding is about, when there is one." } } } }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "VerificationSummary": { "type": "object", "required": [ "state", "version" ], "properties": { "state": { "type": "string", "enum": [ "queued", "running", "passed", "failed", "error" ] }, "version": { "type": "string" }, "tests_pass_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ItemSource": { "type": "object", "properties": { "provider": { "type": "string", "description": "manual, github, huggingface, mcp-registry, arxiv, npm, pypi." }, "url": { "type": "string" }, "ref": { "type": "string" } } }, "Item": { "type": "object", "required": [ "id", "object", "owner", "slug", "full_name", "kind", "title", "summary", "visibility", "status", "license", "pricing_model", "price_cents", "currency", "capabilities", "tags", "latest_version", "stats", "signals", "rating", "rating_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^itm_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "item" ] }, "owner": { "$ref": "#/components/schemas/AccountRef" }, "slug": { "type": "string" }, "full_name": { "$ref": "#/components/schemas/ItemRef" }, "kind": { "$ref": "#/components/schemas/ItemKind" }, "title": { "type": "string", "maxLength": 120 }, "summary": { "type": "string", "maxLength": 280 }, "readme": { "type": "string", "description": "Markdown. Only returned by `get_item` and `create_item`." }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ] }, "status": { "type": "string", "enum": [ "draft", "active", "archived", "retracted" ] }, "license": { "type": "string", "description": "SPDX identifier, or `Commercial-Single-Project`, `Proprietary`, `UNKNOWN`." }, "pricing_model": { "type": "string", "enum": [ "free", "fixed", "pwyw" ], "description": "For `pwyw` (pay what you want) `price_cents` is the minimum." }, "price_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "currency": { "$ref": "#/components/schemas/Currency" }, "source": { "$ref": "#/components/schemas/ItemSource" }, "homepage_url": { "type": "string" }, "html_url": { "type": "string", "format": "uri" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Planner taxonomy ids." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Same list as `keywords`." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The item's tags (the field Claude Code documents)." }, "latest_version": { "type": [ "string", "null" ] }, "verification": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VerificationSummary" } ] }, "stats": { "type": "object", "required": [ "stars", "downloads", "reviews", "sales" ], "properties": { "stars": { "type": "integer" }, "downloads": { "type": "integer" }, "reviews": { "type": "integer" }, "sales": { "type": "integer" } } }, "signals": { "$ref": "#/components/schemas/Signals" }, "rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5, "description": "Average of verified-buyer ratings, one decimal." }, "rating_count": { "type": "integer" }, "demo": { "type": "boolean", "description": "Seeded demonstration listing." }, "forked_from": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ItemRef" } ] }, "project_id": { "type": [ "string", "null" ], "description": "Crowdfunded project whose unit holders share this item's revenue." }, "viewer": { "type": "object", "description": "Present for signed-in callers on `get_item`.", "properties": { "starred": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "entitled": { "type": "boolean", "description": "True for free items, owners, and buyers with a delivered or released order." } } }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ItemPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] }, "ItemCreate": { "type": "object", "additionalProperties": false, "required": [ "slug", "kind", "title" ], "properties": { "owner": { "type": "string", "description": "Handle of an organization you can write for. Defaults to you." }, "slug": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$", "description": "Lowercase letters, digits, dots, underscores and hyphens; starts and ends with a letter or digit." }, "kind": { "$ref": "#/components/schemas/ItemKind" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "summary": { "type": "string", "maxLength": 280 }, "readme": { "type": "string", "maxLength": 200000 }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ], "default": "public" }, "license": { "type": "string", "maxLength": 64, "default": "UNKNOWN" }, "pricing_model": { "type": "string", "enum": [ "free", "fixed", "pwyw" ], "default": "free" }, "price_cents": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 }, "capabilities": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 64 } }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "homepage_url": { "type": "string", "maxLength": 300 }, "source": { "$ref": "#/components/schemas/ItemSource" }, "forked_from": { "$ref": "#/components/schemas/ItemRef" } } }, "ItemUpdate": { "type": "object", "additionalProperties": false, "description": "JSON Merge Patch style. Omitted fields are unchanged; present fields replace the stored value. `null` is not accepted; send an empty string (empty array for `tags` and `capabilities`) to clear a field.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "summary": { "type": "string", "maxLength": 280 }, "readme": { "type": "string", "maxLength": 200000 }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ] }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "license": { "type": "string", "maxLength": 64 }, "pricing_model": { "type": "string", "enum": [ "free", "fixed", "pwyw" ] }, "price_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "capabilities": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 64 } }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "homepage_url": { "type": "string", "maxLength": 300 }, "source": { "$ref": "#/components/schemas/ItemSource" } } }, "StarState": { "type": "object", "required": [ "item", "starred", "stars_count" ], "properties": { "item": { "$ref": "#/components/schemas/ItemRef" }, "starred": { "type": "boolean" }, "stars_count": { "type": "integer" } } }, "Review": { "type": "object", "required": [ "id", "object", "item", "author", "rating", "title", "body", "verified_purchase", "basis", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^rev_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "review" ] }, "item": { "$ref": "#/components/schemas/ItemRef" }, "author": { "$ref": "#/components/schemas/AccountRef" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "verified_purchase": { "type": "boolean" }, "basis": { "type": "string", "enum": [ "purchase", "install", "none" ], "description": "`none` only appears on reviews written in the web app before verification existed." }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ReviewCreate": { "type": "object", "additionalProperties": false, "required": [ "rating" ], "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string", "maxLength": 120 }, "body": { "type": "string", "maxLength": 4000 } } }, "ReviewPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } } } } ] }, "ItemStats": { "type": "object", "required": [ "item", "totals" ], "properties": { "item": { "$ref": "#/components/schemas/ItemRef" }, "totals": { "type": "object", "required": [ "views", "downloads", "stars", "reviews", "sales" ], "properties": { "views": { "type": "integer" }, "downloads": { "type": "integer" }, "stars": { "type": "integer" }, "reviews": { "type": "integer" }, "sales": { "type": "integer" }, "revenue_cents": { "type": "integer", "description": "Owners and organization admins only; omitted when the payments ledger has no figure for the item." } } }, "days": { "type": "array", "description": "Owners only. One entry per UTC day, oldest first.", "items": { "type": "object", "required": [ "day", "views", "downloads", "stars" ], "properties": { "day": { "type": "string", "format": "date" }, "views": { "type": "integer" }, "downloads": { "type": "integer" }, "stars": { "type": "integer" } } } } } }, "Dependency": { "type": "object", "additionalProperties": false, "required": [ "item", "range" ], "properties": { "item": { "$ref": "#/components/schemas/ItemRef" }, "range": { "type": "string", "maxLength": 64, "description": "Semver range: exact `1.2.3`, `^1.2.0`, `~1.2.0`, `>=1.2.0 <2.0.0` or `*`." } } }, "FileEntry": { "type": "object", "required": [ "path", "size_bytes", "sha256", "content_type", "preview" ], "properties": { "path": { "type": "string" }, "size_bytes": { "type": "integer" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "content_type": { "type": "string" }, "preview": { "type": "boolean", "description": "Visible and downloadable by everyone even when the item is paid." } } }, "FileInput": { "type": "object", "additionalProperties": false, "required": [ "path", "content" ], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Relative path with `/` separators. No leading `/`, no `..` segments, no backslashes or NUL." }, "content": { "type": "string", "description": "UTF-8 text or base64, per `encoding`. At most 512 KiB decoded." }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "default": "utf8" }, "content_type": { "type": "string", "maxLength": 100 }, "preview": { "type": "boolean", "default": false } } }, "ItemVersion": { "type": "object", "required": [ "id", "object", "item", "item_id", "version", "changelog", "content_hash", "size_bytes", "file_count", "dependencies", "yanked", "prerelease", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^ver_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "item_version" ] }, "item": { "$ref": "#/components/schemas/ItemRef" }, "item_id": { "type": "string" }, "version": { "type": "string" }, "changelog": { "type": "string" }, "content_hash": { "$ref": "#/components/schemas/ContentHash" }, "size_bytes": { "type": "integer" }, "file_count": { "type": "integer" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileEntry" }, "description": "Only on `get_version`." }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/Dependency" } }, "yanked": { "type": "boolean" }, "yanked_reason": { "type": [ "string", "null" ] }, "prerelease": { "type": "boolean" }, "archive_sha256": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the `plain` ZIP from `get_version_archive` (the value of its `X-Content-SHA256` header). `null` until the archive has been built once, and always `null` for versions of paid items. The `claude-plugin` layout has its own digest (listed in the marketplace)." }, "manifest": { "type": [ "object", "null" ], "description": "The `reuseforge.json` manifest submitted with the version, if any." }, "verification": { "$ref": "#/components/schemas/Verification" }, "created_by": { "$ref": "#/components/schemas/AccountRef" }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ClaudeMarketplace": { "type": "object", "description": "A Claude Code `marketplace.json` (https://code.claude.com/docs/en/plugins/marketplace-reference). Only fields Claude Code reads are used, so `claude plugin validate` passes without warnings.", "required": [ "name", "owner", "plugins" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$", "maxLength": 128, "description": "`reuseforge-`. Users type it after `@` when they install." }, "description": { "type": "string" }, "owner": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" } } }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/ClaudePluginEntry" } } } }, "ClaudePluginEntry": { "type": "object", "required": [ "name", "source" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$", "maxLength": 128, "description": "The item slug. Equals `name` in the plugin's own `plugin.json`." }, "source": { "type": "object", "description": "Claude Code `archive` plugin source: a ZIP downloaded over HTTPS and verified against `sha256`.", "required": [ "source", "url", "sha256" ], "properties": { "source": { "type": "string", "enum": [ "archive" ] }, "url": { "type": "string", "format": "uri" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "description": { "type": "string" }, "version": { "type": "string" }, "category": { "type": "string", "description": "The item kind (`skill`, `prompt` or `mcp_server`)." }, "tags": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "author": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "homepage": { "type": "string", "format": "uri" }, "license": { "type": "string" } } }, "ContentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "SHA-256 over the text made of one line ` ` per file (two spaces, `\\n` after each line), files sorted by path in UTF-8 byte order. Identical to the output of `sha256sum` over the files, so it can be recomputed with standard tools." }, "ItemVersionPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemVersion" } } } } ] }, "VersionCreate": { "type": "object", "additionalProperties": false, "required": [ "version", "files" ], "properties": { "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" }, "changelog": { "type": "string", "maxLength": 20000 }, "files": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/FileInput" } }, "dependencies": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Dependency" } }, "manifest": { "type": "object", "description": "Contents of `reuseforge.json` (schema: api/schemas/reuseforge.schema.json). Validated and stored." }, "content_hash": { "$ref": "#/components/schemas/ContentHash" } } }, "VersionUpdate": { "type": "object", "additionalProperties": false, "properties": { "changelog": { "type": "string", "maxLength": 20000 }, "yanked": { "type": "boolean" }, "yanked_reason": { "type": [ "string", "null" ], "maxLength": 500 } } }, "Bundle": { "type": "object", "required": [ "item", "version", "content_hash", "files" ], "properties": { "item": { "$ref": "#/components/schemas/ItemRef" }, "version": { "type": "string" }, "content_hash": { "$ref": "#/components/schemas/ContentHash" }, "files": { "type": "array", "items": { "type": "object", "required": [ "path", "content", "encoding", "sha256", "size_bytes" ], "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size_bytes": { "type": "integer" }, "content_type": { "type": "string" } } } } } }, "LockFile": { "type": "object", "required": [ "path", "sha256" ], "properties": { "path": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "LockEntry": { "type": "object", "description": "One package entry of `reuseforge.lock` (full schema in api/schemas/reuseforge.lock.schema.json).", "required": [ "name", "id", "version", "kind", "target", "content_hash", "license", "source", "files" ], "properties": { "name": { "$ref": "#/components/schemas/ItemRef" }, "id": { "type": "string" }, "version": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ItemKind" }, "target": { "$ref": "#/components/schemas/InstallTarget" }, "content_hash": { "$ref": "#/components/schemas/ContentHash" }, "license": { "type": "string" }, "source": { "type": "string", "description": "`reuseforge` or the origin URL of an external block." }, "order_id": { "type": [ "string", "null" ] }, "price_paid_cents": { "type": "integer", "minimum": 0 }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/LockFile" } } } }, "InstallDescriptor": { "type": "object", "required": [ "object", "item", "item_id", "kind", "version", "target", "content_hash", "license", "price_cents", "currency", "entitlement", "bundle_url", "files", "config_patches", "commands", "lock_entry" ], "properties": { "object": { "type": "string", "enum": [ "install_descriptor" ] }, "item": { "$ref": "#/components/schemas/ItemRef" }, "item_id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ItemKind" }, "version": { "type": "string" }, "target": { "$ref": "#/components/schemas/InstallTarget" }, "content_hash": { "$ref": "#/components/schemas/ContentHash" }, "license": { "type": "string" }, "price_cents": { "type": "integer" }, "currency": { "$ref": "#/components/schemas/Currency" }, "entitlement": { "type": "object", "required": [ "required", "granted", "reason" ], "properties": { "required": { "type": "boolean", "description": "True when the item is paid." }, "granted": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "free", "owner", "org_member", "purchased", "not_purchased" ] }, "order_id": { "type": [ "string", "null" ] } } }, "bundle_url": { "type": "string", "format": "uri", "description": "Where to download the file contents (`get_version_bundle`)." }, "files": { "type": "array", "description": "Files to write. `path` is relative to the project root (or to the home directory when it starts with `~/`), `source_path` names the file inside the bundle.", "items": { "type": "object", "required": [ "path", "source_path", "sha256", "size_bytes", "mode" ], "properties": { "path": { "type": "string" }, "source_path": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size_bytes": { "type": "integer" }, "mode": { "type": "string", "pattern": "^0[0-7]{3}$" } } } }, "config_patches": { "type": "array", "description": "Edits to existing config files. `json` and `toml` deep-merge `merge` into the file (existing differing values are never overwritten silently). `markdown_block` upserts `content` between `` markers.", "items": { "type": "object", "required": [ "path", "format" ], "properties": { "path": { "type": "string" }, "format": { "type": "string", "enum": [ "json", "toml", "markdown_block" ] }, "merge": { "type": "object" }, "block_id": { "type": "string" }, "content": { "type": "string" } } } }, "commands": { "type": "array", "description": "Suggested shell commands. Clients show them and never run them unless the user passes an explicit flag.", "items": { "type": "object", "required": [ "description", "command", "run" ], "properties": { "description": { "type": "string" }, "command": { "type": "string" }, "run": { "type": "string", "enum": [ "never", "prompt" ] } } } }, "lock_entry": { "$ref": "#/components/schemas/LockEntry" }, "notes": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "Requirement": { "type": "object", "required": [ "capability", "description", "keywords" ], "properties": { "capability": { "type": "string", "description": "Planner taxonomy id or free kebab-case tag." }, "description": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } } } }, "Candidate": { "type": "object", "description": "A reusable thing the planner can pick: a hosted item or an external result. Same fields as the Python `Block`, with money in cents.", "required": [ "id", "name", "kind", "summary", "url", "license", "price_cents", "currency", "origin", "signals" ], "properties": { "id": { "type": "string", "pattern": "^(itm|blk)_[a-z0-9]{12,24}$", "description": "`itm_...` for hosted items, `blk_...` (stable hash of origin and url) for external results." }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/BlockKind" }, "summary": { "type": "string" }, "url": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "license": { "type": "string" }, "price_cents": { "type": "integer", "minimum": 0 }, "currency": { "$ref": "#/components/schemas/Currency" }, "version": { "type": "string" }, "content_hash": { "type": "string", "description": "Empty for external results; `sha256:` hash for hosted versions." }, "owner": { "type": "string", "description": "Seller handle, or the external owner/organization." }, "origin": { "type": "string", "description": "`reuseforge` (hosted), `network` (peer ledger), `github`, `arxiv`, `mcp-registry`, `huggingface`, `npm`, `pypi`, ... Open set." }, "signals": { "$ref": "#/components/schemas/Signals" }, "rating": { "type": "number", "minimum": 0, "maximum": 5 }, "rating_count": { "type": "integer" }, "project_id": { "type": [ "string", "null" ] }, "item": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ItemRef" } ], "description": "Set when the candidate is a hosted item." }, "quality": { "type": "number", "minimum": 0, "maximum": 1, "description": "Planner estimate from verifiable signals." }, "risk": { "type": "number", "minimum": 0, "maximum": 1 }, "payout_rails": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRail" }, "description": "Rails on which the seller can be paid." } } }, "PlanStep": { "type": "object", "required": [ "requirement", "action", "candidate", "quality", "cost_cents", "risk" ], "properties": { "requirement": { "type": "string" }, "action": { "type": "string", "enum": [ "use", "build" ] }, "candidate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Candidate" } ] }, "quality": { "type": "number", "minimum": 0, "maximum": 1 }, "cost_cents": { "type": "integer", "minimum": 0, "description": "Price of the candidate, or the estimated agent-token cost of building." }, "risk": { "type": "number", "minimum": 0, "maximum": 1 }, "blueprints": { "type": "array", "items": { "type": "object", "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" } } } } } }, "PaidItem": { "type": "object", "required": [ "item", "item_id", "name", "version", "seller", "price_cents" ], "properties": { "item": { "$ref": "#/components/schemas/ItemRef" }, "item_id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "seller": { "type": "string" }, "price_cents": { "type": "integer" }, "project_id": { "type": [ "string", "null" ] } } }, "PlanOption": { "type": "object", "required": [ "index", "objectives", "paid_total_cents", "build_total_cents", "steps", "paid_items" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Position in `pareto_front`." }, "objectives": { "type": "object", "required": [ "quality", "cost_cents", "risk" ], "properties": { "quality": { "type": "number", "minimum": 0, "maximum": 1, "description": "Mean over requirements. Higher is better." }, "cost_cents": { "type": "integer", "minimum": 0, "description": "Paid items (each once) plus estimated build cost. Lower is better." }, "risk": { "type": "number", "minimum": 0, "maximum": 1, "description": "Mean over requirements. Lower is better." } } }, "paid_total_cents": { "type": "integer", "minimum": 0 }, "build_total_cents": { "type": "integer", "minimum": 0 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/PlanStep" } }, "paid_items": { "type": "array", "items": { "$ref": "#/components/schemas/PaidItem" } } } }, "Explanation": { "type": "object", "required": [ "scope", "ref", "kind", "text" ], "properties": { "scope": { "type": "string", "enum": [ "plan", "requirement", "option" ] }, "ref": { "type": "string", "description": "Requirement capability, option index (as string) or `plan`." }, "kind": { "type": "string", "enum": [ "rationale", "tradeoff", "warning" ] }, "text": { "type": "string" } } }, "SourceStatus": { "type": "object", "required": [ "connector", "status", "count" ], "properties": { "connector": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error", "skipped" ] }, "count": { "type": "integer" }, "duration_ms": { "type": "integer" }, "error": { "type": "string" } } }, "Plan": { "type": "object", "required": [ "id", "object", "goal", "budget_cents", "currency", "created_at", "expires_at", "requirements", "pareto_front", "recommended", "recommended_index", "explanations", "sources", "partial" ], "properties": { "id": { "type": "string", "pattern": "^pln_[a-z0-9]{8,40}$", "description": "The `plan_id` used by other operations. Valid 24 hours." }, "object": { "type": "string", "enum": [ "plan" ] }, "goal": { "type": "string" }, "budget_cents": { "type": [ "integer", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/Requirement" } }, "pareto_front": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/PlanOption" } }, "recommended": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanOption" } ] }, "recommended_index": { "type": [ "integer", "null" ] }, "explanations": { "type": "array", "items": { "$ref": "#/components/schemas/Explanation" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceStatus" } }, "note": { "type": [ "string", "null" ], "description": "Set when nothing fits the budget." }, "partial": { "type": "boolean", "description": "True when at least one connector failed." } } }, "PlanRequest": { "type": "object", "additionalProperties": false, "required": [ "goal" ], "properties": { "goal": { "type": "string", "minLength": 3, "maxLength": 4000 }, "budget_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000, "description": "Null or omitted means no budget." }, "online": { "type": "boolean", "default": false, "description": "Also query external connectors." }, "connectors": { "type": "array", "maxItems": 12, "items": { "type": "string" }, "description": "Restrict external discovery." }, "llm": { "type": "boolean", "default": false, "description": "Decompose the goal with an LLM instead of the keyword taxonomy." }, "per_requirement": { "type": "integer", "minimum": 1, "maximum": 8, "default": 4 }, "constraints": { "type": "object", "additionalProperties": false, "properties": { "exclude_paid": { "type": "boolean", "default": false }, "allowed_licenses": { "type": "array", "maxItems": 30, "items": { "type": "string" } }, "max_risk": { "type": "number", "minimum": 0, "maximum": 1 }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKind" } }, "deny_licenses": { "type": "array", "maxItems": 30, "items": { "type": "string" }, "description": "Licence ids to refuse. Case-insensitive; a trailing `*` matches a prefix (`CC-BY-NC*`)." }, "prefer_free": { "type": "boolean", "default": false, "description": "Recommend the best plan without paid items when it scores within 0.10 of the overall best." }, "require_verified": { "type": "boolean", "default": false, "description": "Only reuse blocks from sellers with a verified purchase or a verified badge, and from external sources." }, "max_options_per_requirement": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Overrides `per_requirement` for this plan." } } } } }, "Brief": { "type": "object", "required": [ "plan_id", "option", "brief", "build_steps", "mcp_servers" ], "properties": { "plan_id": { "type": "string" }, "option": { "type": "integer" }, "brief": { "type": "string", "description": "Markdown." }, "build_steps": { "type": "array", "items": { "type": "object", "required": [ "requirement", "budget_cents", "blueprints" ], "properties": { "requirement": { "type": "string" }, "budget_cents": { "type": "integer" }, "blueprints": { "type": "array", "items": { "type": "object", "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" } } } } } } }, "mcp_servers": { "type": "array", "items": { "type": "string" } } } }, "DiscoverResult": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "sources" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceStatus" } } } } ] }, "McpConfig": { "type": "object", "required": [ "mcpServers", "servers", "capabilities" ], "properties": { "mcpServers": { "type": "object", "description": "Drop-in `.mcp.json` content. Key name is camelCase because the file format requires it.", "additionalProperties": { "type": "object" } }, "servers": { "type": "array", "items": { "type": "object", "required": [ "name", "purpose", "oauth", "verified" ], "properties": { "name": { "type": "string" }, "purpose": { "type": "string" }, "oauth": { "type": "boolean" }, "verified": { "type": "boolean", "description": "False when the URL or tool name was not confirmed against the live server." }, "token_env": { "type": [ "string", "null" ] } } } }, "capabilities": { "type": "array", "items": { "type": "string" } } } }, "Connector": { "type": "object", "required": [ "name", "type", "role", "ready", "origin", "description" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "builtin", "rest", "mcp-http", "mcp-stdio" ] }, "role": { "type": "string", "enum": [ "block_source", "agent_server" ] }, "ready": { "type": "boolean" }, "origin": { "type": "string" }, "description": { "type": "string" }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKind" } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "verified": { "type": "boolean" }, "token_env": { "type": [ "string", "null" ] }, "oauth": { "type": "boolean" } } }, "ConnectorPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } } } } ] }, "PaymentRail": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,31}$", "description": "Open set. Known: `simulated`, `base-usdc`, `base-usdt`, `btc`. Python nodes also use `usdc-base` and `usdt-ethereum`." }, "OrderState": { "type": "string", "enum": [ "awaiting_payment", "funded", "settled", "expired", "cancelled" ] }, "OrderItemState": { "type": "string", "enum": [ "pending", "delivered", "released", "disputed", "resolved", "refunded" ] }, "Payment": { "type": "object", "description": "Rail-agnostic payment instructions and status.", "required": [ "rail", "status", "amount_cents", "address" ], "properties": { "rail": { "$ref": "#/components/schemas/PaymentRail" }, "network": { "type": [ "string", "null" ], "description": "Chain or network id, for example `base-sepolia`, `base`, `testnet4`." }, "asset": { "type": "string", "description": "USDC, USDT, BTC or USD (simulated)." }, "status": { "type": "string", "enum": [ "awaiting_payment", "pending_confirmations", "confirmed", "failed", "expired", "refunded" ] }, "amount_cents": { "type": "integer", "minimum": 0 }, "amount_atomic": { "type": "string", "pattern": "^[0-9]+$", "description": "Amount in the asset's smallest unit (token base units or satoshis) as a decimal string." }, "address": { "type": "string", "description": "Escrow contract or deposit address the buyer pays." }, "memo": { "type": [ "string", "null" ], "description": "Reference to include when the rail supports one." }, "uri": { "type": [ "string", "null" ], "description": "Wallet link (EIP-681 `ethereum:` or BIP-21 `bitcoin:`)." }, "tx_ref": { "type": [ "string", "null" ], "description": "Transaction hash or simulated reference that funded the order." }, "confirmations": { "type": "integer", "minimum": 0 }, "required_confirmations": { "type": "integer", "minimum": 0 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the price quote." }, "refund_address": { "type": [ "string", "null" ] }, "simulated": { "type": "boolean", "description": "True when no real funds move." } } }, "NextAction": { "type": "object", "description": "What a client or agent should do next to progress the order.", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "enum": [ "send_payment", "sign_transaction", "review_delivery", "wait" ] }, "description": { "type": "string" }, "chain_id": { "type": "integer" }, "to": { "type": "string" }, "data": { "type": [ "string", "null" ] }, "uri": { "type": "string" } } }, "OrderItem": { "type": "object", "required": [ "item_id", "item", "title", "version", "seller", "state", "price_cents", "fee_cents", "seller_amount_cents" ], "properties": { "item_id": { "type": "string" }, "item": { "$ref": "#/components/schemas/ItemRef" }, "title": { "type": "string" }, "version": { "type": "string" }, "seller": { "$ref": "#/components/schemas/AccountRef" }, "state": { "$ref": "#/components/schemas/OrderItemState" }, "price_cents": { "type": "integer" }, "fee_cents": { "type": "integer", "description": "Platform fee on this item. Zero when refunded." }, "seller_amount_cents": { "type": "integer", "description": "What the seller receives on release (price minus fee)." }, "project_id": { "type": [ "string", "null" ] }, "delivery": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "delivered_at", "access" ], "properties": { "delivered_at": { "$ref": "#/components/schemas/Timestamp" }, "access": { "$ref": "#/components/schemas/DeliveryAccess" }, "content_hash": { "type": [ "string", "null" ] } } } ] }, "deliver_by": { "type": [ "string", "null" ], "format": "date-time" }, "accept_by": { "type": [ "string", "null" ], "format": "date-time", "description": "After this moment silence releases the funds." }, "dispute": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "reason", "opened_at" ], "properties": { "reason": { "type": "string" }, "opened_at": { "$ref": "#/components/schemas/Timestamp" } } } ] }, "resolution": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "seller_bps", "refund_cents", "resolved_at" ], "properties": { "seller_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "refund_cents": { "type": "integer" }, "note": { "type": "string" }, "resolved_at": { "$ref": "#/components/schemas/Timestamp" } } } ] }, "release_reason": { "type": [ "string", "null" ], "enum": [ "accepted", "window_expired", "resolved", null ] } } }, "DeliveryAccess": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "item_version", "url", "message" ] }, "version": { "type": "string", "description": "For `item_version`: the hosted version that is delivered." }, "url": { "type": "string", "format": "uri" }, "note": { "type": "string", "maxLength": 2000 } } }, "PayoutKind": { "type": "string", "enum": [ "seller", "platform_fee", "refund", "revenue_share" ] }, "Payout": { "type": "object", "required": [ "id", "object", "order_id", "kind", "address", "rail", "amount_cents", "currency", "state" ], "properties": { "id": { "type": "string", "pattern": "^pyo_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "payout" ] }, "order_id": { "type": "string" }, "item_id": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/PayoutKind" }, "recipient": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountRef" } ] }, "address": { "type": "string" }, "rail": { "$ref": "#/components/schemas/PaymentRail" }, "amount_cents": { "type": "integer", "minimum": 0 }, "currency": { "$ref": "#/components/schemas/Currency" }, "state": { "type": "string", "enum": [ "pending", "sent", "failed" ] }, "tx_ref": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "project_id": { "type": [ "string", "null" ] } } }, "Order": { "type": "object", "required": [ "id", "object", "state", "buyer", "items", "subtotal_cents", "fee_bps", "fee_cents", "total_cents", "currency", "payment", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^ord_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "order" ] }, "state": { "$ref": "#/components/schemas/OrderState" }, "buyer": { "$ref": "#/components/schemas/AccountRef" }, "items": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "$ref": "#/components/schemas/OrderItem" } }, "subtotal_cents": { "type": "integer", "description": "Sum of item prices." }, "fee_bps": { "type": "integer", "minimum": 0, "maximum": 500, "description": "Platform fee rate snapshotted at creation." }, "fee_cents": { "type": "integer", "description": "Sum of item fees. Deducted from sellers' proceeds, not added to the buyer's price." }, "total_cents": { "type": "integer", "description": "What the buyer pays (equals `subtotal_cents`)." }, "currency": { "$ref": "#/components/schemas/Currency" }, "payment": { "$ref": "#/components/schemas/Payment" }, "plan_id": { "type": [ "string", "null" ] }, "accept_window_seconds": { "type": "integer" }, "deliver_window_seconds": { "type": "integer" }, "funded_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "payouts": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "OrderPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } ] }, "PayoutPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } } } } ] }, "OrderItemInput": { "type": "object", "additionalProperties": false, "required": [ "item" ], "properties": { "item": { "oneOf": [ { "$ref": "#/components/schemas/ItemRef" }, { "type": "string", "pattern": "^itm_[a-z0-9]{8,40}$" } ], "description": "Address `owner/slug` or id." }, "version": { "type": "string", "description": "Exact version to buy. Defaults to the latest at order time." }, "amount_cents": { "type": "integer", "minimum": 0, "description": "Price for `pwyw` items (at least the minimum)." } } }, "OrderCreate": { "type": "object", "additionalProperties": false, "description": "Give either `plan_id` or `items`.", "oneOf": [ { "required": [ "plan_id" ] }, { "required": [ "items" ] } ], "properties": { "plan_id": { "type": "string", "pattern": "^pln_[a-z0-9]{8,40}$" }, "option": { "type": "integer", "minimum": 0, "maximum": 11, "description": "Pareto option to order. Defaults to the plan's recommended option." }, "items": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "$ref": "#/components/schemas/OrderItemInput" } }, "rail": { "$ref": "#/components/schemas/PaymentRail" }, "wallet": { "type": "string", "maxLength": 128, "description": "Buyer wallet address used for fund verification and as the default refund address." }, "refund_address": { "type": "string", "maxLength": 128 }, "accept_window_days": { "type": "number", "minimum": 1, "maximum": 60, "default": 7 }, "deliver_window_days": { "type": "number", "minimum": 0.04, "maximum": 90, "default": 7 } } }, "PayOrder": { "type": "object", "additionalProperties": false, "properties": { "tx_ref": { "type": "string", "maxLength": 128, "description": "Transaction hash. Required on real rails, ignored on `simulated`." } } }, "DeliverOrder": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "item_id", "access" ], "properties": { "item_id": { "type": "string" }, "access": { "$ref": "#/components/schemas/DeliveryAccess" }, "content_hash": { "$ref": "#/components/schemas/ContentHash" } } } } } }, "AcceptOrder": { "type": "object", "additionalProperties": false, "required": [ "confirm" ], "properties": { "confirm": { "type": "boolean", "enum": [ true ], "description": "Must be true. A deliberate speed bump." }, "item_ids": { "type": "array", "items": { "type": "string" }, "description": "Subset to accept. Default is every delivered item." }, "note": { "type": "string", "maxLength": 1000 } } }, "DisputeOrder": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 2000 }, "item_ids": { "type": "array", "items": { "type": "string" } }, "evidence_urls": { "type": "array", "maxItems": 10, "items": { "type": "string", "format": "uri" } } } }, "RefundItem": { "type": "object", "additionalProperties": false, "properties": { "note": { "type": "string", "maxLength": 1000 } } }, "ResolveDispute": { "type": "object", "additionalProperties": false, "required": [ "seller_bps", "note" ], "properties": { "seller_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "note": { "type": "string", "minLength": 3, "maxLength": 2000 } } }, "Earnings": { "type": "object", "required": [ "currency", "in_escrow_cents", "releasable_soon_cents", "available_cents", "paid_out_cents", "fees_paid_cents", "by_rail" ], "properties": { "currency": { "$ref": "#/components/schemas/Currency" }, "in_escrow_cents": { "type": "integer" }, "releasable_soon_cents": { "type": "integer", "description": "Delivered items whose acceptance window ends within 48 hours." }, "available_cents": { "type": "integer", "description": "Released but not yet claimed on rails that need a claim." }, "paid_out_cents": { "type": "integer" }, "fees_paid_cents": { "type": "integer" }, "by_rail": { "type": "array", "items": { "type": "object", "required": [ "rail", "paid_out_cents" ], "properties": { "rail": { "$ref": "#/components/schemas/PaymentRail" }, "paid_out_cents": { "type": "integer" } } } } } }, "ProjectState": { "type": "string", "enum": [ "open", "funded", "completed", "failed", "aborted" ] }, "Developer": { "type": "object", "required": [ "account", "budget_bps", "equity_bps" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "budget_bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Share of each milestone payment. All developers total 10000." }, "equity_bps": { "type": "integer", "minimum": 0, "maximum": 5000, "description": "Share of revenue units. All developers total at most 5000." } } }, "Milestone": { "type": "object", "required": [ "index", "name", "bps", "amount_cents", "state", "votes" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amount_cents": { "type": "integer" }, "state": { "type": "string", "enum": [ "pending", "submitted", "approved", "rejected" ] }, "evidence": { "type": [ "string", "null" ] }, "submitted_by": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountRef" } ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "submissions": { "type": "integer", "description": "Number of times it was submitted (at most 3)." }, "votes": { "type": "object", "description": "Weights are pledge amounts in cents, so transferring units cannot double-count a vote.", "required": [ "approve_weight", "reject_weight", "total_weight" ], "properties": { "approve_weight": { "type": "integer" }, "reject_weight": { "type": "integer" }, "total_weight": { "type": "integer" } } } } }, "Project": { "type": "object", "required": [ "id", "object", "title", "spec", "deliverables", "proposer", "state", "goal_cents", "raised_cents", "progress", "currency", "created_at", "deadline_at", "developers", "milestones", "cap_table", "total_units" ], "properties": { "id": { "type": "string", "pattern": "^prj_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "project" ] }, "title": { "type": "string" }, "spec": { "type": "string" }, "deliverables": { "type": "array", "items": { "type": "string" } }, "proposer": { "$ref": "#/components/schemas/AccountRef" }, "state": { "$ref": "#/components/schemas/ProjectState" }, "goal_cents": { "type": "integer" }, "raised_cents": { "type": "integer" }, "pending_cents": { "type": "integer", "description": "Pledges awaiting confirmation." }, "progress": { "type": "number", "minimum": 0, "maximum": 1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "deadline_at": { "$ref": "#/components/schemas/Timestamp" }, "funded_at": { "type": [ "string", "null" ], "format": "date-time" }, "developers": { "type": "array", "items": { "$ref": "#/components/schemas/Developer" } }, "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/Milestone" } }, "cap_table": { "type": "array", "items": { "type": "object", "required": [ "holder", "units", "ownership_bps" ], "properties": { "holder": { "$ref": "#/components/schemas/AccountRef" }, "units": { "type": "integer", "minimum": 0 }, "ownership_bps": { "type": "integer", "minimum": 0, "maximum": 10000 } } } }, "total_units": { "type": "integer", "description": "Fixed supply of revenue units." }, "dividends_cents": { "type": "integer", "description": "Revenue distributed to unit holders so far." }, "product": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ItemRef" } ] }, "share_token": { "type": [ "object", "null" ], "description": "On-chain revenue-share token when the EVM rail is used.", "properties": { "chain": { "type": "string" }, "address": { "type": "string" } } } } }, "ProjectPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } ] }, "ProjectCreate": { "type": "object", "additionalProperties": false, "required": [ "title", "deliverables", "goal_cents", "developers", "milestones" ], "properties": { "title": { "type": "string", "minLength": 3, "maxLength": 200 }, "spec": { "type": "string", "maxLength": 4000 }, "deliverables": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "maxLength": 200 } }, "goal_cents": { "type": "integer", "minimum": 1000, "maximum": 100000000 }, "deadline_days": { "type": "number", "minimum": 1, "maximum": 180, "default": 30 }, "developers": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "account", "budget_bps", "equity_bps" ], "properties": { "account": { "type": "string", "description": "Handle or account id of the developer." }, "budget_bps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "equity_bps": { "type": "integer", "minimum": 0, "maximum": 5000 } } } }, "milestones": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "bps" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000 } } } } } }, "Backing": { "type": "object", "required": [ "id", "object", "project_id", "backer", "amount_cents", "currency", "state", "payment", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^bck_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "backing" ] }, "project_id": { "type": "string" }, "backer": { "$ref": "#/components/schemas/AccountRef" }, "amount_cents": { "type": "integer" }, "currency": { "$ref": "#/components/schemas/Currency" }, "state": { "type": "string", "enum": [ "pending", "confirmed", "withdrawn", "refunded" ] }, "units": { "type": [ "integer", "null" ], "description": "Revenue units allotted for this pledge." }, "payment": { "$ref": "#/components/schemas/Payment" }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "BackProject": { "type": "object", "additionalProperties": false, "required": [ "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "minimum": 100 }, "rail": { "$ref": "#/components/schemas/PaymentRail" }, "tx_ref": { "type": "string", "maxLength": 128 }, "wallet": { "type": "string", "maxLength": 128 } } }, "DeliverMilestone": { "type": "object", "additionalProperties": false, "required": [ "evidence" ], "properties": { "evidence": { "type": "string", "minLength": 3, "maxLength": 500 } } }, "VoteMilestone": { "type": "object", "additionalProperties": false, "required": [ "approve" ], "properties": { "approve": { "type": "boolean" } } }, "VoteAbort": { "type": "object", "additionalProperties": false, "required": [ "abort" ], "properties": { "abort": { "type": "boolean" } } }, "TransferUnits": { "type": "object", "additionalProperties": false, "required": [ "to", "units" ], "properties": { "to": { "type": "string", "description": "Handle or account id of the recipient." }, "units": { "type": "integer", "minimum": 1 } } }, "AttachProduct": { "type": "object", "additionalProperties": false, "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/ItemRef" } } }, "Portfolio": { "type": "object", "required": [ "holder", "currency", "invested_cents", "dividends_cents", "net_cents", "positions" ], "properties": { "holder": { "$ref": "#/components/schemas/AccountRef" }, "currency": { "$ref": "#/components/schemas/Currency" }, "invested_cents": { "type": "integer" }, "dividends_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "positions": { "type": "array", "items": { "type": "object", "required": [ "project_id", "title", "state", "invested_cents", "units", "ownership_bps", "dividends_cents", "net_cents" ], "properties": { "project_id": { "type": "string" }, "title": { "type": "string" }, "state": { "$ref": "#/components/schemas/ProjectState" }, "invested_cents": { "type": "integer" }, "units": { "type": "integer" }, "ownership_bps": { "type": "integer" }, "dividends_cents": { "type": "integer" }, "net_cents": { "type": "integer" } } } } } }, "EventType": { "type": "string", "enum": [ "item.published", "item.version.published", "item.updated", "item.retracted", "review.created", "order.created", "order.funded", "order.delivered", "order.released", "order.refunded", "order.disputed", "project.funded", "project.milestone.approved", "payout.sent", "verification.completed" ] }, "Webhook": { "type": "object", "required": [ "id", "object", "url", "events", "status", "api_version", "consecutive_failures", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^whk_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "events": { "type": "array", "description": "Subscribed event types, or `[\"*\"]` for every type.", "items": { "oneOf": [ { "$ref": "#/components/schemas/EventType" }, { "type": "string", "enum": [ "*" ] } ] } }, "account": { "type": "string", "description": "Handle of the account whose events are delivered." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "manual", "consecutive_failures", "ssrf_blocked", null ] }, "api_version": { "type": "string", "description": "Payload version. Fixed at creation." }, "consecutive_failures": { "type": "integer" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9]{32}$", "description": "Signing secret. Shown once." }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set after rotation: until then deliveries carry two signatures." } } } ] }, "WebhookCreate": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "description": { "type": "string", "maxLength": 200 }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "oneOf": [ { "$ref": "#/components/schemas/EventType" }, { "type": "string", "enum": [ "*" ] } ] } }, "account": { "type": "string", "description": "Organization handle you administer. Defaults to you." } } }, "WebhookUpdate": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "description": { "type": "string", "maxLength": 200 }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "oneOf": [ { "$ref": "#/components/schemas/EventType" }, { "type": "string", "enum": [ "*" ] } ] } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "WebhookPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } ] }, "WebhookDelivery": { "type": "object", "required": [ "id", "object", "webhook_id", "event_id", "event_type", "attempt", "state", "scheduled_at" ], "properties": { "id": { "type": "string", "pattern": "^whd_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "webhook_id": { "type": "string" }, "event_id": { "type": "string", "pattern": "^evt_[a-z0-9]{8,40}$" }, "event_type": { "type": "string" }, "attempt": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "pending", "retrying", "succeeded", "failed", "exhausted" ] }, "scheduled_at": { "$ref": "#/components/schemas/Timestamp" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_status": { "type": [ "integer", "null" ] }, "response_ms": { "type": [ "integer", "null" ] }, "response_excerpt": { "type": [ "string", "null" ], "maxLength": 1024 }, "error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookDeliveryPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] }, "EventBase": { "type": "object", "description": "Envelope of every webhook delivery. The signed raw body is exactly this JSON.", "required": [ "id", "object", "type", "api_version", "created_at", "account", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[a-z0-9]{8,40}$" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string" }, "api_version": { "type": "string", "enum": [ "1" ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "account": { "type": "string", "description": "Handle of the account the delivery is for." }, "data": { "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object" }, "previous_attributes": { "type": "object", "description": "Old values of changed top-level fields (`item.updated`)." }, "truncated": { "type": "boolean", "description": "`true` when the body would exceed 256 KiB and was shrunk: heavy fields of `object` (readme, files, manifest, cap table,\nmilestones, payouts) are dropped, and as a last step `object` is only `{object, id}`. Fetch the resource by id.\n" } } } } }, "ItemPublishedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "item.published" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Item" } } } } } ] }, "ItemVersionPublishedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "item.version.published" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ItemVersion" } } } } } ] }, "ItemUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "item.updated" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Item" } } } } } ] }, "ItemRetractedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "item.retracted" }, "data": { "type": "object", "properties": { "object": { "type": "object", "required": [ "id", "object", "full_name", "status", "retracted_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "item" ] }, "full_name": { "$ref": "#/components/schemas/ItemRef" }, "status": { "type": "string", "enum": [ "retracted" ] }, "retracted_at": { "$ref": "#/components/schemas/Timestamp" } } } } } } } ] }, "ReviewCreatedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "review.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Review" } } } } } ] }, "OrderCreatedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "order.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Order" } } } } } ] }, "OrderFundedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "order.funded" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Order" } } } } } ] }, "OrderDeliveredEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "order.delivered" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Order" } } } } } ] }, "OrderReleasedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "order.released" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Order" } } } } } ] }, "OrderRefundedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "order.refunded" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Order" } } } } } ] }, "OrderDisputedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "order.disputed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Order" } } } } } ] }, "ProjectFundedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "project.funded" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Project" } } } } } ] }, "ProjectMilestoneApprovedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "project.milestone.approved" }, "data": { "type": "object", "required": [ "object", "project_id" ], "properties": { "object": { "$ref": "#/components/schemas/Milestone" }, "project_id": { "type": "string" } } } } } ] }, "PayoutSentEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "payout.sent" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Payout" } } } } } ] }, "VerificationCompletedEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "verification.completed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Verification" } } } } } ] }, "PingEvent": { "allOf": [ { "$ref": "#/components/schemas/EventBase" }, { "type": "object", "properties": { "type": { "const": "ping" }, "data": { "type": "object", "properties": { "object": { "type": "object", "required": [ "object", "webhook_id" ], "properties": { "object": { "type": "string", "enum": [ "ping" ] }, "webhook_id": { "type": "string" }, "message": { "type": "string" } } } } } } } ] }, "LedgerEvent": { "type": "object", "description": "A signed, content-addressed ledger event (Ed25519). `id` is the SHA-256 of the canonical JSON of `{body, sig}`. Field formats follow the Python reference implementation (`repoblock/ledger.py`), including its `price_usd` decimals inside `body.data`: ledger payloads are not part of the money convention.", "required": [ "id", "body", "sig" ], "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "body": { "type": "object", "required": [ "kind", "author", "data", "lamport", "parents", "ts" ], "properties": { "kind": { "type": "string", "description": "For example `block.publish`, `block.retract`, `block.attest`, `review`, `project.create`." }, "author": { "type": "string", "description": "Public id `rb1` of the signing identity." }, "data": { "type": "object" }, "lamport": { "type": "integer", "minimum": 1 }, "parents": { "type": "array", "items": { "type": "string" } }, "ts": { "type": "integer", "description": "Unix seconds." } } }, "sig": { "type": "string", "description": "base64url Ed25519 signature over the canonical JSON of `body`." } } }, "LedgerEventPage": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEvent" } } } } ] }, "LedgerEventsPush": { "type": "object", "additionalProperties": false, "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/LedgerEvent" } } } }, "LedgerPushResult": { "type": "object", "required": [ "added", "duplicates", "rejected" ], "properties": { "added": { "type": "integer" }, "duplicates": { "type": "integer" }, "rejected": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "message" ], "properties": { "id": { "type": "string" }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" } } } } } } } } }