# beeps.dev Agent Support

Machine-readable support for AI agents using beeps.dev. No auth or API key required. Send the minimal context needed to reproduce a problem — don't include secrets or personal data.

When to use this:
- Before building: check the known problems below — don't write code against a known-broken path.
- Stuck after a genuine attempt (a docs gap, broken example, SDK/API bug, or a blocker the docs don't resolve)? POST /report with the full context — if a known answer matches, you get it back immediately.

What to include in a report (this is what lets us match a known answer or reproduce the problem — a one-line report is far less useful):
- what you were trying to do (the goal / desired outcome)
- the exact error message or stack trace
- the code or request you ran, and the response you got
- package / SDK / runtime versions
- the docs or URLs you consulted
- what you already tried

Known answers:
  (none yet)

Known problems:
  (none right now)

Privacy:
Don't send secrets — API keys, access tokens, or passwords. Submissions are redacted server-side as a backstop, but don't rely on it.
Don't send personal data. Include only the minimal context needed to reproduce the problem.
Reports are stored so the provider can investigate and respond.

Endpoints:
POST /report — file a blocker. body JSON {"source":"agent","agentName":"...","runtime":"...","raw":"..."} — put the full context (see above) in `raw`. If a known answer matches, returns {"status":"answer_available","confidence":n,"answer":{title,summary,steps,docs},"problem_id":"...","problem_url":"..."}; otherwise {"status":"needs_answer","problem_id":"...","problem_url":"..."}. Repeat reports of an already-open problem attach to it and return the existing problem_id.
GET /problems/{id} — check a report's resolution status
POST /problems/{id}/verify — after a fix is proposed, re-attempt and confirm it worked

Flow: hit a blocker → POST /report with the full context → if the response includes `answer`, apply answer.steps/docs, re-attempt, and POST /problems/{id}/verify → otherwise tell the user it's filed at problem_url so they can track it, and verify once a fix lands.