{"openapi":"3.1.0","info":{"title":"Runheed API","version":"1.0.0","description":"Report errors from any language (ingest) and read or resolve them (the API the Runheed MCP server uses). Setup: https://runheed.com/docs","contact":{"email":"hello@greatwork.company"}},"servers":[{"url":"https://runheed.com"}],"components":{"securitySchemes":{"projectKey":{"type":"apiKey","in":"header","name":"X-Runheed-Key","description":"The pk_... part of a project DSN. Authorization: Bearer pk_... also works."},"agentKey":{"type":"http","scheme":"bearer","description":"Agent key (al_...) from Settings > Agent keys."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"What happened and what to do next"},"code":{"type":"string"},"fix_url":{"type":"string","format":"uri"}},"required":["error"]},"Frame":{"type":"object","properties":{"filename":{"type":"string"},"function":{"type":"string"},"lineno":{"type":"integer"},"colno":{"type":"integer"},"inApp":{"type":"boolean"},"context":{"type":"array","items":{"type":"string"}}}},"Event":{"type":"object","required":["errorType","errorMessage"],"properties":{"errorType":{"type":"string","maxLength":500,"description":"e.g. TypeError"},"errorMessage":{"type":"string","maxLength":10000},"stacktrace":{"type":"array","items":{"$ref":"#/components/schemas/Frame"}},"platform":{"type":"string"},"runtime":{"type":"string"},"os":{"type":"string"},"environment":{"type":"string","description":"e.g. production"},"release":{"type":"string","description":"e.g. a git sha"},"agent":{"type":"object","description":"Which coding agent shipped the code","properties":{"name":{"type":"string"},"version":{"type":"string"},"sessionId":{"type":"string"},"action":{"type":"string"},"toolName":{"type":"string"}}},"request":{"type":"object","properties":{"method":{"type":"string"},"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Authorization, cookie and API-key headers are redacted on arrival"}}},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"ip":{"type":"string"}}},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"category":{"type":"string"},"message":{"type":"string"},"level":{"type":"string"},"data":{"type":"object"}}}},"extra":{"type":"object"},"timestamp":{"type":"string","format":"date-time"},"fingerprint":{"type":"array","items":{"type":"string"},"description":"Override grouping"}}},"ErrorGroup":{"type":"object","properties":{"id":{"type":"string"},"errorType":{"type":"string"},"errorMessage":{"type":"string"},"status":{"type":"string","enum":["unresolved","resolved","ignored","muted"]},"eventCount":{"type":"integer"},"firstSeen":{"type":"string"},"lastSeen":{"type":"string"},"projectName":{"type":"string"}}}}},"paths":{"/api/ingest":{"post":{"summary":"Report one error event","security":[{"projectKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Stored (or sampled out when sampled is false)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["string","null"]},"groupId":{"type":"string"},"sampled":{"type":"boolean"},"isNew":{"type":"boolean"},"quotaUsed":{"type":"number","description":"Percent of the monthly events used"}}}}}},"400":{"description":"Invalid JSON or event format (details included).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown project key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The project is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly event limit reached, or more than 300 events a minute for this project (Retry-After: 60).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Health check","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}},"/api/mcp/errors":{"get":{"summary":"Search error groups","security":[{"agentKey":[]}],"parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["unresolved","resolved","ignored"]}},{"name":"projectId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":20}},{"name":"sort","in":"query","schema":{"type":"string","default":"recent"}}],"responses":{"200":{"description":"Matching groups","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorGroup"}}}}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/errors/{id}":{"get":{"summary":"Error detail: stack trace, breadcrumbs, agent context","security":[{"agentKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Error group id"}],"responses":{"200":{"description":"Error group with its latest event","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No error with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/errors/{id}/context":{"get":{"summary":"Environment, user, agent, breadcrumbs and extra data","security":[{"agentKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Error group id"}],"responses":{"200":{"description":"Context","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No error with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/errors/{id}/resolve":{"post":{"summary":"Mark resolved, with an optional comment such as the fixing commit","security":[{"agentKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Error group id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"string"}}}}}},"responses":{"200":{"description":"Resolved","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No error with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/errors/{id}/ignore":{"post":{"summary":"Ignore an error","security":[{"agentKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Error group id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Ignored","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No error with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/errors/{id}/unignore":{"post":{"summary":"Stop ignoring an error","security":[{"agentKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Error group id"}],"responses":{"200":{"description":"Unignored","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No error with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/trends":{"get":{"summary":"Counts and top errors","security":[{"agentKey":[]}],"parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["24h","7d","30d"]}},{"name":"projectId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Trends","content":{"application/json":{"schema":{"type":"object","properties":{"totalErrors":{"type":"integer"},"newErrors":{"type":"integer"},"resolvedErrors":{"type":"integer"},"topErrors":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/health":{"get":{"summary":"Project health score (0 to 100) with recommendations","security":[{"agentKey":[]}],"parameters":[{"name":"projectId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Health","content":{"application/json":{"schema":{"type":"object","properties":{"healthScore":{"type":"integer"},"errors24h":{"type":"integer"},"unresolvedCount":{"type":"integer"},"recommendations":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing, unknown or revoked agent key, or a project key (pk_) used where an agent key (al_) is needed. `code` and `fix_url` say which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace has no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}