{"openapi":"3.1.0","info":{"title":"vithos API","version":"0.1.0-canary.8","description":"The public vithos email API. Same capabilities as the command palette; the MCP server at /mcp exposes the same tools."},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{},"parameters":{}},"paths":{"/v1/me":{"get":{"security":[{"apiKey":[]}],"responses":{"200":{"description":"The authenticated principal","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"via":{"type":"string","enum":["session","api-key"]},"scopes":{"type":"array","items":{"type":"string","enum":["read","write","send"]}},"billing":{"type":"object","properties":{"plan":{"type":"string","enum":["free","pro","team"]},"status":{"type":"string","enum":["free","trialing","active","past_due","canceled"]},"interval":{"type":"string","nullable":true,"enum":["month","year",null],"default":null},"trialEndsAt":{"type":"integer","nullable":true},"periodEnd":{"type":"integer","nullable":true}},"required":["plan","status","trialEndsAt","periodEnd"]}},"required":["userId","via","scopes","billing"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/featurebase/token":{"get":{"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"appVersion","in":"query"},{"schema":{"type":"string"},"required":false,"name":"channel","in":"query"},{"schema":{"type":"string"},"required":false,"name":"platform","in":"query"}],"responses":{"200":{"description":"Short-lived Featurebase identity JWT","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1},"expiresAt":{"type":"integer"}},"required":["token","expiresAt"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Featurebase JWT secret not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/billing/checkout":{"post":{"security":[{"apiKey":[]}],"responses":{"200":{"description":"Polar hosted checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Billing not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/billing/change":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"interval":{"type":"string","enum":["month","year"]}},"required":["interval"]}}}},"responses":{"200":{"description":"Subscription switched","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Billing not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/onboarding/welcome":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountEmail":{"type":"string","format":"email"}},"required":["accountEmail"]}}}},"responses":{"200":{"description":"Welcome email sent","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"}},"required":["sent"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Email sending not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/billing/portal":{"get":{"security":[{"apiKey":[]}],"responses":{"200":{"description":"Polar customer portal URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Billing not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/accounts":{"get":{"security":[{"apiKey":[]}],"responses":{"200":{"description":"Gmail accounts linked to this user","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["gmail"]},"email":{"type":"string"},"displayName":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"historyId":{"type":"string","nullable":true},"linkedAt":{"type":"integer"}},"required":["id","provider","email","displayName","avatarUrl","historyId","linkedAt"]}}},"required":["accounts"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/accounts/{accountId}/token":{"get":{"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"accountId","in":"path"}],"responses":{"200":{"description":"Short-lived Gmail access token for desktop sync","content":{"application/json":{"schema":{"type":"object","properties":{"accessToken":{"type":"string","minLength":1},"expiresAt":{"type":"integer","nullable":true}},"required":["accessToken","expiresAt"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/accounts/{accountId}":{"delete":{"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path"}],"responses":{"200":{"description":"Google link removed for this inbox","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"unlinked":{"type":"boolean"}},"required":["ok","unlinked"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/search":{"get":{"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Matching threads, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"subject":{"type":"string"},"snippet":{"type":"string"},"lastMessageAt":{"type":"integer"},"messageIds":{"type":"array","items":{"type":"string"}},"participants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"unreadCount":{"type":"integer","minimum":0},"starred":{"type":"boolean"},"labelIds":{"type":"array","items":{"type":"string"}},"waitingOn":{"type":"boolean"},"followUpAt":{"type":"integer","nullable":true}},"required":["id","accountId","subject","snippet","lastMessageAt","messageIds","participants","unreadCount","starred","labelIds","waitingOn","followUpAt"]}}},"required":["threads"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/threads/{threadId}":{"get":{"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"threadId","in":"path"}],"responses":{"200":{"description":"The thread with normalized plain-text messages","content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"subject":{"type":"string"},"snippet":{"type":"string"},"lastMessageAt":{"type":"integer"},"messageIds":{"type":"array","items":{"type":"string"}},"participants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"unreadCount":{"type":"integer","minimum":0},"starred":{"type":"boolean"},"labelIds":{"type":"array","items":{"type":"string"}},"waitingOn":{"type":"boolean"},"followUpAt":{"type":"integer","nullable":true}},"required":["id","accountId","subject","snippet","lastMessageAt","messageIds","participants","unreadCount","starred","labelIds","waitingOn","followUpAt"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"threadId":{"type":"string"},"from":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"to":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"cc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"bcc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"replyTo":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"listId":{"type":"string","nullable":true},"subject":{"type":"string"},"snippet":{"type":"string"},"bodyText":{"type":"string"},"date":{"type":"integer"},"unread":{"type":"boolean"},"starred":{"type":"boolean"},"labelIds":{"type":"array","items":{"type":"string"}},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"emailId":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"inline":{"type":"boolean"}},"required":["id","accountId","emailId","filename","mimeType","sizeBytes","inline"]}}},"required":["id","accountId","threadId","from","to","cc","bcc","replyTo","listId","subject","snippet","bodyText","date","unread","starred","labelIds","attachments"]}}},"required":["thread","messages"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/labels":{"get":{"security":[{"apiKey":[]}],"responses":{"200":{"description":"All labels","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["system","user"]},"color":{"type":"string","nullable":true}},"required":["id","accountId","name","kind","color"]}}},"required":["labels"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/labels/set":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string"},"labelId":{"type":"string"},"on":{"type":"boolean"}},"required":["threadId","labelId","on"]}}}},"responses":{"200":{"description":"The updated thread","content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"subject":{"type":"string"},"snippet":{"type":"string"},"lastMessageAt":{"type":"integer"},"messageIds":{"type":"array","items":{"type":"string"}},"participants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"unreadCount":{"type":"integer","minimum":0},"starred":{"type":"boolean"},"labelIds":{"type":"array","items":{"type":"string"}},"waitingOn":{"type":"boolean"},"followUpAt":{"type":"integer","nullable":true}},"required":["id","accountId","subject","snippet","lastMessageAt","messageIds","participants","unreadCount","starred","labelIds","waitingOn","followUpAt"]}},"required":["thread"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/waiting-on":{"get":{"security":[{"apiKey":[]}],"responses":{"200":{"description":"Threads marked Waiting On","content":{"application/json":{"schema":{"type":"object","properties":{"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"subject":{"type":"string"},"snippet":{"type":"string"},"lastMessageAt":{"type":"integer"},"messageIds":{"type":"array","items":{"type":"string"}},"participants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"unreadCount":{"type":"integer","minimum":0},"starred":{"type":"boolean"},"labelIds":{"type":"array","items":{"type":"string"}},"waitingOn":{"type":"boolean"},"followUpAt":{"type":"integer","nullable":true}},"required":["id","accountId","subject","snippet","lastMessageAt","messageIds","participants","unreadCount","starred","labelIds","waitingOn","followUpAt"]}}},"required":["threads"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/drafts":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"threadId":{"type":"string","nullable":true,"default":null},"to":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"minItems":1},"cc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"default":[]},"bcc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"default":[]},"subject":{"type":"string"},"bodyMarkdown":{"type":"string"}},"required":["accountId","to","subject","bodyMarkdown"]}}}},"responses":{"200":{"description":"The created draft","content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"threadId":{"type":"string","nullable":true},"to":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"cc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"bcc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"subject":{"type":"string"},"bodyMarkdown":{"type":"string"},"inReplyToEmailId":{"type":"string","nullable":true},"updatedAt":{"type":"integer"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"path":{"type":"string"}},"required":["id","filename","mimeType","sizeBytes","path"]}}},"required":["id","accountId","threadId","to","cc","bcc","subject","bodyMarkdown","inReplyToEmailId","updatedAt","attachments"]}},"required":["draft"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/send":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"threadId":{"type":"string","nullable":true,"default":null},"to":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"minItems":1},"cc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"default":[]},"bcc":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"default":[]},"subject":{"type":"string"},"bodyMarkdown":{"type":"string"}},"required":["accountId","to","subject","bodyMarkdown"]}}}},"responses":{"200":{"description":"Accepted for delivery","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["accepted","id"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/followups":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string"},"remindAt":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["threadId","remindAt"]}}}},"responses":{"200":{"description":"The updated thread","content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"subject":{"type":"string"},"snippet":{"type":"string"},"lastMessageAt":{"type":"integer"},"messageIds":{"type":"array","items":{"type":"string"}},"participants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]}},"unreadCount":{"type":"integer","minimum":0},"starred":{"type":"boolean"},"labelIds":{"type":"array","items":{"type":"string"}},"waitingOn":{"type":"boolean"},"followUpAt":{"type":"integer","nullable":true}},"required":["id","accountId","subject","snippet","lastMessageAt","messageIds","participants","unreadCount","starred","labelIds","waitingOn","followUpAt"]}},"required":["thread"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/keys":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"scopes":{"type":"array","items":{"type":"string","enum":["read","write","send"]},"minItems":1,"default":["read"]}},"required":["name"]}}}},"responses":{"200":{"description":"The created API key; the raw key is shown exactly once","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write","send"]}}},"required":["id","key","scopes"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/ai/enrich":{"post":{"security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountEmail":{"type":"string","minLength":3},"emailId":{"type":"string","minLength":1},"threadId":{"type":"string","minLength":1},"subject":{"type":"string","maxLength":1000},"from":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"to":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["name","email"]},"maxItems":20,"default":[]},"listId":{"type":"string","nullable":true,"default":null},"snippet":{"type":"string","maxLength":1000,"default":""},"bodyText":{"type":"string","maxLength":20000},"receivedAt":{"type":"integer"}},"required":["accountEmail","emailId","threadId","subject","from","bodyText","receivedAt"]}}}},"responses":{"200":{"description":"AI triage metadata for the message, freshly generated or from KV","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"minItems":1,"maxItems":5},"description":{"type":"string","minLength":1,"maxLength":300},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["reply","reminder","add_to_calendar","pay","unsubscribe","archive"]},"label":{"type":"string","minLength":1,"maxLength":160},"at":{"type":"integer","nullable":true,"default":null}},"required":["type","label"]},"maxItems":5},"emailId":{"type":"string","minLength":1},"accountEmail":{"type":"string","minLength":3},"threadId":{"type":"string","minLength":1},"model":{"type":"string","minLength":1},"enrichedAt":{"type":"integer"},"version":{"type":"number","enum":[2]}},"required":["tags","description","actions","emailId","accountEmail","threadId","model","enrichedAt","version"]},"cached":{"type":"boolean"}},"required":["metadata","cached"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Model produced an unusable answer","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"AI enrichment not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/ai/vithy/ticket":{"post":{"security":[{"apiKey":[]}],"responses":{"200":{"description":"Short-lived connection ticket for the Vithy agent WebSocket","content":{"application/json":{"schema":{"type":"object","properties":{"ticket":{"type":"string","minLength":1},"expiresAt":{"type":"integer","minimum":0,"exclusiveMinimum":true},"agent":{"type":"string","enum":["vithy"]},"name":{"type":"string","minLength":1}},"required":["ticket","expiresAt","agent","name"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/ai/metadata":{"get":{"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":3},"required":true,"name":"accountEmail","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"emailId","in":"query"}],"responses":{"200":{"description":"The stored AI metadata record for one message; null when absent","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","nullable":true,"properties":{"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"minItems":1,"maxItems":5},"description":{"type":"string","minLength":1,"maxLength":300},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["reply","reminder","add_to_calendar","pay","unsubscribe","archive"]},"label":{"type":"string","minLength":1,"maxLength":160},"at":{"type":"integer","nullable":true,"default":null}},"required":["type","label"]},"maxItems":5},"emailId":{"type":"string","minLength":1},"accountEmail":{"type":"string","minLength":3},"threadId":{"type":"string","minLength":1},"model":{"type":"string","minLength":1},"enrichedAt":{"type":"integer"},"version":{"type":"number","enum":[2]}},"required":["tags","description","actions","emailId","accountEmail","threadId","model","enrichedAt","version"]}},"required":["metadata"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"AI enrichment not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/sync/hint":{"get":{"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"accountEmail","in":"query"}],"responses":{"200":{"description":"The freshest push signal for this account; the desktop engine polls it to decide when to run an incremental sync","content":{"application/json":{"schema":{"type":"object","properties":{"accountEmail":{"type":"string"},"latestHistoryId":{"type":"string","nullable":true},"receivedAt":{"type":"integer","nullable":true}},"required":["accountEmail","latestHistoryId","receivedAt"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}