The Node SDK intercepts the merchant’s existing GET /openapi.json by default. Keep that handler mounted after Forge. Use openapi: { document } to serve a static document or openapi: { paths: ["/spec.json"] } for a different route.
The Python SDK intercepts /openapi.json by default. FastAPI’s payment middleware may not declare a 402 response in its schema; declare one for paid operations or pass OpenAPIOptions(is_paid_operation=...). For strict response schemas, provide the document and call forge.enrich_openapi(app.openapi()) before traffic so the SDK knows which bodies can safely receive fields. Supported Swagger 2.0 and OpenAPI 3.0–3.2 documents can gain a short guidance sentence for agents. Existing paths, payment requirements, prices, and shared schema components remain yours. Unsupported or ambiguous response schemas keep their original body. If agent context is on, its fields are described in the spec: optional with agentContext: true, required with { required: true }. Updating the spec does not update your runtime validators or clients. Agent context.