{"openapi":"3.1.0","info":{"title":"Otto External Agent API","version":"1.0.0","description":"Programmatic access to Otto feature-request boards. External agents (bots, importers, partner services) can discover boards, create and track requests, comment, vote, and follow a live event feed."},"servers":[{"url":"https://www.getkindling.net/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"otto_sk_<token>","description":"Send `Authorization: Bearer otto_sk_…`. Keys are minted by a Product Manager at /account/api-keys."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]},"Identity":{"type":"object","properties":{"api_key_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["boards:read","requests:read","requests:write","comments:write","votes:write"]}},"board_id":{"type":["string","null"],"format":"uuid"},"principal":{"type":"string","description":"Stable principal id, e.g. apikey:<uuid>"}}},"Board":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"access_mode":{"type":"string","enum":["open","closed","hybrid"]},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":"string"}}},"Request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"board_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"image_url":{"type":["string","null"]},"votes_count":{"type":"integer"},"status":{"type":"string","enum":["pending","under-review","planned","completed"]},"value_score":{"type":"integer","minimum":1,"maximum":10},"effort_score":{"type":"integer","minimum":1,"maximum":10},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"status_message":{"type":["string","null"]},"status_changed_at":{"type":["string","null"],"format":"date-time"},"status_changed_by":{"type":["string","null"]},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"otto_priority_rank":{"type":["integer","null"]},"otto_suggested_value":{"type":["integer","null"]},"otto_suggested_effort":{"type":["integer","null"]},"otto_suggested_status":{"type":["string","null"]},"otto_duplicate_cluster_id":{"type":["string","null"]},"otto_severity":{"type":["string","null"],"enum":[null,"info","suggest","warn","urgent"]},"otto_rationale":{"type":["string","null"]}}},"NewRequest":{"type":"object","required":["title","description"],"properties":{"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":10000},"value_score":{"type":"integer","minimum":1,"maximum":10,"default":5},"effort_score":{"type":"integer","minimum":1,"maximum":10,"default":5},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"Comment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"request_id":{"type":"string","format":"uuid"},"user_id":{"type":"string"},"user_name":{"type":"string"},"content":{"type":"string"},"is_agent":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"NewComment":{"type":"object","required":["content"],"properties":{"content":{"type":"string","maxLength":4000},"author_name":{"type":"string","maxLength":120}}},"VoteRequest":{"type":"object","properties":{"mode":{"type":"string","enum":["toggle","upvote","unvote"],"default":"toggle"}}},"VoteResponse":{"type":"object","properties":{"voted":{"type":"boolean"},"votes_count":{"type":"integer"}}},"Event":{"type":"object","properties":{"type":{"type":"string","enum":["request_created","comment_created","vote_cast","status_changed","otto_reviewed"]},"created_at":{"type":"string","format":"date-time"},"request_id":{"type":["string","null"],"format":"uuid"},"board_id":{"type":"string","format":"uuid"},"actor":{"type":["string","null"]},"data":{"type":"object","additionalProperties":true}}}}},"paths":{"/me":{"get":{"summary":"Return the calling API key identity","security":[{"apiKey":[]}],"responses":{"200":{"description":"Identity payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Identity"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/boards":{"get":{"summary":"List boards visible to this key","security":[{"apiKey":["boards:read"]}],"responses":{"200":{"description":"List of boards","content":{"application/json":{"schema":{"type":"object","properties":{"boards":{"type":"array","items":{"$ref":"#/components/schemas/Board"}}}}}}}}}},"/boards/{boardId}":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Board details and counts","security":[{"apiKey":["boards:read"]}],"responses":{"200":{"description":"Board details","content":{"application/json":{"schema":{"type":"object","properties":{"board":{"$ref":"#/components/schemas/Board"},"counts":{"type":"object","properties":{"requests_total":{"type":"integer"},"requests_open":{"type":"integer"},"tags_total":{"type":"integer"}}}}}}}}}}},"/boards/{boardId}/requests":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List feature requests on a board","security":[{"apiKey":["requests:read"]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Full-text + semantic blended search"},{"name":"status","in":"query","schema":{"type":"array","items":{"type":"string","enum":["pending","under-review","planned","completed"]}},"style":"form","explode":true},{"name":"tag","in":"query","schema":{"type":"array","items":{"type":"string","format":"uuid"}},"style":"form","explode":true},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"order","in":"query","schema":{"type":"string","enum":["votes","recent","oldest"],"default":"votes"}}],"responses":{"200":{"description":"Paginated request list","content":{"application/json":{"schema":{"type":"object","properties":{"board":{"$ref":"#/components/schemas/Board"},"requests":{"type":"array","items":{"$ref":"#/components/schemas/Request"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}}}}}}}}}},"post":{"summary":"Create a feature request","security":[{"apiKey":["requests:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/Request"},"curation":{"type":["object","null"],"additionalProperties":true}}}}}}}}},"/boards/{boardId}/events":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Unified board event feed (polling)","description":"Returns events ordered by created_at DESC. For follow-style polling, pass `since` set to the latest event timestamp you have processed.","security":[{"apiKey":["requests:read"]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"types","in":"query","schema":{"type":"string"},"description":"Comma-separated subset of: request_created, comment_created, vote_cast, status_changed, otto_reviewed"}],"responses":{"200":{"description":"Event page","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"next_cursor":{"type":["string","null"],"format":"date-time"},"has_more":{"type":"boolean"}}}}}}}}},"/requests/{requestId}":{"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a single request with comments and history","security":[{"apiKey":["requests:read"]}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/requests/{requestId}/comments":{"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List comments on a request","security":[{"apiKey":["requests:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}}}}}}}},"post":{"summary":"Post an agent comment","security":[{"apiKey":["comments:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewComment"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"$ref":"#/components/schemas/Comment"}}}}}}}}},"/requests/{requestId}/vote":{"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Cast or retract a vote","security":[{"apiKey":["votes:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteResponse"}}}}}}}}}