{"openapi":"3.1.0","info":{"title":"Rove API","version":"0.0.1","description":"The Rove API: Topics, Sessions and Facts over HTTP. Most teams connect through MCP instead, which uses the same operations; this is for scripts and custom integrations. Authenticate with a personal access token as Authorization: Bearer <token>."},"paths":{"/v1/me":{"get":{"tags":["Identity"],"summary":"Who am I","operationId":"get_me_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}}},"description":"The user the token belongs to, the workspace the request acts in, and every workspace you belong to. A quick way to check a token works."}},"/v1/topics":{"post":{"tags":["Topics"],"summary":"Create a Topic","operationId":"create_topic_v1_topics_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTopicRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Topic"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"A Topic is one problem, feature or investigation. Sessions and Facts are added to it. You become its owner."},"get":{"tags":["Topics"],"summary":"List Topics","operationId":"list_topics_v1_topics_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicPage"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Topics you can see in the workspace, newest first, a page at a time."}},"/v1/topics/{topic_id}":{"get":{"tags":["Topics"],"summary":"Get a Topic","operationId":"get_topic_v1_topics__topic_id__get","parameters":[{"name":"topic_id","in":"path","required":true,"schema":{"type":"string","title":"Topic Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Topic"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"One Topic, with how many Sessions and Facts it holds and your role on it."}},"/v1/topics/{topic_id}/sessions":{"post":{"tags":["Sessions"],"summary":"Check in a Session","description":"Add one unit of work to a Topic: what was found, what was ruled out, what's next. Sessions are immutable and numbered in order. This is how work is handed off: whoever picks it up reads the Topic's Sessions.","operationId":"upload_session_v1_topics__topic_id__sessions_post","parameters":[{"name":"topic_id","in":"path","required":true,"schema":{"type":"string","title":"Topic Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSessionRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Sessions"],"summary":"List a Topic's Sessions","operationId":"list_sessions_v1_topics__topic_id__sessions_get","parameters":[{"name":"topic_id","in":"path","required":true,"schema":{"type":"string","title":"Topic Id"}},{"name":"after_sequence","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Return sequences above this","default":0,"title":"After Sequence"},"description":"Return sequences above this"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionPage"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"The Topic's Sessions in order. To pick up a handoff, read them from the start; to catch up, pass the last sequence number you read and get only what came after."}},"/v1/sessions/{session_id}":{"get":{"tags":["Sessions"],"summary":"Get a Session","operationId":"get_session_v1_sessions__session_id__get","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"One Session by its id."}},"/v1/topics/{topic_id}/facts":{"get":{"tags":["Facts"],"summary":"Get a Topic's Facts","operationId":"get_facts_v1_topics__topic_id__facts_get","parameters":[{"name":"topic_id","in":"path","required":true,"schema":{"type":"string","title":"Topic Id"}},{"name":"include_retired","in":"query","required":false,"schema":{"type":"boolean","description":"Return the whole annotated log, not just what stands","default":false,"title":"Include Retired"},"description":"Return the whole annotated log, not just what stands"},{"name":"after_sequence","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Return facts above this sequence","default":0,"title":"After Sequence"},"description":"Return facts above this sequence"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactSheet"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"What the Topic currently holds to be true: decisions, dead ends and open questions, one sentence each. Facts that were later corrected are left out unless you ask for them."},"post":{"tags":["Facts"],"summary":"Add a Fact","description":"Record one conclusion from the work. Facts are never edited: to correct one, add a Fact that supersedes or retracts it.","operationId":"add_fact_v1_topics__topic_id__facts_post","parameters":[{"name":"topic_id","in":"path","required":true,"schema":{"type":"string","title":"Topic Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFactRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fact"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/context/find":{"post":{"tags":["Search"],"summary":"Find prior context","description":"Before starting work, describe it in a sentence and get back the Sessions most worth reading, across every Topic you can see, with why each matched.","operationId":"find_context_v1_context_find_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindContextRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBundle"}}}},"404":{"description":"Not found in the caller's scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AddFactRequest":{"properties":{"verb":{"$ref":"#/components/schemas/FactVerb"},"statement":{"type":"string","maxLength":280,"minLength":1,"title":"Statement"},"target":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Target"},"source_session":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Source Session"}},"additionalProperties":false,"type":"object","required":["verb","statement"],"title":"AddFactRequest"},"AnnotatedFact":{"properties":{"fact":{"$ref":"#/components/schemas/Fact"},"standing":{"type":"boolean","title":"Standing"},"in_force":{"type":"boolean","title":"In Force","default":true},"superseded_by":{"items":{"type":"integer"},"type":"array","title":"Superseded By"},"retracted_by":{"items":{"type":"integer"},"type":"array","title":"Retracted By"},"answered_by":{"items":{"type":"integer"},"type":"array","title":"Answered By"},"confirmed_by":{"items":{"type":"integer"},"type":"array","title":"Confirmed By"}},"type":"object","required":["fact","standing"],"title":"AnnotatedFact"},"ContextBundle":{"properties":{"task":{"type":"string","title":"Task"},"topics":{"items":{"$ref":"#/components/schemas/Topic"},"type":"array","title":"Topics"},"sessions":{"items":{"$ref":"#/components/schemas/ScoredSession"},"type":"array","title":"Sessions"},"considered":{"type":"integer","title":"Considered"},"budget_exhausted":{"type":"boolean","title":"Budget Exhausted","default":false},"candidates_truncated":{"type":"boolean","title":"Candidates Truncated","default":false}},"type":"object","required":["task","topics","sessions","considered"],"title":"ContextBundle"},"CreateTopicRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Description"},"workspace_access":{"anyOf":[{"$ref":"#/components/schemas/TopicRole"},{"type":"null"}],"default":"editor"}},"additionalProperties":false,"type":"object","required":["name"],"title":"CreateTopicRequest"},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error"},"message":{"type":"string","title":"Message"}},"type":"object","required":["error","message"],"title":"ErrorResponse"},"Fact":{"properties":{"fact_id":{"type":"string","title":"Fact Id"},"topic_id":{"type":"string","title":"Topic Id"},"sequence_number":{"type":"integer","title":"Sequence Number"},"verb":{"$ref":"#/components/schemas/FactVerb"},"statement":{"type":"string","title":"Statement"},"target":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Target"},"source_session":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Source Session"},"created_by":{"type":"string","title":"Created By"},"asserted_at":{"type":"string","format":"date-time","title":"Asserted At"}},"type":"object","required":["fact_id","topic_id","sequence_number","verb","statement","created_by","asserted_at"],"title":"Fact"},"FactSheet":{"properties":{"topic_id":{"type":"string","title":"Topic Id"},"facts":{"items":{"$ref":"#/components/schemas/AnnotatedFact"},"type":"array","title":"Facts"},"standing_count":{"type":"integer","title":"Standing Count"},"total":{"type":"integer","title":"Total"},"include_retired":{"type":"boolean","title":"Include Retired","default":false}},"type":"object","required":["topic_id","facts","standing_count","total"],"title":"FactSheet"},"FactVerb":{"type":"string","enum":["asserts","observed","decided","ruled_out","open_question","supersedes","retracts","answers","confirms"],"title":"FactVerb"},"FindContextRequest":{"properties":{"task":{"type":"string","maxLength":4000,"minLength":1,"title":"Task"},"topic_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic Id"},"tags":{"items":{"type":"string"},"type":"array","maxItems":32,"title":"Tags"},"limit":{"type":"integer","maximum":25.0,"minimum":1.0,"title":"Limit","default":5},"budget_chars":{"type":"integer","maximum":200000.0,"minimum":500.0,"title":"Budget Chars","default":12000}},"additionalProperties":false,"type":"object","required":["task"],"title":"FindContextRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Me":{"properties":{"user":{"$ref":"#/components/schemas/User"},"workspace":{"anyOf":[{"$ref":"#/components/schemas/Workspace"},{"type":"null"}]},"role":{"anyOf":[{"$ref":"#/components/schemas/TenantRole"},{"type":"null"}]},"teams":{"items":{"$ref":"#/components/schemas/Team"},"type":"array","title":"Teams"},"workspaces":{"items":{"$ref":"#/components/schemas/WorkspaceMembership"},"type":"array","title":"Workspaces"}},"type":"object","required":["user","workspace","role","teams","workspaces"],"title":"Me"},"ScoredSession":{"properties":{"session":{"$ref":"#/components/schemas/Session"},"score":{"type":"number","title":"Score"},"reason":{"type":"string","title":"Reason"},"text_truncated":{"type":"boolean","title":"Text Truncated","default":false},"superseded_by":{"items":{"$ref":"#/components/schemas/Supersession"},"type":"array","title":"Superseded By"},"later_in_topic":{"type":"integer","title":"Later In Topic","default":0}},"type":"object","required":["session","score","reason"],"title":"ScoredSession"},"Session":{"properties":{"session_id":{"type":"string","title":"Session Id"},"topic_id":{"type":"string","title":"Topic Id"},"sequence_number":{"type":"integer","title":"Sequence Number"},"title":{"type":"string","title":"Title"},"text":{"type":"string","title":"Text"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"schema_version":{"type":"integer","title":"Schema Version"},"created_by":{"type":"string","title":"Created By"},"checked_in_at":{"type":"string","format":"date-time","title":"Checked In At"},"supersedes":{"items":{"type":"integer"},"type":"array","title":"Supersedes"}},"type":"object","required":["session_id","topic_id","sequence_number","title","text","tags","schema_version","created_by","checked_in_at"],"title":"Session"},"SessionPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Session"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["items"],"title":"SessionPage"},"Supersession":{"properties":{"sequence_number":{"type":"integer","title":"Sequence Number"},"retracted_by":{"items":{"type":"integer"},"type":"array","title":"Retracted By"}},"type":"object","required":["sequence_number"],"title":"Supersession"},"Team":{"properties":{"team_id":{"type":"string","title":"Team Id"},"name":{"type":"string","title":"Name"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["team_id","name","created_by","created_at"],"title":"Team"},"TenantRole":{"type":"string","enum":["admin","member"],"title":"TenantRole"},"Topic":{"properties":{"topic_id":{"type":"string","title":"Topic Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"workspace_access":{"anyOf":[{"$ref":"#/components/schemas/TopicRole"},{"type":"null"}]},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"latest_sequence_number":{"type":"integer","title":"Latest Sequence Number","default":0},"latest_fact_sequence":{"type":"integer","title":"Latest Fact Sequence","default":0},"your_role":{"anyOf":[{"$ref":"#/components/schemas/TopicRole"},{"type":"null"}]}},"type":"object","required":["topic_id","name","created_by","created_at"],"title":"Topic"},"TopicPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Topic"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["items"],"title":"TopicPage"},"TopicRole":{"type":"string","enum":["viewer","editor","owner"],"title":"TopicRole"},"UploadSessionRequest":{"properties":{"schema_version":{"type":"integer","title":"Schema Version","default":1},"title":{"type":"string","maxLength":200,"minLength":1,"title":"Title"},"text":{"type":"string","maxLength":200000,"minLength":1,"title":"Text"},"tags":{"items":{"type":"string"},"type":"array","maxItems":32,"title":"Tags"},"supersedes":{"items":{"type":"integer"},"type":"array","maxItems":32,"title":"Supersedes"}},"additionalProperties":false,"type":"object","required":["title","text"],"title":"UploadSessionRequest"},"User":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"type":"string","title":"Email"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["user_id","email","created_at"],"title":"User"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Workspace":{"properties":{"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["workspace_id","name","created_at"],"title":"Workspace"},"WorkspaceMembership":{"properties":{"workspace":{"$ref":"#/components/schemas/Workspace"},"role":{"$ref":"#/components/schemas/TenantRole"}},"type":"object","required":["workspace","role"],"title":"WorkspaceMembership"}},"securitySchemes":{"token":{"type":"http","scheme":"bearer"}}},"security":[{"token":[]}],"tags":[{"name":"Identity"},{"name":"Topics"},{"name":"Sessions"},{"name":"Facts"},{"name":"Search"}]}