API

Schemas

Every named schema of the ReuseForge API v1 contract with field names, types and which fields are required.

Every named schema of the contract, 132 in all. Field names are the wire names; there is no case conversion in any SDK. Fields marked no may be absent. Clients must ignore fields and enum values they do not know.

Schemas AcceptOrder to EventType

AcceptOrder

Fields of AcceptOrder
Field	Type	Required	Description
`confirm`	`boolean: true`	yes	Must be true. A deliberate speed bump.
`item_ids`	array of `string`	no	Subset to accept. Default is every delivered item.
`note`	`string`	no

Account

Fields of Account
Field	Type	Required
`id`	`string`	yes
`object`	`string: account`	yes
`type`	`string: user, org`	yes
`handle`	`string`	yes
`display_name`	`string`	yes
`bio`	`string`	no
`avatar_url`	`string`	no
`website`	`string`	no
`location`	`string`	no
`links`	map of `string`	no
`verified`	`boolean`	yes
`followers_count`	`integer`	no
`following_count`	`integer`	no
`stats`	`object`	no
`stats.items`	`integer`	no
`stats.stars_received`	`integer`	no
`created_at`	`Timestamp`	yes

AccountRef

Fields of AccountRef
Field	Type	Required	Description
`id`	`string`	yes
`type`	`string: user, org`	yes
`handle`	`string`	yes
`display_name`	`string`	no
`verified`	`boolean`	no	Platform-verified badge.
`avatar_url`	`string`	no	Empty string means the client draws an identicon.

ApiIndex

Fields of ApiIndex
Field	Type	Required	Description
`name`	`string`	yes
`api_version`	`string`	yes	Full contract semver.
`major`	`string: v1`	yes
`documentation_url`	`string (uri)`	yes
`openapi_url`	`string (uri)`	yes
`links`	map of `string`	yes	Relation name to URL (path or absolute).
`auth`	`object`	yes
`auth.type`	`string: bearer`	yes
`auth.token_prefix`	`string`	yes
`auth.scope_catalog_url`	`string (uri)`	no
`test_mode`	`boolean`	yes	True while payments are simulated or run on test networks.
`rails`	array of `object`	yes
`rails[].id`	`PaymentRail`	yes	Open set. Known: `simulated`, `base-usdc`, `base-usdt`, `btc`. Python nodes also use `usdc-base` and `usdt-ethereum`.
`rails[].network`	`string` or `null`	no
`rails[].enabled`	`boolean`	yes
`rails[].test_mode`	`boolean`	yes
`limits`	map of `integer`	yes	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`	array of `object`	yes
`deprecations[].operation_id`	`string`	yes
`deprecations[].deprecated_at`	`Timestamp`	yes
`deprecations[].sunset_at`	`Timestamp`	yes
`deprecations[].replacement`	`string` or `null`	no

AttachProduct

Fields of AttachProduct
Field	Type	Required	Description
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.

BackProject

Fields of BackProject
Field	Type	Required	Description
`amount_cents`	`integer`	yes
`rail`	`PaymentRail`	no	Open set. Known: `simulated`, `base-usdc`, `base-usdt`, `btc`. Python nodes also use `usdc-base` and `usdt-ethereum`.
`tx_ref`	`string`	no
`wallet`	`string`	no

Backing

Fields of Backing
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: backing`	yes
`project_id`	`string`	yes
`backer`	`AccountRef`	yes
`amount_cents`	`integer`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`state`	`string: pending, confirmed, withdrawn, refunded`	yes
`units`	`integer` or `null`	no	Revenue units allotted for this pledge.
`payment`	`Payment`	yes	Rail-agnostic payment instructions and status.
`created_at`	`Timestamp`	yes

BlockKind

Kinds the planner and connectors can return. Adds external-only kinds (paper, build_task, design) to ItemKind.

One of: repo, skill, harness, mcp_server, model, dataset, prompt, template, paper, build_task, design

Brief

Fields of Brief
Field	Type	Required	Description
`plan_id`	`string`	yes
`option`	`integer`	yes
`brief`	`string`	yes	Markdown.
`build_steps`	array of `object`	yes
`build_steps[].requirement`	`string`	yes
`build_steps[].budget_cents`	`integer`	yes
`build_steps[].blueprints`	array of `object`	yes
`mcp_servers`	array of `string`	yes

Bundle

Fields of Bundle
Field	Type	Required	Description
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`version`	`string`	yes
`content_hash`	`ContentHash`	yes	SHA-256 over the text made of one line `<sha256 of file bytes> <path>` 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.
`files`	array of `object`	yes
`files[].path`	`string`	yes
`files[].content`	`string`	yes
`files[].encoding`	`string: utf8, base64`	yes
`files[].sha256`	`string`	yes
`files[].size_bytes`	`integer`	yes
`files[].content_type`	`string`	no

Candidate

A reusable thing the planner can pick: a hosted item or an external result. Same fields as the Python Block, with money in cents.

Fields of Candidate
Field	Type	Required	Description
`id`	`string`	yes	`itm_...` for hosted items, `blk_...` (stable hash of origin and url) for external results.
`name`	`string`	yes
`kind`	`BlockKind`	yes	Kinds the planner and connectors can return. Adds external-only kinds (`paper`, `build_task`, `design`) to `ItemKind`.
`summary`	`string`	yes
`url`	`string`	yes
`capabilities`	array of `string`	no
`license`	`string`	yes
`price_cents`	`integer`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`version`	`string`	no
`content_hash`	`string`	no	Empty for external results; `sha256:` hash for hosted versions.
`owner`	`string`	no	Seller handle, or the external owner/organization.
`origin`	`string`	yes	`reuseforge` (hosted), `network` (peer ledger), `github`, `arxiv`, `mcp-registry`, `huggingface`, `npm`, `pypi`, ... Open set.
`signals`	`Signals`	yes	Numeric quality and risk signals shared by hosted items and external candidates. All keys are optional and unknown keys must be tolerated.
`rating`	`number`	no
`rating_count`	`integer`	no
`project_id`	`string` or `null`	no
`item`	`null` or `ItemRef`	no	Set when the candidate is a hosted item.
`quality`	`number`	no	Planner estimate from verifiable signals.
`risk`	`number`	no
`payout_rails`	array of `PaymentRail`	no	Rails on which the seller can be paid.

ClaudeMarketplace

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.

Fields of ClaudeMarketplace
Field	Type	Required	Description
`name`	`string`	yes	`reuseforge-<owner>`. Users type it after `@` when they install.
`description`	`string`	no
`owner`	`object`	yes
`owner.name`	`string`	yes
`owner.url`	`string (uri)`	no
`plugins`	array of `ClaudePluginEntry`	yes

ClaudePluginEntry

Fields of ClaudePluginEntry
Field	Type	Required	Description
`name`	`string`	yes	The item slug. Equals `name` in the plugin's own `plugin.json`.
`source`	`object`	yes	Claude Code `archive` plugin source: a ZIP downloaded over HTTPS and verified against `sha256`.
`source.source`	`string: archive`	yes
`source.url`	`string (uri)`	yes
`source.sha256`	`string`	yes
`description`	`string`	no
`version`	`string`	no
`category`	`string`	no	The item kind (`skill`, `prompt` or `mcp_server`).
`tags`	array of `string`	no
`keywords`	array of `string`	no
`author`	`object`	no
`author.name`	`string`	yes
`author.url`	`string (uri)`	no
`homepage`	`string (uri)`	no
`license`	`string`	no

Connector

Fields of Connector
Field	Type	Required
`name`	`string`	yes
`type`	`string: builtin, rest, mcp-http, mcp-stdio`	yes
`role`	`string: block_source, agent_server`	yes
`ready`	`boolean`	yes
`origin`	`string`	yes
`description`	`string`	yes
`kinds`	array of `BlockKind`	no
`capabilities`	array of `string`	no
`verified`	`boolean`	no
`token_env`	`string` or `null`	no
`oauth`	`boolean`	no

ConnectorPage

Fields of ConnectorPage
Field	Type	Required	Description
`data`	array of `Connector`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

ContentHash

SHA-256 over the text made of one line <sha256 of file bytes> <path> 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.

Type: string

Currency

ISO 4217 code. Only USD in v1.

One of: USD

DeliverMilestone

Fields of DeliverMilestone
Field	Type	Required	Description
`evidence`	`string`	yes

DeliverOrder

Fields of DeliverOrder
Field	Type	Required	Description
`items`	array of `object`	yes
`items[].item_id`	`string`	yes
`items[].access`	`DeliveryAccess`	yes
`items[].content_hash`	`ContentHash`	no	SHA-256 over the text made of one line `<sha256 of file bytes> <path>` 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.

DeliveryAccess

Fields of DeliveryAccess
Field	Type	Required	Description
`type`	`string: item_version, url, message`	yes
`version`	`string`	no	For `item_version`: the hosted version that is delivered.
`url`	`string (uri)`	no
`note`	`string`	no

Dependency

Fields of Dependency
Field	Type	Required	Description
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`range`	`string`	yes	Semver range: exact `1.2.3`, `^1.2.0`, `~1.2.0`, `>=1.2.0 <2.0.0` or `*`.

Developer

Fields of Developer
Field	Type	Required	Description
`account`	`AccountRef`	yes
`budget_bps`	`integer`	yes	Share of each milestone payment. All developers total 10000.
`equity_bps`	`integer`	yes	Share of revenue units. All developers total at most 5000.

DiscoverResult

Fields of DiscoverResult
Field	Type	Required	Description
`data`	array of `Candidate`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.
`sources`	array of `SourceStatus`	yes

DisputeOrder

Fields of DisputeOrder
Field	Type	Required
`reason`	`string`	yes
`item_ids`	array of `string`	no
`evidence_urls`	array of `string (uri)`	no

Earnings

Fields of Earnings
Field	Type	Required	Description
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`in_escrow_cents`	`integer`	yes
`releasable_soon_cents`	`integer`	yes	Delivered items whose acceptance window ends within 48 hours.
`available_cents`	`integer`	yes	Released but not yet claimed on rails that need a claim.
`paid_out_cents`	`integer`	yes
`fees_paid_cents`	`integer`	yes
`by_rail`	array of `object`	yes
`by_rail[].rail`	`PaymentRail`	yes	Open set. Known: `simulated`, `base-usdc`, `base-usdt`, `btc`. Python nodes also use `usdc-base` and `usdt-ethereum`.
`by_rail[].paid_out_cents`	`integer`	yes

ErrorCode

Stable, machine-readable error identifiers. New codes may be added in minor releases; branch on code, never on title or detail.

One of: 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

EventBase

Envelope of every webhook delivery. The signed raw body is exactly this JSON.

Fields of EventBase
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`string`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`object`	yes
`data.previous_attributes`	`object`	no	Old values of changed top-level fields (`item.updated`).
`data.truncated`	`boolean`	no	`true` when the body would exceed 256 KiB and was shrunk: heavy fields of `object` (readme, files, manifest, cap table, milestones, payouts) are dropped, and as a last step `object` is only `{object, id}`. Fetch the resource by id.

EventType

One of: 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

Schemas EventTypeInfo to LedgerPushResult

EventTypeInfo

Fields of EventTypeInfo
Field	Type	Required	Description
`type`	`EventType`	yes
`description`	`string`	yes
`object`	`string`	yes	Value of `data.object.object` carried by the event.

EventTypePage

Fields of EventTypePage
Field	Type	Required	Description
`data`	array of `EventTypeInfo`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

Explanation

Fields of Explanation
Field	Type	Required	Description
`scope`	`string: plan, requirement, option`	yes
`ref`	`string`	yes	Requirement capability, option index (as string) or `plan`.
`kind`	`string: rationale, tradeoff, warning`	yes
`text`	`string`	yes

FieldError

Fields of FieldError
Field	Type	Required	Description
`pointer`	`string`	yes	JSON Pointer fragment of the offending field in the request body (`#/slug`) or the query parameter name (`#/limit`).
`code`	`string`	yes	Short reason such as `required`, `invalid_format`, `out_of_range`, `too_long`, `unknown_field`, `not_allowed`.
`message`	`string`	yes

FileEntry

Fields of FileEntry
Field	Type	Required	Description
`path`	`string`	yes
`size_bytes`	`integer`	yes
`sha256`	`string`	yes
`content_type`	`string`	yes
`preview`	`boolean`	yes	Visible and downloadable by everyone even when the item is paid.

FileInput

Fields of FileInput
Field	Type	Required	Description
`path`	`string`	yes	Relative path with `/` separators. No leading `/`, no `..` segments, no backslashes or NUL.
`content`	`string`	yes	UTF-8 text or base64, per `encoding`. At most 512 KiB decoded.
`encoding`	`string: utf8, base64`	no	Default `"utf8"`.
`content_type`	`string`	no
`preview`	`boolean`	no	Default `false`.

Health

Fields of Health
Field	Type	Required
`status`	`string: ok, degraded, down`	yes
`time`	`Timestamp`	yes
`version`	`string`	yes
`components`	map of `string: ok, degraded, down`	yes

InstallDescriptor

Fields of InstallDescriptor
Field	Type	Required	Description
`object`	`string: install_descriptor`	yes
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`item_id`	`string`	yes
`kind`	`ItemKind`	yes	Kinds that can be published and sold on ReuseForge.
`version`	`string`	yes
`target`	`InstallTarget`	yes	Where an item is installed. `generic` extracts into `./reuseforge/<owner>/<slug>/`. `mcp-json` produces a `.mcp.json` entry for `mcp_server` items.
`content_hash`	`ContentHash`	yes	SHA-256 over the text made of one line `<sha256 of file bytes> <path>` 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.
`license`	`string`	yes
`price_cents`	`integer`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`entitlement`	`object`	yes
`entitlement.required`	`boolean`	yes	True when the item is paid.
`entitlement.granted`	`boolean`	yes
`entitlement.reason`	`string: free, owner, org_member, purchased, not_purchased`	yes
`entitlement.order_id`	`string` or `null`	no
`bundle_url`	`string (uri)`	yes	Where to download the file contents (`get_version_bundle`).
`files`	array of `object`	yes	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.
`files[].path`	`string`	yes
`files[].source_path`	`string`	yes
`files[].sha256`	`string`	yes
`files[].size_bytes`	`integer`	yes
`files[].mode`	`string`	yes
`config_patches`	array of `object`	yes	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 `<!-- reuseforge:<block_id> begin/end -->` markers.
`config_patches[].path`	`string`	yes
`config_patches[].format`	`string: json, toml, markdown_block`	yes
`config_patches[].merge`	`object`	no
`config_patches[].block_id`	`string`	no
`config_patches[].content`	`string`	no
`commands`	array of `object`	yes	Suggested shell commands. Clients show them and never run them unless the user passes an explicit flag.
`commands[].description`	`string`	yes
`commands[].command`	`string`	yes
`commands[].run`	`string: never, prompt`	yes
`lock_entry`	`LockEntry`	yes	One package entry of `reuseforge.lock` (full schema in api/schemas/reuseforge.lock.schema.json).
`notes`	array of `string`	no
`warnings`	array of `string`	no

InstallTarget

Where an item is installed. generic extracts into ./reuseforge/<owner>/<slug>/. mcp-json produces a .mcp.json entry for mcp_server items.

One of: generic, claude-code, cursor, codex, mcp-json

Item

Fields of Item
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: item`	yes
`owner`	`AccountRef`	yes
`slug`	`string`	yes
`full_name`	`ItemRef`	yes	Canonical item address `owner/slug`.
`kind`	`ItemKind`	yes	Kinds that can be published and sold on ReuseForge.
`title`	`string`	yes
`summary`	`string`	yes
`readme`	`string`	no	Markdown. Only returned by `get_item` and `create_item`.
`visibility`	`string: public, unlisted, private`	yes
`status`	`string: draft, active, archived, retracted`	yes
`license`	`string`	yes	SPDX identifier, or `Commercial-Single-Project`, `Proprietary`, `UNKNOWN`.
`pricing_model`	`string: free, fixed, pwyw`	yes	For `pwyw` (pay what you want) `price_cents` is the minimum.
`price_cents`	`integer`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`source`	`ItemSource`	no
`homepage_url`	`string`	no
`html_url`	`string (uri)`	no
`capabilities`	array of `string`	yes	Planner taxonomy ids.
`tags`	array of `string`	yes	Same list as `keywords`.
`keywords`	array of `string`	no	The item's tags (the field Claude Code documents).
`latest_version`	`string` or `null`	yes
`verification`	`null` or `VerificationSummary`	no
`stats`	`object`	yes
`stats.stars`	`integer`	yes
`stats.downloads`	`integer`	yes
`stats.reviews`	`integer`	yes
`stats.sales`	`integer`	yes
`signals`	`Signals`	yes	Numeric quality and risk signals shared by hosted items and external candidates. All keys are optional and unknown keys must be tolerated.
`rating`	`number` or `null`	yes	Average of verified-buyer ratings, one decimal.
`rating_count`	`integer`	yes
`demo`	`boolean`	no	Seeded demonstration listing.
`forked_from`	`null` or `ItemRef`	no
`project_id`	`string` or `null`	no	Crowdfunded project whose unit holders share this item's revenue.
`viewer`	`object`	no	Present for signed-in callers on `get_item`.
`viewer.starred`	`boolean`	no
`viewer.can_edit`	`boolean`	no
`viewer.entitled`	`boolean`	no	True for free items, owners, and buyers with a delivered or released order.
`created_at`	`Timestamp`	yes
`updated_at`	`Timestamp`	yes

ItemCreate

Fields of ItemCreate
Field	Type	Required	Description
`owner`	`string`	no	Handle of an organization you can write for. Defaults to you.
`slug`	`string`	yes	Lowercase letters, digits, dots, underscores and hyphens; starts and ends with a letter or digit.
`kind`	`ItemKind`	yes	Kinds that can be published and sold on ReuseForge.
`title`	`string`	yes
`summary`	`string`	no
`readme`	`string`	no
`visibility`	`string: public, unlisted, private`	no	Default `"public"`.
`license`	`string`	no	Default `"UNKNOWN"`.
`pricing_model`	`string: free, fixed, pwyw`	no	Default `"free"`.
`price_cents`	`integer`	no	Default `0`.
`capabilities`	array of `string`	no
`tags`	array of `string`	no
`homepage_url`	`string`	no
`source`	`ItemSource`	no
`forked_from`	`ItemRef`	no	Canonical item address `owner/slug`.

ItemKind

Kinds that can be published and sold on ReuseForge.

One of: repo, skill, harness, mcp_server, model, dataset, prompt, template

ItemPage

Fields of ItemPage
Field	Type	Required	Description
`data`	array of `Item`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

ItemPublishedEvent

Fields of ItemPublishedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "item.published"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Item`	no

ItemRef

Canonical item address owner/slug.

Type: string

ItemRetractedEvent

Fields of ItemRetractedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "item.retracted"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`object`	no

ItemSort

One of: relevance, trending, stars, downloads, updated, newest, rating, price_asc, price_desc

ItemSource

Fields of ItemSource
Field	Type	Required	Description
`provider`	`string`	no	manual, github, huggingface, mcp-registry, arxiv, npm, pypi.
`url`	`string`	no
`ref`	`string`	no

ItemStats

Fields of ItemStats
Field	Type	Required	Description
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`totals`	`object`	yes
`totals.views`	`integer`	yes
`totals.downloads`	`integer`	yes
`totals.stars`	`integer`	yes
`totals.reviews`	`integer`	yes
`totals.sales`	`integer`	yes
`totals.revenue_cents`	`integer`	no	Owners and organization admins only; omitted when the payments ledger has no figure for the item.
`days`	array of `object`	no	Owners only. One entry per UTC day, oldest first.
`days[].day`	`string (date)`	yes
`days[].views`	`integer`	yes
`days[].downloads`	`integer`	yes
`days[].stars`	`integer`	yes

ItemUpdate

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.

Fields of ItemUpdate
Field	Type	Required
`title`	`string`	no
`summary`	`string`	no
`readme`	`string`	no
`visibility`	`string: public, unlisted, private`	no
`status`	`string: draft, active, archived`	no
`license`	`string`	no
`pricing_model`	`string: free, fixed, pwyw`	no
`price_cents`	`integer`	no
`capabilities`	array of `string`	no
`tags`	array of `string`	no
`homepage_url`	`string`	no
`source`	`ItemSource`	no

ItemUpdatedEvent

Fields of ItemUpdatedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "item.updated"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Item`	no

ItemVersion

Fields of ItemVersion
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: item_version`	yes
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`item_id`	`string`	yes
`version`	`string`	yes
`changelog`	`string`	yes
`content_hash`	`ContentHash`	yes	SHA-256 over the text made of one line `<sha256 of file bytes> <path>` 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.
`size_bytes`	`integer`	yes
`file_count`	`integer`	yes
`files`	array of `FileEntry`	no	Only on `get_version`.
`dependencies`	array of `Dependency`	yes
`yanked`	`boolean`	yes
`yanked_reason`	`string` or `null`	no
`prerelease`	`boolean`	yes
`archive_sha256`	`string` or `null`	no	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`	`object` or `null`	no	The `reuseforge.json` manifest submitted with the version, if any.
`verification`	`Verification`	no
`created_by`	`AccountRef`	no
`created_at`	`Timestamp`	yes

ItemVersionPage

Fields of ItemVersionPage
Field	Type	Required	Description
`data`	array of `ItemVersion`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

ItemVersionPublishedEvent

Fields of ItemVersionPublishedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "item.version.published"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`ItemVersion`	no

LedgerEvent

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.

Fields of LedgerEvent
Field	Type	Required	Description
`id`	`string`	yes
`body`	`object`	yes
`body.kind`	`string`	yes	For example `block.publish`, `block.retract`, `block.attest`, `review`, `project.create`.
`body.author`	`string`	yes	Public id `rb1<base64url>` of the signing identity.
`body.data`	`object`	yes
`body.lamport`	`integer`	yes
`body.parents`	array of `string`	yes
`body.ts`	`integer`	yes	Unix seconds.
`sig`	`string`	yes	base64url Ed25519 signature over the canonical JSON of `body`.

LedgerEventPage

Fields of LedgerEventPage
Field	Type	Required	Description
`data`	array of `LedgerEvent`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

LedgerEventsPush

Fields of LedgerEventsPush
Field	Type	Required	Description
`events`	array of `LedgerEvent`	yes

LedgerPushResult

Fields of LedgerPushResult
Field	Type	Required	Description
`added`	`integer`	yes
`duplicates`	`integer`	yes
`rejected`	array of `object`	yes
`rejected[].id`	`string`	yes
`rejected[].code`	`ErrorCode`	yes	Stable, machine-readable error identifiers. New codes may be added in minor releases; branch on `code`, never on `title` or `detail`.
`rejected[].message`	`string`	yes

Schemas LockEntry to PayoutKind

LockEntry

One package entry of reuseforge.lock (full schema in api/schemas/reuseforge.lock.schema.json).

Fields of LockEntry
Field	Type	Required	Description
`name`	`ItemRef`	yes	Canonical item address `owner/slug`.
`id`	`string`	yes
`version`	`string`	yes
`kind`	`ItemKind`	yes	Kinds that can be published and sold on ReuseForge.
`target`	`InstallTarget`	yes	Where an item is installed. `generic` extracts into `./reuseforge/<owner>/<slug>/`. `mcp-json` produces a `.mcp.json` entry for `mcp_server` items.
`content_hash`	`ContentHash`	yes	SHA-256 over the text made of one line `<sha256 of file bytes> <path>` 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.
`license`	`string`	yes
`source`	`string`	yes	`reuseforge` or the origin URL of an external block.
`order_id`	`string` or `null`	no
`price_paid_cents`	`integer`	no
`files`	array of `LockFile`	yes

LockFile

Fields of LockFile
Field	Type	Required	Description
`path`	`string`	yes
`sha256`	`string`	yes

McpConfig

Fields of McpConfig
Field	Type	Required	Description
`mcpServers`	map of `object`	yes	Drop-in `.mcp.json` content. Key name is camelCase because the file format requires it.
`servers`	array of `object`	yes
`servers[].name`	`string`	yes
`servers[].purpose`	`string`	yes
`servers[].oauth`	`boolean`	yes
`servers[].verified`	`boolean`	yes	False when the URL or tool name was not confirmed against the live server.
`servers[].token_env`	`string` or `null`	no
`capabilities`	array of `string`	yes

Me

Fields of Me
Field	Type	Required
`id`	`string`	yes
`object`	`string: account`	yes
`type`	`string: user`	yes
`handle`	`string`	yes
`display_name`	`string`	yes
`avatar_url`	`string`	no
`email`	`string (email)`	no
`email_verified`	`boolean`	yes
`role`	`string: user, admin`	yes
`created_at`	`Timestamp`	yes
`auth`	`object`	yes
`auth.via`	`string: token, session`	yes
`auth.scopes`	array of `Scope`	yes
`auth.token_id`	`string` or `null`	no
`auth.spend_limit_cents`	`integer` or `null`	no
`auth.spent_cents`	`integer`	no
`orgs`	array of `object`	yes
`orgs[].account`	`AccountRef`	yes
`orgs[].role`	`string: owner, admin, write, read`	yes

Milestone

Fields of Milestone
Field	Type	Required	Description
`index`	`integer`	yes
`name`	`string`	yes
`bps`	`integer`	yes
`amount_cents`	`integer`	yes
`state`	`string: pending, submitted, approved, rejected`	yes
`evidence`	`string` or `null`	no
`submitted_by`	`null` or `AccountRef`	no
`submitted_at`	`string (date-time)` or `null`	no
`decided_at`	`string (date-time)` or `null`	no
`submissions`	`integer`	no	Number of times it was submitted (at most 3).
`votes`	`object`	yes	Weights are pledge amounts in cents, so transferring units cannot double-count a vote.
`votes.approve_weight`	`integer`	yes
`votes.reject_weight`	`integer`	yes
`votes.total_weight`	`integer`	yes

NextAction

What a client or agent should do next to progress the order.

Fields of NextAction
Field	Type	Required
`type`	`string: send_payment, sign_transaction, review_delivery, wait`	yes
`description`	`string`	yes
`chain_id`	`integer`	no
`to`	`string`	no
`data`	`string` or `null`	no
`uri`	`string`	no

OpenApiDocument

Fields of OpenApiDocument
Field	Type	Required	Description
`openapi`	`string`	yes
`info`	`object`	yes

Order

Fields of Order
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: order`	yes
`state`	`OrderState`	yes
`buyer`	`AccountRef`	yes
`items`	array of `OrderItem`	yes
`subtotal_cents`	`integer`	yes	Sum of item prices.
`fee_bps`	`integer`	yes	Platform fee rate snapshotted at creation.
`fee_cents`	`integer`	yes	Sum of item fees. Deducted from sellers' proceeds, not added to the buyer's price.
`total_cents`	`integer`	yes	What the buyer pays (equals `subtotal_cents`).
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`payment`	`Payment`	yes	Rail-agnostic payment instructions and status.
`plan_id`	`string` or `null`	no
`accept_window_seconds`	`integer`	no
`deliver_window_seconds`	`integer`	no
`funded_at`	`string (date-time)` or `null`	no
`settled_at`	`string (date-time)` or `null`	no
`payouts`	array of `Payout`	no
`next_actions`	array of `NextAction`	no
`created_at`	`Timestamp`	yes
`updated_at`	`Timestamp`	yes

OrderCreate

Give either plan_id or items.

One of: any or any

OrderCreatedEvent

Fields of OrderCreatedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "order.created"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Order`	no

OrderDeliveredEvent

Fields of OrderDeliveredEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "order.delivered"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Order`	no

OrderDisputedEvent

Fields of OrderDisputedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "order.disputed"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Order`	no

OrderFundedEvent

Fields of OrderFundedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "order.funded"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Order`	no

OrderHint

Machine-actionable instructions that turn a 402 into a purchase.

Fields of OrderHint
Field	Type	Required	Description
`reason`	`string: item_not_purchased, order_not_funded, order_refunded`	yes
`total_cents`	`integer`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`items`	array of `object`	yes
`items[].item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`items[].item_id`	`string`	yes
`items[].version`	`string`	no
`items[].price_cents`	`integer`	yes
`order_id`	`string` or `null`	no	Existing unpaid order that would unlock the item, if any.
`create_order`	`object`	yes
`create_order.method`	`string: POST`	yes
`create_order.href`	`string`	yes
`create_order.body`	`object`	yes

OrderItem

Fields of OrderItem
Field	Type	Required	Description
`item_id`	`string`	yes
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`title`	`string`	yes
`version`	`string`	yes
`seller`	`AccountRef`	yes
`state`	`OrderItemState`	yes
`price_cents`	`integer`	yes
`fee_cents`	`integer`	yes	Platform fee on this item. Zero when refunded.
`seller_amount_cents`	`integer`	yes	What the seller receives on release (price minus fee).
`project_id`	`string` or `null`	no
`delivery`	`null` or `object`	no
`deliver_by`	`string (date-time)` or `null`	no
`accept_by`	`string (date-time)` or `null`	no	After this moment silence releases the funds.
`dispute`	`null` or `object`	no
`resolution`	`null` or `object`	no
`release_reason`	`string: accepted, window_expired, resolved, null`	no

OrderItemInput

Fields of OrderItemInput
Field	Type	Required	Description
`item`	`ItemRef` or `string`	yes	Address `owner/slug` or id.
`version`	`string`	no	Exact version to buy. Defaults to the latest at order time.
`amount_cents`	`integer`	no	Price for `pwyw` items (at least the minimum).

OrderItemState

One of: pending, delivered, released, disputed, resolved, refunded

OrderPage

Fields of OrderPage
Field	Type	Required	Description
`data`	array of `Order`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

OrderRefundedEvent

Fields of OrderRefundedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "order.refunded"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Order`	no

OrderReleasedEvent

Fields of OrderReleasedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "order.released"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Order`	no

OrderState

One of: awaiting_payment, funded, settled, expired, cancelled

Page

Cursor page. Every collection endpoint returns this shape (with data narrowed to the item type).

Fields of Page
Field	Type	Required	Description
`data`	array of `any`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

PaidItem

Fields of PaidItem
Field	Type	Required	Description
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`item_id`	`string`	yes
`name`	`string`	yes
`version`	`string`	yes
`seller`	`string`	yes
`price_cents`	`integer`	yes
`project_id`	`string` or `null`	no

PayOrder

Fields of PayOrder
Field	Type	Required	Description
`tx_ref`	`string`	no	Transaction hash. Required on real rails, ignored on `simulated`.

Payment

Rail-agnostic payment instructions and status.

Fields of Payment
Field	Type	Required	Description
`rail`	`PaymentRail`	yes	Open set. Known: `simulated`, `base-usdc`, `base-usdt`, `btc`. Python nodes also use `usdc-base` and `usdt-ethereum`.
`network`	`string` or `null`	no	Chain or network id, for example `base-sepolia`, `base`, `testnet4`.
`asset`	`string`	no	USDC, USDT, BTC or USD (simulated).
`status`	`string: awaiting_payment, pending_confirmations, confirmed, failed, expired, refunded`	yes
`amount_cents`	`integer`	yes
`amount_atomic`	`string`	no	Amount in the asset's smallest unit (token base units or satoshis) as a decimal string.
`address`	`string`	yes	Escrow contract or deposit address the buyer pays.
`memo`	`string` or `null`	no	Reference to include when the rail supports one.
`uri`	`string` or `null`	no	Wallet link (EIP-681 `ethereum:` or BIP-21 `bitcoin:`).
`tx_ref`	`string` or `null`	no	Transaction hash or simulated reference that funded the order.
`confirmations`	`integer`	no
`required_confirmations`	`integer`	no
`expires_at`	`string (date-time)` or `null`	no	End of the price quote.
`refund_address`	`string` or `null`	no
`simulated`	`boolean`	no	True when no real funds move.

PaymentRail

Open set. Known: simulated, base-usdc, base-usdt, btc. Python nodes also use usdc-base and usdt-ethereum.

Type: string

Payout

Fields of Payout
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: payout`	yes
`order_id`	`string`	yes
`item_id`	`string` or `null`	no
`kind`	`PayoutKind`	yes
`recipient`	`null` or `AccountRef`	no
`address`	`string`	yes
`rail`	`PaymentRail`	yes	Open set. Known: `simulated`, `base-usdc`, `base-usdt`, `btc`. Python nodes also use `usdc-base` and `usdt-ethereum`.
`amount_cents`	`integer`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`state`	`string: pending, sent, failed`	yes
`tx_ref`	`string` or `null`	no
`sent_at`	`string (date-time)` or `null`	no
`project_id`	`string` or `null`	no

PayoutKind

One of: seller, platform_fee, refund, revenue_share

Schemas PayoutPage to StarState

PayoutPage

Fields of PayoutPage
Field	Type	Required	Description
`data`	array of `Payout`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

PayoutSentEvent

Fields of PayoutSentEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "payout.sent"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Payout`	no

PingEvent

Fields of PingEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "ping"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`object`	no

Plan

Fields of Plan
Field	Type	Required	Description
`id`	`string`	yes	The `plan_id` used by other operations. Valid 24 hours.
`object`	`string: plan`	yes
`goal`	`string`	yes
`budget_cents`	`integer` or `null`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`created_at`	`Timestamp`	yes
`expires_at`	`Timestamp`	yes
`requirements`	array of `Requirement`	yes
`pareto_front`	array of `PlanOption`	yes
`recommended`	`null` or `PlanOption`	yes
`recommended_index`	`integer` or `null`	yes
`explanations`	array of `Explanation`	yes
`sources`	array of `SourceStatus`	yes
`note`	`string` or `null`	no	Set when nothing fits the budget.
`partial`	`boolean`	yes	True when at least one connector failed.

PlanOption

Fields of PlanOption
Field	Type	Required	Description
`index`	`integer`	yes	Position in `pareto_front`.
`objectives`	`object`	yes
`objectives.quality`	`number`	yes	Mean over requirements. Higher is better.
`objectives.cost_cents`	`integer`	yes	Paid items (each once) plus estimated build cost. Lower is better.
`objectives.risk`	`number`	yes	Mean over requirements. Lower is better.
`paid_total_cents`	`integer`	yes
`build_total_cents`	`integer`	yes
`steps`	array of `PlanStep`	yes
`paid_items`	array of `PaidItem`	yes

PlanRequest

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

PlanStep

Fields of PlanStep
Field	Type	Required	Description
`requirement`	`string`	yes
`action`	`string: use, build`	yes
`candidate`	`null` or `Candidate`	yes
`quality`	`number`	yes
`cost_cents`	`integer`	yes	Price of the candidate, or the estimated agent-token cost of building.
`risk`	`number`	yes
`blueprints`	array of `object`	no
`blueprints[].title`	`string`	yes
`blueprints[].url`	`string`	yes

Portfolio

Fields of Portfolio
Field	Type	Required	Description
`holder`	`AccountRef`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`invested_cents`	`integer`	yes
`dividends_cents`	`integer`	yes
`net_cents`	`integer`	yes
`positions`	array of `object`	yes
`positions[].project_id`	`string`	yes
`positions[].title`	`string`	yes
`positions[].state`	`ProjectState`	yes
`positions[].invested_cents`	`integer`	yes
`positions[].units`	`integer`	yes
`positions[].ownership_bps`	`integer`	yes
`positions[].dividends_cents`	`integer`	yes
`positions[].net_cents`	`integer`	yes

Problem

RFC 9457 problem details, served as application/problem+json. Extension members depend on code.

Fields of Problem
Field	Type	Required	Description
`type`	`string (uri-reference)`	yes	Documentation URL for the error: `https://reuseforge.com/docs/api/errors/<code>`.
`title`	`string`	yes	Short summary that is stable per code.
`status`	`integer`	yes
`detail`	`string`	no	Human-readable explanation of this occurrence. Do not parse it.
`instance`	`string`	no	Path of the request that failed.
`code`	`ErrorCode`	yes	Stable, machine-readable error identifiers. New codes may be added in minor releases; branch on `code`, never on `title` or `detail`.
`request_id`	`string`	yes
`errors`	array of `FieldError`	no	Per-field problems for `validation_failed`, `invalid_parameter` and `invalid_request`.
`retry_after`	`integer`	no	Seconds to wait. Mirrors `Retry-After`. Present for `rate_limited`, `unavailable`, `upstream_error`, `idempotency_in_progress`.
`required_scopes`	array of `string`	no	Present for `insufficient_scope`.
`order_hint`	`OrderHint`	no	Machine-actionable instructions that turn a 402 into a purchase.
`current_etag`	`string`	no	Present for `precondition_failed`.
`state`	`string`	no	Present for `invalid_state`: the state that blocked the call.
`limit_cents`	`integer`	no	Present for `spend_limit_exceeded`: the token's limit.
`spent_cents`	`integer`	no	Present for `spend_limit_exceeded`: already spent.

Project

Fields of Project
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: project`	yes
`title`	`string`	yes
`spec`	`string`	yes
`deliverables`	array of `string`	yes
`proposer`	`AccountRef`	yes
`state`	`ProjectState`	yes
`goal_cents`	`integer`	yes
`raised_cents`	`integer`	yes
`pending_cents`	`integer`	no	Pledges awaiting confirmation.
`progress`	`number`	yes
`currency`	`Currency`	yes	ISO 4217 code. Only USD in v1.
`created_at`	`Timestamp`	yes
`deadline_at`	`Timestamp`	yes
`funded_at`	`string (date-time)` or `null`	no
`developers`	array of `Developer`	yes
`milestones`	array of `Milestone`	yes
`cap_table`	array of `object`	yes
`cap_table[].holder`	`AccountRef`	yes
`cap_table[].units`	`integer`	yes
`cap_table[].ownership_bps`	`integer`	yes
`total_units`	`integer`	yes	Fixed supply of revenue units.
`dividends_cents`	`integer`	no	Revenue distributed to unit holders so far.
`product`	`null` or `ItemRef`	no
`share_token`	`object` or `null`	no	On-chain revenue-share token when the EVM rail is used.

ProjectCreate

Fields of ProjectCreate
Field	Type	Required	Description
`title`	`string`	yes
`spec`	`string`	no
`deliverables`	array of `string`	yes
`goal_cents`	`integer`	yes
`deadline_days`	`number`	no	Default `30`.
`developers`	array of `object`	yes
`developers[].account`	`string`	yes	Handle or account id of the developer.
`developers[].budget_bps`	`integer`	yes
`developers[].equity_bps`	`integer`	yes
`milestones`	array of `object`	yes
`milestones[].name`	`string`	yes
`milestones[].bps`	`integer`	yes

ProjectFundedEvent

Fields of ProjectFundedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "project.funded"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Project`	no

ProjectMilestoneApprovedEvent

Fields of ProjectMilestoneApprovedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "project.milestone.approved"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Milestone`	yes
`data.project_id`	`string`	yes

ProjectPage

Fields of ProjectPage
Field	Type	Required	Description
`data`	array of `Project`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

ProjectState

One of: open, funded, completed, failed, aborted

RateLimit

Fields of RateLimit
Field	Type	Required
`tier`	`string: read, write, plan, discover, payments`	yes
`limit`	`integer`	yes
`remaining`	`integer`	yes
`reset_seconds`	`integer`	yes
`window_seconds`	`integer`	yes
`policy`	`string`	yes
`daily_limit`	`integer`	no
`daily_remaining`	`integer`	no

RateLimitStatus

Fields of RateLimitStatus
Field	Type	Required	Description
`principal`	`string: anonymous, token, session`	yes
`tiers`	array of `RateLimit`	yes

RefundItem

Fields of RefundItem
Field	Type	Required	Description
`note`	`string`	no

Requirement

Fields of Requirement
Field	Type	Required	Description
`capability`	`string`	yes	Planner taxonomy id or free kebab-case tag.
`description`	`string`	yes
`keywords`	array of `string`	yes

ResolveDispute

Fields of ResolveDispute
Field	Type	Required	Description
`seller_bps`	`integer`	yes
`note`	`string`	yes

Review

Fields of Review
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: review`	yes
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`author`	`AccountRef`	yes
`rating`	`integer`	yes
`title`	`string`	yes
`body`	`string`	yes
`verified_purchase`	`boolean`	yes
`basis`	`string: purchase, install, none`	yes	`none` only appears on reviews written in the web app before verification existed.
`created_at`	`Timestamp`	yes

ReviewCreate

Fields of ReviewCreate
Field	Type	Required
`rating`	`integer`	yes
`title`	`string`	no
`body`	`string`	no

ReviewCreatedEvent

Fields of ReviewCreatedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "review.created"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Review`	no

ReviewPage

Fields of ReviewPage
Field	Type	Required	Description
`data`	array of `Review`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

Scope

One of: items:read, items:write, items:publish, orders:read, orders:create, orders:pay, orders:accept, projects:read, projects:write, webhooks:manage, tokens:manage, admin

Signals

Numeric quality and risk signals shared by hosted items and external candidates. All keys are optional and unknown keys must be tolerated.

Fields of Signals
Field	Type	Required	Description
`stars`	`number`	no
`downloads`	`number`	no
`citations`	`number`	no
`tests_pass_rate`	`number`	no
`forks`	`number`	no
`open_issues`	`number`	no
`dependents`	`number`	no
`vulns_total`	`number`	no
`vulns_critical_high`	`number`	no
`scorecard`	`number`	no	OpenSSF Scorecard aggregate.
`archived`	`number: 0, 1`	no
`days_since_update`	`number`	no

SourceStatus

Fields of SourceStatus
Field	Type	Required
`connector`	`string`	yes
`status`	`string: ok, error, skipped`	yes
`count`	`integer`	yes
`duration_ms`	`integer`	no
`error`	`string`	no

StarState

Fields of StarState
Field	Type	Required	Description
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`starred`	`boolean`	yes
`stars_count`	`integer`	yes

Schemas Timestamp to WebhookWithSecret

Timestamp

Type: string (date-time)

Token

Fields of Token
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: token`	yes
`name`	`string`	yes
`prefix`	`string`	yes	First characters of the secret, safe to show.
`scopes`	array of `Scope`	yes
`spend_limit_cents`	`integer` or `null`	yes	Lifetime cap on money this token may commit through `pay_order` and `back_project`. Null means unlimited.
`spent_cents`	`integer`	yes
`created_at`	`Timestamp`	yes
`last_used_at`	`string (date-time)` or `null`	yes
`expires_at`	`string (date-time)` or `null`	yes

TokenCreate

Fields of TokenCreate
Field	Type	Required	Description
`name`	`string`	yes
`scopes`	array of `Scope`	yes
`expires_in_days`	`integer`	no	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`	`integer` or `null`	no	Default 5000 when `orders:pay` is requested (the only scope that can commit money). Null (unlimited) is only honoured for interactive sessions.

TokenPage

Fields of TokenPage
Field	Type	Required	Description
`data`	array of `Token`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

TokenWithSecret

Fields of TokenWithSecret
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: token`	yes
`name`	`string`	yes
`prefix`	`string`	yes	First characters of the secret, safe to show.
`scopes`	array of `Scope`	yes
`spend_limit_cents`	`integer` or `null`	yes	Lifetime cap on money this token may commit through `pay_order` and `back_project`. Null means unlimited.
`spent_cents`	`integer`	yes
`created_at`	`Timestamp`	yes
`last_used_at`	`string (date-time)` or `null`	yes
`expires_at`	`string (date-time)` or `null`	yes
`token`	`string`	yes	The secret. Shown once.

TransferUnits

Fields of TransferUnits
Field	Type	Required	Description
`to`	`string`	yes	Handle or account id of the recipient.
`units`	`integer`	yes

Verification

Fields of Verification
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: verification`	yes
`item`	`ItemRef`	yes	Canonical item address `owner/slug`.
`version`	`string`	yes
`state`	`string: queued, running, passed, failed, error`	yes
`runner`	`string: static-v1, platform, community, seller`	yes	`static-v1` is the in-API static checker (no publisher code is executed). `platform`, `community` and `seller` are attested test runs.
`tests_total`	`integer` or `null`	no	Test cases attested by the runner; for `static-v1` the number of static checks that ran.
`tests_passed`	`integer` or `null`	no
`tests_pass_rate`	`number` or `null`	no	Only set by runners that executed tests. Always `null` for `static-v1`.
`summary`	`string` or `null`	no
`checks`	array of `object`	no	Per-check results of a static run (absent for attested runs).
`checks[].id`	`string`	yes	hashes, limits, manifest, license, secrets, binaries, skill, mcp, readme.
`checks[].status`	`string: pass, warn, fail, skip`	yes
`checks[].message`	`string`	yes
`checks[].path`	`string`	no	The file the finding is about, when there is one.
`created_at`	`Timestamp`	yes
`completed_at`	`string (date-time)` or `null`	no

VerificationCompletedEvent

Fields of VerificationCompletedEvent
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: event`	yes
`type`	`const "verification.completed"`	yes
`api_version`	`string: 1`	yes
`created_at`	`Timestamp`	yes
`account`	`string`	yes	Handle of the account the delivery is for.
`data`	`object`	yes
`data.object`	`Verification`	no

VerificationSummary

Fields of VerificationSummary
Field	Type	Required
`state`	`string: queued, running, passed, failed, error`	yes
`version`	`string`	yes
`tests_pass_rate`	`number` or `null`	no
`verified_at`	`string (date-time)` or `null`	no

VersionCreate

Fields of VersionCreate
Field	Type	Required	Description
`version`	`string`	yes
`changelog`	`string`	no
`files`	array of `FileInput`	yes
`dependencies`	array of `Dependency`	no
`manifest`	`object`	no	Contents of `reuseforge.json` (schema: api/schemas/reuseforge.schema.json). Validated and stored.
`content_hash`	`ContentHash`	no	SHA-256 over the text made of one line `<sha256 of file bytes> <path>` 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.

VersionUpdate

Fields of VersionUpdate
Field	Type	Required
`changelog`	`string`	no
`yanked`	`boolean`	no
`yanked_reason`	`string` or `null`	no

VoteAbort

Fields of VoteAbort
Field	Type	Required	Description
`abort`	`boolean`	yes

VoteMilestone

Fields of VoteMilestone
Field	Type	Required	Description
`approve`	`boolean`	yes

Webhook

Fields of Webhook
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: webhook`	yes
`url`	`string (uri)`	yes
`description`	`string`	no
`events`	array of `EventType` or `string: *`	yes	Subscribed event types, or `["*"]` for every type.
`account`	`string`	no	Handle of the account whose events are delivered.
`status`	`string: enabled, disabled`	yes
`disabled_reason`	`string: manual, consecutive_failures, ssrf_blocked, null`	no
`api_version`	`string`	yes	Payload version. Fixed at creation.
`consecutive_failures`	`integer`	yes
`last_delivery_at`	`string (date-time)` or `null`	no
`last_success_at`	`string (date-time)` or `null`	no
`created_at`	`Timestamp`	yes
`updated_at`	`Timestamp`	yes

WebhookCreate

Fields of WebhookCreate
Field	Type	Required	Description
`url`	`string (uri)`	yes
`description`	`string`	no
`events`	array of `EventType` or `string: *`	yes
`account`	`string`	no	Organization handle you administer. Defaults to you.

WebhookDelivery

Fields of WebhookDelivery
Field	Type	Required
`id`	`string`	yes
`object`	`string: webhook_delivery`	yes
`webhook_id`	`string`	yes
`event_id`	`string`	yes
`event_type`	`string`	yes
`attempt`	`integer`	yes
`state`	`string: pending, retrying, succeeded, failed, exhausted`	yes
`scheduled_at`	`Timestamp`	yes
`delivered_at`	`string (date-time)` or `null`	no
`response_status`	`integer` or `null`	no
`response_ms`	`integer` or `null`	no
`response_excerpt`	`string` or `null`	no
`error`	`string` or `null`	no
`next_attempt_at`	`string (date-time)` or `null`	no

WebhookDeliveryPage

Fields of WebhookDeliveryPage
Field	Type	Required	Description
`data`	array of `WebhookDelivery`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

WebhookPage

Fields of WebhookPage
Field	Type	Required	Description
`data`	array of `Webhook`	yes
`next_cursor`	`string` or `null`	yes	Pass as `cursor` to get the next page. Null on the last page.
`has_more`	`boolean`	yes
`total`	`integer`	no	Total matches when cheap to compute (search). May be an estimate.

WebhookUpdate

Fields of WebhookUpdate
Field	Type	Required
`url`	`string (uri)`	no
`description`	`string`	no
`events`	array of `EventType` or `string: *`	no
`status`	`string: enabled, disabled`	no

WebhookWithSecret

Fields of WebhookWithSecret
Field	Type	Required	Description
`id`	`string`	yes
`object`	`string: webhook`	yes
`url`	`string (uri)`	yes
`description`	`string`	no
`events`	array of `EventType` or `string: *`	yes	Subscribed event types, or `["*"]` for every type.
`account`	`string`	no	Handle of the account whose events are delivered.
`status`	`string: enabled, disabled`	yes
`disabled_reason`	`string: manual, consecutive_failures, ssrf_blocked, null`	no
`api_version`	`string`	yes	Payload version. Fixed at creation.
`consecutive_failures`	`integer`	yes
`last_delivery_at`	`string (date-time)` or `null`	no
`last_success_at`	`string (date-time)` or `null`	no
`created_at`	`Timestamp`	yes
`updated_at`	`Timestamp`	yes
`secret`	`string`	yes	Signing secret. Shown once.
`previous_secret_expires_at`	`string (date-time)` or `null`	no	Set after rotation: until then deliveries carry two signatures.