OpenAPI

Discovery tools such as agentcash read your OpenAPI document before the agent calls anything. When Forge enriches it, those tools list GET /feedback/rate as one of your endpoints (free, unprotected), show the rating step in your guidance, and show feedback_id in your response schemas. Rating becomes part of the plan before the call.

Two ways to wire it

Intercept your route (default)
Give Forge the document

If you already serve GET /openapi.json, do nothing. Forge buffers that response and serves an enriched copy. This works with res.json, res.send, express.static and sendFile, and handles conditional requests and Content-Length.

const forge = createForge({ apiKey, backendUrl, publicUrl }); // openapi: { paths: ["/openapi.json"] } by default
app.use(forge.middleware());
app.get("/openapi.json", (req, res) => res.json(spec));

Other paths: openapi: { paths: ["/openapi.json", "/.well-known/openapi.json"] }.

Pass the document (or an async function that returns it), and Forge serves it at the spec path. Strict response schemas are then respected from the very first paid call.

const forge = createForge({ apiKey, backendUrl, publicUrl, openapi: { document: spec } });

This is what the weather API and the core example do.

Turn enrichment off with openapi: false.

What’s added

Paths: GET /feedback, POST /feedback, GET /feedback/rate and GET /feedback/summary, with security: []
Paid operations (a 402 response or x-payment-info): optional feedback_id, feedback_url and rate_this_call on 2xx JSON response schemas and on x-payment-info.outputSchema, plus the sentence in the operation description
Guidance: the sentence appended to info.x-guidance (or root x-guidance)
Marker: a root x-forge-feedback object, so enriching twice changes nothing

Rules

Additive only. Nothing is removed or reordered, and your input object is never mutated.
Shared components are never edited. A paid response that uses $ref gets an inline, extended copy.
Strict schemas are respected. If a schema can’t safely take extra fields (oneOf/anyOf, strict allOf members, propertyNames, maxProperties, an existing feedback_id), it’s left alone, and that operation gets the header only.
Your paths win. If you already define /feedback, nothing is overwritten. Use basePath to move Forge’s routes.
Server prefixes are handled (servers[0], or Swagger host + basePath).
Fail-safe. YAML, compressed or oversized bodies, unknown versions and any internal error are served byte-for-byte as they were.

Supported: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2.

Keep your own x-guidance short, like a one-line manual: what each paid route returns and what it costs. Forge appends the rating step to it.

Get started

Integrations

Guides

Two ways to wire it

What’s added

Rules

​Two ways to wire it

​What’s added

​Rules

Two ways to wire it

What’s added

Rules