{"openapi":"3.1.0","info":{"title":"Emic Agent Feedback API","version":"1.0.0","description":"Direct user research for products whose users are AI agents. Submit structured reports about bugs, friction, missing capabilities, docs, schemas, workflows, and what worked.","license":{"name":"CC0-1.0 for the Agent Feedback field vocabulary","url":"https://creativecommons.org/publicdomain/zero/1.0/"}},"servers":[{"url":"https://emic.sh"}],"externalDocs":{"description":"Human-readable API and install reference","url":"https://emic.sh/docs/api"},"tags":[{"name":"Agent feedback","description":"Direct reports authored by an agent user."},{"name":"MCP feedback","description":"Compatibility adapter for the MCP feedback/submit proposal."}],"paths":{"/api/v1/feedback":{"post":{"operationId":"submitAgentFeedback","summary":"Submit direct feedback from an AI agent user","description":"Files one structured report. A successful ingest returns HTTP 201 and may include an exit survey prompt.","tags":["Agent feedback"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFeedbackInput"}}}},"responses":{"201":{"description":"Feedback accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackAccepted"}}}},"400":{"description":"Invalid JSON body"},"401":{"description":"Missing or invalid Bearer key or signature"},"402":{"description":"Workspace monthly quota exceeded"},"422":{"description":"Feedback failed validation"},"429":{"description":"Rate limit exceeded"}}}},"/api/mcp/feedback":{"post":{"operationId":"submitMcpFeedback","summary":"Submit MCP feedback/submit compatible feedback","description":"Accepts either a JSON-RPC 2.0 feedback/submit envelope or the proposal params object directly, then passes it through the canonical Emic ingest pipeline.","tags":["MCP feedback"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/McpFeedbackEnvelope"},{"$ref":"#/components/schemas/McpFeedbackParams"}]}}}},"responses":{"201":{"description":"Feedback accepted"},"400":{"description":"Invalid JSON body"},"401":{"description":"Missing or invalid Bearer key or signature"},"402":{"description":"Workspace monthly quota exceeded"},"404":{"description":"JSON-RPC method is not feedback/submit"},"422":{"description":"Feedback params failed validation"},"429":{"description":"Rate limit exceeded"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Emic ingest key"}},"schemas":{"AgentFeedbackInput":{"type":"object","additionalProperties":true,"required":["feedback_type","tool_or_endpoint"],"properties":{"feedback_type":{"type":"string","enum":["support_ticket","bug_or_failure","friction","feature_request","docs_feedback","schema_feedback","workflow_feedback","positive_feedback"],"description":"The direct agent feedback lane."},"tool_or_endpoint":{"type":"string","description":"The exact tool name or API endpoint the feedback is about."},"outcome":{"type":"string","enum":["success","partial_success","failure"]},"agent_goal":{"type":"string"},"task":{"type":"string"},"what_worked":{"type":"string"},"what_was_confusing":{"type":"string"},"what_was_missing":{"type":"string"},"what_would_improve_it":{"type":"string"},"expected_behavior":{"type":"string"},"actual_behavior":{"type":"string"},"error_message":{"type":"string"},"attempted_calls":{"type":"array","items":{"type":"string"},"maxItems":50},"failure_type":{"type":"string","enum":["missing_capability","confusing_schema","bad_tool_description","incomplete_response","incorrect_response","unhelpful_error","authentication_problem","pagination_or_truncation","rate_limit_or_timeout","docs_mismatch","wrong_tool_selected","other"]},"satisfaction_score":{"type":"integer","minimum":1,"maximum":5},"severity":{"type":"string","enum":["blocking","high","medium","low"]},"model":{"type":"string","description":"Self-declared model identity. It is unverified unless signed."},"source":{"type":"string","enum":["agent_authored","agent_solicited","server_observed","runtime_observed"],"default":"agent_authored"},"metadata":{"type":"object","additionalProperties":true,"description":"Optional non-sensitive metadata."}}},"FeedbackAccepted":{"type":"object","required":["ok","id","verified"],"properties":{"ok":{"type":"boolean","const":true},"id":{"type":"string"},"verified":{"type":"boolean"},"scrubbed":{"type":"array","items":{"type":"string"}},"survey_prompt":{"type":"string"},"survey_id":{"type":"string"}}},"McpFeedbackParams":{"type":"object","additionalProperties":true,"properties":{"category":{"type":"string","enum":["usability","reliability","documentation","efficiency","interoperability","capability_gap"]},"subcategory":{"type":"string"},"severity":{"type":"integer","minimum":1,"maximum":5},"summary":{"type":"string"},"description":{"type":"string"},"suggestion":{"type":"string"},"toolName":{"type":"string"},"serverName":{"type":"string"},"client":{"type":"object","additionalProperties":true}},"anyOf":[{"required":["summary"]},{"required":["description"]},{"required":["category"]}]},"McpFeedbackEnvelope":{"type":"object","required":["jsonrpc","method","params"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string","const":"feedback/submit"},"params":{"$ref":"#/components/schemas/McpFeedbackParams"}}}}}}