Required
string
required
Your Forge API key (
forge_…), from your project’s Agents page. Feedback IDs are signed with a key derived from it, so keep it secret.string
required
Where events and ratings go: the
backendUrl shown on your Agents page (it ends in /api/sdk/v2). A bare origin uses /v1/events, /v1/feedback and /v1/summary instead.string
required
This service’s public origin, for example
https://api.example.com. Used in every rating URL agents see. Never derived from the Host header.Routes
string
default:"/feedback"
Where Forge serves its routes:
{basePath}, {basePath}/rate and {basePath}/summary.false | object
default:"{ paths: ['/openapi.json'] }"
OpenAPI enrichment.
false turns it off. See OpenAPI.What agents see
"soft" | "lifecycle"
default:"soft"
How the rating is asked for.
soft: “please rate this service for other agents”. lifecycle: describes this service’s flow as four steps (402, pay, response, rate). Both are soft asks. See Wording.boolean
default:"true"
Append the rating sentence to 402 challenge descriptions (v2 header, v1 JSON body).
string
Replace the sentence.
{rate_url} and {summary_url} are substituted. Text that presents the rating as required, makes anything depend on it, or asks for user data is refused with a warning, and the tone’s default is used.boolean
default:"true"
Add the
forge-feedback extension, with the real feedback_id, to the x402 v2 payment receipt (PAYMENT-RESPONSE). See Challenge and receipt.boolean | { searchQuery?: boolean }
default:"true"
Ask agents for self-reported agent context (
agent_type, client, search_query), record it with the call, and remove it before your code runs. { searchQuery: false } stops asking for the search query; false stops asking and recording. The fields are removed either way.boolean
default:"true"
Add
feedback_id and feedback_url to paid JSON object bodies.boolean | string
default:"true"
The
rate_this_call field in paid JSON bodies. A string replaces the wording ({feedback_url} and {summary_url} are substituted), false removes it.boolean
default:"false"
Append a two-line
feedback_id: … / feedback_url: … trailer to paid text/plain bodies. This changes your payload, so turn it on only when agents can’t see headers.Runtime
number
default:"86400000"
How long feedback IDs are accepted. Must match the backend’s
FEEDBACK_TTL_HOURS. Only used to reject stale IDs before a network call.number
default:"2000"
How often events are sent to the backend.
(error: unknown) => void
Called on internal errors. Default: a deduplicated
console.warn. Forge never throws into your request.typeof fetch
Custom fetch for backend calls (for tests or proxies).
boolean
default:"false"
Throw on invalid options. By default a misconfigured Forge logs one warning, reports the problem in
diagnostics() (enabled: false, configErrors) and passes everything through, so it can’t take down your API. Set strict in CI to fail the build instead. See Performance and reliability.Returned object
createForge (Express) returns:
createForgeCore returns the core API.