API

Meta operations

Index, health, contract, event catalogue and rate limit status.

Index, health, contract, event catalogue and rate limit status. Paths are relative to https://reuseforge.com/api/v1.

Operations in this area
Operation	Method	Path
API index	`GET`	`/`
Health check	`GET`	`/health`
This contract	`GET`	`/openapi.{format}`
Webhook event catalogue	`GET`	`/event-types`
Rate limit status	`GET`	`/rate-limit`

API index

GET / Enabled on reuseforge.com

Entry point with links to every top-level collection, the enabled payment rails, current limits and any announced deprecations. Safe to call without credentials.

API index: facts
Property	Value
Operation ID	`get_api_index`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.get_api_index(...)`
JavaScript SDK	`client.getApiIndex(...)`
CLI	`rf api index`
MCP tool	not exposed as a tool
Deployments	reuseforge.com: enabled. Python node: implemented.

Responses

API index: responses
Status	Meaning	Body
200 OK	The index.	`application/json`: `ApiIndex`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`
500	Unexpected failure on our side. Safe to retry idempotent calls; quote `request_id` if it persists.	`Problem`. Codes: `internal`

Example

curl

bash

curl 'https://reuseforge.com/api/v1'

Python

python

import reuseforge

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

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

JavaScript

javascript

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

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

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

CLI

bash

rf api index

# rf api index
# all options: rf api index --help

Response 200 OK:

json

{
  "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": []
}

Health check

GET /health Enabled on reuseforge.com

Cheap liveness and dependency check for monitors. Returns 200 when the API can serve requests and 503 when it cannot reach its database.

Health check: facts
Property	Value
Operation ID	`get_health`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.get_health(...)`
JavaScript SDK	`client.getHealth(...)`
CLI	`rf api health`
MCP tool	not exposed as a tool
Deployments	reuseforge.com: enabled. Python node: implemented.

Responses

Health check: responses
Status	Meaning	Body
200 OK	Healthy or degraded (degraded still serves).	`application/json`: `Health`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`
503	Temporarily unable to serve (maintenance or a dependency is down). Honour `Retry-After`.	`Problem`. Codes: `unavailable`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/health'

Python

python

import reuseforge

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

result = client.get_health()
print(result)

JavaScript

javascript

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

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

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

CLI

bash

rf api health

# rf api health
# all options: rf api health --help

Response 200 OK:

json

{
  "status": "ok",
  "time": "2026-11-03T10:00:00Z",
  "version": "1.1.0",
  "components": {
    "database": "ok",
    "cache": "ok",
    "connectors": "ok"
  }
}

This contract

GET /openapi.{format} Enabled on reuseforge.com

The OpenAPI 3.1 document served by this deployment, as JSON or YAML. Cacheable; honours If-None-Match.

This contract: facts
Property	Value
Operation ID	`get_openapi_document`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Caching	Sends an `ETag`; repeat with `If-None-Match` to get `304 Not Modified`
Python SDK	`client.get_openapi_document(...)`
JavaScript SDK	`client.getOpenapiDocument(...)`
CLI	`rf api openapi`
MCP tool	not exposed as a tool
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

This contract: parameters
Name	In	Type	Required	Description
`format`	path	`string: json, yaml`	yes
`If-None-Match`	header	`string`	no	ETag from an earlier response; a match returns 304 without a body.

Responses

This contract: responses
Status	Meaning	Body
200 OK	The OpenAPI document.	`application/json`: `OpenApiDocument`
304 Not Modified	Not modified.	no body
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/openapi.json'

Python

python

import reuseforge

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

result = client.get_openapi_document("json")
print(result)

JavaScript

javascript

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

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

const result = await client.getOpenapiDocument("json");
console.log(result);

CLI

bash

rf api openapi

# rf api openapi [options]
# all options: rf api openapi --help

Response 200 OK:

json

{
  "openapi": "3.1.0",
  "info": {
    "title": "ReuseForge API",
    "version": "1.1.0"
  },
  "paths": {}
}

Webhook event catalogue

GET /event-types Enabled on reuseforge.com

Every event type that can be delivered to webhooks, with the resource carried in data.object.

Webhook event catalogue: facts
Property	Value
Operation ID	`list_event_types`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.list_event_types(...)`
JavaScript SDK	`client.listEventTypes(...)`
CLI	`rf events types`
MCP tool	`list_event_types`
Deployments	reuseforge.com: enabled. Python node: implemented.

Responses

Webhook event catalogue: responses
Status	Meaning	Body
200 OK	The catalogue.	`application/json`: `EventTypePage`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/event-types'

Python

python

import reuseforge

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

result = client.list_event_types()
print(result["type"])

JavaScript

javascript

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

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

const result = await client.listEventTypes();
console.log(result.type);

CLI

bash

rf events types

# rf events types
# all options: rf events types --help

Response 200 OK:

json

{
  "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
}

Rate limit status

GET /rate-limit Enabled on reuseforge.com

Your current allowance in every tier. Does not itself consume allowance.

Rate limit status: facts
Property	Value
Operation ID	`get_rate_limits`
Authentication	None required. A token raises your rate limits and shows your private items.
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.get_rate_limits(...)`
JavaScript SDK	`client.getRateLimits(...)`
CLI	`rf api rate-limit`
MCP tool	`get_rate_limits`
Deployments	reuseforge.com: enabled. Python node: implemented.

Responses

Rate limit status: responses
Status	Meaning	Body
200 OK	Allowance per tier.	`application/json`: `RateLimitStatus`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/rate-limit'

Python

python

import reuseforge

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

result = client.get_rate_limits()
print(result)

JavaScript

javascript

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

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

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

CLI

bash

rf api rate-limit

# rf api rate-limit
# all options: rf api rate-limit --help

Response 200 OK:

json

{
  "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"
    }
  ]
}