{"success":true,"tool":"report_bug","version":"2026-06-11-bridge-v6","description":"Create or update a Proof bug report through one HTTP bridge tool call.","method":"POST","auth":"none","endpoint":"https://www.proofeditor.ai/api/bridge/report_bug","paths":{"canonical":"/api/bridge/report_bug","docAwareAlias":"/d/:slug/bridge/report_bug"},"guidance":{"summary":"Call POST /api/bridge/report_bug with what you know. If the response says needs_more_info, ask the suggested questions and call it again. If you need to append context later, call the same endpoint with issueNumber.","slugContext":"Provide slug when you want server/document evidence enrichment.","non2xxRule":"Only transport, auth, or server failures use non-2xx responses. Missing bug details return 200 with status=needs_more_info.","unavailableRule":"A 503 means the server-side tracker integration is not configured. Your evidence is still captured locally; report the outage to a human instead of retrying immediately.","partialFailureRule":"A 502 that includes issueNumber means the issue was created but attaching evidence failed. Do not re-submit the report; call the same endpoint again with that issueNumber to append the evidence.","bestEvidenceExamples":["Exact request URL, method, status, and x-request-id for the failing call","Whether retrying once changed the outcome (for example: timed out twice, or second try succeeded)","Document slug and whether it was a homepage, library, shared doc, state read, collab refresh, or write path","A short timeline with timestamps, such as page loaded at 12:03:10, write timed out at 12:03:18, retry succeeded at 12:03:31","Raw response body or console/network error text instead of a summary"]},"input":{"required":["summary or context","evidence or requestId/slug"],"fields":{"by":"Stable agent identity (ai:<agent-name>). Used to attribute the report to you in the tracker.","user":"Optional affected human: {\"name\":\"...\",\"email\":\"...\"}. Ask the user first (\"May I include your name/email so the team can follow up when this is fixed?\") and only include it with their consent. Never guess or harvest contact details.","summary":"One-line bug summary when you have it.","actual":"What happened.","expected":"What should have happened.","repro":"Steps to reproduce, if known.","context":"Free-form narrative for everything that does not fit the structured fields.","evidence":"Raw evidence blobs. The server classifies them for the fixer.","requestId":"Optional x-request-id for server trace lookup.","occurredAt":"Optional ISO timestamp for narrowing the evidence window.","slug":"Optional document slug on the top-level path.","issueNumber":"When present, the same tool appends follow-up context to an existing issue.","followUp":"Explicit follow-up text when issueNumber is present."},"evidenceKinds":["http_request","http_response","error","console","operator_note","raw_json"]},"response":{"statuses":["created","needs_more_info","follow_up_added"],"fields":["missingFields","suggestedQuestions","nextBestEvidence","evidenceSummary","fixerBrief","issueNumber","issueIdentifier","issueUrl"]},"openSourceReference":{"name":"EveryInc/proof-sdk","url":"https://github.com/EveryInc/proof-sdk","guidance":"If you want reference code while debugging, you can inspect this repo while preparing the report. It is a point-in-time snapshot that lags the hosted product (routes and error codes may differ): verify the bug against proofeditor.ai before filing, and never report a locally run proof-sdk server as a production bug."},"examples":{"minimal":{"summary":"v3 edit returned 500 while inserting a mark","context":"I was trying to add a mark to the selected text and the first write failed.","evidence":[{"kind":"http_response","method":"POST","url":"https://www.proofeditor.ai/api/agent/example/v3/edit","status":500,"requestId":"example-request-id","data":{"responseBody":{"error":"Internal Server Error"}}}]},"needsMoreInfo":{"context":"Something weird happened after I clicked publish."},"followUp":{"issueNumber":42,"followUp":"Tried again with a single mark and it still failed.","evidence":[{"kind":"http_response","method":"POST","url":"https://www.proofeditor.ai/api/agent/example/v3/edit","status":500,"requestId":"example-request-id"}]}},"curlExamples":{"create":"curl -X POST https://www.proofeditor.ai/api/bridge/report_bug -H 'content-type: application/json' -d '{\"summary\":\"v3 edit returned 500\",\"context\":\"I tried to insert a mark and the first write failed.\",\"evidence\":[{\"kind\":\"http_response\",\"method\":\"POST\",\"url\":\"https://www.proofeditor.ai/api/agent/example/v3/edit\",\"status\":500,\"requestId\":\"example-request-id\"}]}'","followUp":"curl -X POST https://www.proofeditor.ai/api/bridge/report_bug -H 'content-type: application/json' -d '{\"issueNumber\":42,\"followUp\":\"Tried again with a single mark and it still failed.\"}'"}}