{"openapi":"3.1.0","info":{"title":"FeedbackBasket Public API","version":"1.0.0","description":"REST API for agents and integrations that manage FeedbackBasket projects, feedback, bugs, notes, replies, and teams. Use a private CLI bearer token for protected operations. Documented routes return RateLimit and RateLimit-Policy fields. Stable routes use major URL versions. The versioning and deprecation policy is at https://feedbackbasket.com/developers#versioning-and-deprecation.","contact":{"name":"FeedbackBasket support","email":"support@feedbackbasket.com"}},"servers":[{"url":"https://feedbackbasket.com","description":"Production"}],"x-versioning-policy":"https://feedbackbasket.com/developers#versioning-and-deprecation","x-feedbackbasket-agent-surface":{"version":"3.1.0","operationCount":31,"operations":[{"id":"projects.list","http":{"method":"GET","path":"/api/v1/projects","queryParameters":[]},"cli":["projects list"],"mcp":"list_projects","access":{"scope":"read:projects","projectScoped":false,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"projects.get","http":{"method":"GET","path":"/api/v1/projects/{projectId}","queryParameters":[]},"cli":["projects show"],"mcp":"get_project","access":{"scope":"read:projects","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"projects.create","http":{"method":"POST","path":"/api/v1/projects","queryParameters":[]},"cli":["projects create"],"mcp":"create_project","access":{"scope":"write:projects","projectScoped":false,"unrestrictedKeyRequired":true},"requiresConfirmation":false},{"id":"projects.update","http":{"method":"PATCH","path":"/api/v1/projects/{projectId}","queryParameters":[]},"cli":["projects update"],"mcp":"update_project","access":{"scope":"write:projects","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"projects.delete","http":{"method":"DELETE","path":"/api/v1/projects/{projectId}","queryParameters":[]},"cli":["projects delete"],"mcp":"delete_project","access":{"scope":"write:projects","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":true},{"id":"feedback.list","http":{"method":"GET","path":"/api/v1/feedback","queryParameters":[]},"cli":["feedback list"],"mcp":"get_feedback","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"feedback.get","http":{"method":"GET","path":"/api/v1/feedback/{feedbackId}","queryParameters":[]},"cli":["feedback show"],"mcp":"get_feedback_item","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"feedback.search","http":{"method":"GET","path":"/api/v1/feedback","queryParameters":[]},"cli":["feedback search"],"mcp":"search_feedback","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"feedback.create","http":{"method":"POST","path":"/api/v1/feedback","queryParameters":[]},"cli":["feedback create"],"mcp":"create_feedback","access":{"scope":"write:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"feedback.update","http":{"method":"PATCH","path":"/api/v1/feedback/{feedbackId}","queryParameters":[]},"cli":["feedback update"],"mcp":"update_feedback","access":{"scope":"write:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"feedback.delete","http":{"method":"DELETE","path":"/api/v1/feedback/{feedbackId}","queryParameters":[]},"cli":["feedback delete"],"mcp":"delete_feedback","access":{"scope":"write:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":true},{"id":"feedback.bulkUpdate","http":{"method":"POST","path":"/api/v1/feedback/bulk-update","queryParameters":[]},"cli":["feedback bulk-update"],"mcp":"bulk_update_feedback","access":{"scope":"write:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":true},{"id":"feedback.export","http":{"method":"GET","path":"/api/v1/projects/{projectId}/export","queryParameters":[]},"cli":["feedback export"],"mcp":"export_feedback","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"bugs.list","http":{"method":"GET","path":"/api/v1/feedback/bugs","queryParameters":[]},"cli":["bugs list"],"mcp":"get_bug_reports","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"bugs.stats","http":{"method":"GET","path":"/api/v1/feedback/bugs/stats","queryParameters":[]},"cli":["bugs stats"],"mcp":"get_bug_stats","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"notes.create","http":{"method":"POST","path":"/api/v1/feedback/{feedbackId}/notes","queryParameters":[]},"cli":["feedback note"],"mcp":"create_feedback_note","access":{"scope":"write:notes","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"notes.update","http":{"method":"PATCH","path":"/api/v1/feedback/{feedbackId}/notes/{noteId}","queryParameters":[]},"cli":["feedback note update"],"mcp":"update_feedback_note","access":{"scope":"write:notes","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"notes.delete","http":{"method":"DELETE","path":"/api/v1/feedback/{feedbackId}/notes/{noteId}","queryParameters":[]},"cli":["feedback note delete"],"mcp":"delete_feedback_note","access":{"scope":"write:notes","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":true},{"id":"replies.list","http":{"method":"GET","path":"/api/v1/feedback/{feedbackId}/replies","queryParameters":[]},"cli":["feedback replies"],"mcp":"list_feedback_replies","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"replies.send","http":{"method":"POST","path":"/api/v1/feedback/{feedbackId}/replies","queryParameters":[]},"cli":["feedback reply"],"mcp":"send_feedback_reply","access":{"scope":"write:replies","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":true},{"id":"widget.getSettings","http":{"method":"GET","path":"/api/v1/projects/{projectId}/widget","queryParameters":[]},"cli":["widget settings"],"mcp":"get_widget_settings","access":{"scope":"read:projects","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"widget.updateSettings","http":{"method":"PATCH","path":"/api/v1/projects/{projectId}/widget","queryParameters":[]},"cli":["widget update","widget flow"],"mcp":"update_widget_settings","access":{"scope":"write:widget","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"widget.getScript","http":{"method":"GET","path":"/api/v1/projects/{projectId}/widget-script","queryParameters":[]},"cli":["widget script"],"mcp":"get_widget_script","access":{"scope":"read:projects","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"mobile.get","http":{"method":"GET","path":"/api/v1/projects/{projectId}/mobile","queryParameters":[]},"cli":["mobile status","mobile verify"],"mcp":"get_mobile_integration","access":{"scope":"read:projects","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"mobile.update","http":{"method":"PATCH","path":"/api/v1/projects/{projectId}/mobile","queryParameters":["includePublishableKey"]},"cli":["mobile setup","mobile bundle","mobile conversations","mobile disable"],"mcp":"update_mobile_integration","access":{"scope":"write:mobile","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"mobile.rotateKey","http":{"method":"POST","path":"/api/v1/projects/{projectId}/mobile/rotate-key","queryParameters":["includePublishableKey"]},"cli":["mobile rotate-key"],"mcp":"rotate_mobile_project_key","access":{"scope":"write:mobile","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":true},{"id":"waitlist.list","http":{"method":"GET","path":"/api/v1/projects/{projectId}/waitlist","queryParameters":[]},"cli":["waitlist list"],"mcp":"get_waitlist","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"waitlist.export","http":{"method":"GET","path":"/api/v1/projects/{projectId}/waitlist/export","queryParameters":[]},"cli":["waitlist export"],"mcp":"export_waitlist","access":{"scope":"read:feedback","projectScoped":true,"unrestrictedKeyRequired":false},"requiresConfirmation":false},{"id":"team.list","http":{"method":"GET","path":"/api/v1/team","queryParameters":[]},"cli":["team list"],"mcp":"list_team_members","access":{"scope":"write:team","projectScoped":false,"unrestrictedKeyRequired":true},"requiresConfirmation":false},{"id":"team.updateRole","http":{"method":"PATCH","path":"/api/v1/team/{memberId}","queryParameters":[]},"cli":["team role"],"mcp":"update_team_member_role","access":{"scope":"write:team","projectScoped":false,"unrestrictedKeyRequired":true},"requiresConfirmation":true},{"id":"team.remove","http":{"method":"DELETE","path":"/api/v1/team/{memberId}","queryParameters":[]},"cli":["team remove"],"mcp":"remove_team_member","access":{"scope":"write:team","projectScoped":false,"unrestrictedKeyRequired":true},"requiresConfirmation":true}]},"security":[{"bearerAuth":[]}],"paths":{"/api/health":{"get":{"operationId":"getApiHealth","summary":"Check API availability","description":"Returns API status and links to machine-readable developer resources. This operation does not require authentication.","security":[],"responses":{"200":{"description":"The API is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/api/v1/projects":{"get":{"operationId":"listProjects","summary":"List projects","description":"Lists all projects available to the authenticated organization.","responses":{"200":{"description":"The organization's projects.","content":{"application/json":{"schema":{"type":"object","required":["projects","totalProjects"],"properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"totalProjects":{"type":"integer","minimum":0}}}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createProject","summary":"Create a project","description":"Creates a FeedbackBasket project. Full token scope and an administrator or owner role are required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"The created project.","content":{"application/json":{"schema":{"type":"object","required":["project"],"properties":{"project":{"$ref":"#/components/schemas/Project"}}}}}},"400":{"description":"The request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{id}":{"get":{"operationId":"getProject","summary":"Get a project","description":"Returns one project by its stable ID or unique project slug.","parameters":[{"name":"id","in":"path","required":true,"description":"Stable FeedbackBasket resource ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Project details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching project exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateProject","summary":"Update a project","description":"Updates project fields. Full token scope and an administrator or owner role are required.","parameters":[{"name":"id","in":"path","required":true,"description":"Stable FeedbackBasket resource ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"The updated project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching project exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteProject","summary":"Delete a project","description":"Deletes a project and its data. Full token scope and an administrator or owner role are required.","parameters":[{"name":"id","in":"path","required":true,"description":"Stable FeedbackBasket resource ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Deletion confirmation.","content":{"application/json":{"schema":{"type":"object","required":["deleted","id"],"properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching project exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feedback":{"get":{"operationId":"listFeedback","summary":"List feedback","description":"Lists feedback with optional project, category, status, sentiment, search, and pagination filters.","parameters":[{"name":"projectId","in":"query","description":"Stable project ID.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Feedback category.","schema":{"$ref":"#/components/schemas/FeedbackCategory"}},{"name":"status","in":"query","description":"Triage status.","schema":{"$ref":"#/components/schemas/FeedbackStatus"}},{"name":"search","in":"query","description":"Text to find in feedback content and summaries.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","description":"Number of records to skip.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of feedback.","content":{"application/json":{"schema":{"type":"object","required":["feedback","pagination"],"properties":{"feedback":{"type":"array","items":{"$ref":"#/components/schemas/Feedback"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFeedback","summary":"Create feedback","description":"Creates feedback in a project. Full token scope is required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","content"],"properties":{"projectId":{"type":"string","description":"Stable project ID."},"content":{"type":"string","minLength":1,"maxLength":2000},"email":{"type":"string","format":"email"},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"The created feedback and its dashboard URL.","content":{"application/json":{"schema":{"type":"object","required":["url","feedback"],"properties":{"url":{"type":"string","format":"uri"},"feedback":{"$ref":"#/components/schemas/Feedback"}}}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feedback/{id}":{"get":{"operationId":"getFeedback","summary":"Get feedback","description":"Returns one feedback item, its analysis, notes, and project context.","parameters":[{"name":"id","in":"path","required":true,"description":"Stable FeedbackBasket resource ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Feedback details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching feedback exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFeedback","summary":"Update feedback","description":"Updates triage fields such as status. Full token scope is required.","parameters":[{"name":"id","in":"path","required":true,"description":"Stable FeedbackBasket resource ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"status":{"$ref":"#/components/schemas/FeedbackStatus"}}}}}},"responses":{"200":{"description":"The updated feedback.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching feedback exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFeedback","summary":"Delete feedback","description":"Deletes one feedback item. Full token scope is required.","parameters":[{"name":"id","in":"path","required":true,"description":"Stable FeedbackBasket resource ID.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Deletion confirmation.","content":{"application/json":{"schema":{"type":"object","required":["deleted","id"],"properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching feedback exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feedback/bugs":{"get":{"operationId":"listBugs","summary":"List bug reports","description":"Lists feedback classified as bugs, with optional severity and project filters.","parameters":[{"name":"severity","in":"query","description":"Derived bug severity.","schema":{"type":"string","enum":["high","medium","low"]}}],"responses":{"200":{"description":"A page of bug reports with aggregate statistics.","content":{"application/json":{"schema":{"type":"object","required":["bugReports","stats","pagination"],"properties":{"bugReports":{"type":"array","items":{"$ref":"#/components/schemas/Feedback"}},"stats":{"type":"object","additionalProperties":true},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feedback/bugs/stats":{"get":{"operationId":"getBugStatistics","summary":"Get bug statistics","description":"Returns aggregate bug counts grouped by severity and status.","responses":{"200":{"description":"Bug statistics.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feedback/{id}/notes":{"post":{"operationId":"createFeedbackNote","summary":"Add a feedback note","description":"Adds an internal note to one feedback item. Full token scope is required.","parameters":[{"name":"id","in":"path","required":true,"description":"Stable FeedbackBasket resource ID.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":5000}}}}}},"responses":{"201":{"description":"The created note.","content":{"application/json":{"schema":{"type":"object","required":["id","content"],"properties":{"id":{"type":"string"},"content":{"type":"string"}}}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching feedback exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"fb_cli token","description":"Private FeedbackBasket CLI token. Do not expose it in client code or logs."}},"schemas":{"Error":{"type":"object","required":["ok","error","code","message","hint"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}}},"Health":{"type":"object","required":["ok","service","apiVersion","resources"],"properties":{"ok":{"type":"boolean","const":true},"service":{"type":"string","const":"FeedbackBasket"},"apiVersion":{"type":"string"},"resources":{"type":"object","required":["developers","openapi","llms","mcp"],"properties":{"developers":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"}}}}},"Project":{"type":"object","required":["id","name","url"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Feedback":{"type":"object","required":["id","content","status","category","createdAt"],"properties":{"id":{"type":"string"},"content":{"type":"string"},"summary":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"status":{"$ref":"#/components/schemas/FeedbackStatus"},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"sentiment":{"type":["string","null"],"enum":["POSITIVE","NEGATIVE","NEUTRAL",null]},"priority":{"type":["integer","null"],"minimum":0,"maximum":100},"createdAt":{"type":"string","format":"date-time"}}},"FeedbackCategory":{"type":"string","enum":["BUG","FEATURE_REQUEST","IMPROVEMENT","QUESTION"]},"FeedbackStatus":{"type":"string","enum":["OPEN","UNDER_REVIEW","PLANNED","IN_PROGRESS","COMPLETE","CLOSED"]},"Pagination":{"type":"object","required":["totalCount","limit","offset","hasMore"],"properties":{"totalCount":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0},"hasMore":{"type":"boolean"}}}}},"externalDocs":{"description":"FeedbackBasket developer platform","url":"https://feedbackbasket.com/developers"}}