{"openapi":"3.1.0","info":{"title":"Attrove API","description":"Attrove public API, partner, and A2A endpoints","version":"v1"},"components":{"schemas":{"ApiError":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]},"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]},"PaginationInfo":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"has_more":{"type":"boolean"},"total_count":{"type":"number"}},"required":["limit","offset","has_more"]}}},"paths":{"/a2a/v1/message:send":{"post":{"summary":"Send an A2A message to Attrove","tags":["A2A"],"description":"Synchronous HTTP+JSON A2A entry point for Attrove's communication query capability.","parameters":[],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/a2a/v1/tasks/{id}":{"get":{"summary":"Fetch a previously created A2A task","tags":["A2A"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/a2a/v1/tasks":{"get":{"summary":"List retained A2A tasks for the authenticated user","tags":["A2A"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/a2a/v1/tasks/{id}:cancel":{"post":{"summary":"Cancel an A2A task","tags":["A2A"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/users/{user_id}/calendars":{"get":{"summary":"List user calendars","tags":["Calendars"],"description":"Returns all calendars discovered for a user's calendar integrations.\n\n**Filtering:**\n- `integration_id`: Filter to a specific integration (int_xxx format)\n- `active`: Filter by active status (true/false)\n\n**Expand parameter**:\nBy default, `description` is not included.\nUse `expand=description` to include calendar descriptions.\n\n**Pagination:**\n- `limit`: Maximum number of calendars to return (default: 100, max: 100)\n- `offset`: Number of calendars to skip for pagination (default: 0)\n\n**Note:** By default, only the primary calendar is active. Use PATCH to activate additional calendars.","parameters":[{"schema":{"type":"string"},"in":"query","name":"integration_id","required":false,"description":"Filter to a specific integration (int_xxx format)"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"active","required":false,"description":"Filter by active status"},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false,"description":"Number of items to return (1-100, default 50)"},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"offset","required":false,"description":"Number of items to skip (default 0)"},{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: description"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque calendar ID (cal_xxx format)"},"integration_id":{"type":"string","description":"Opaque integration ID (int_xxx format)"},"title":{"type":"string","nullable":true,"description":"Calendar display name"},"description":{"type":"string","nullable":true,"description":"Calendar description"},"active":{"type":"boolean","description":"Whether this calendar is being synced"},"created_at":{"type":"string","format":"date-time","description":"When the calendar was discovered"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the calendar was last modified"}},"required":["id","integration_id","active","created_at"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"has_more":{"type":"boolean"},"total_count":{"type":"number"}},"required":["limit","offset","has_more"]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/calendars/{id}":{"get":{"summary":"Get calendar by ID","tags":["Calendars"],"description":"Returns a single calendar by its ID. Accepts cal_xxx opaque ID format.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque calendar ID (cal_xxx format)"},"integration_id":{"type":"string","description":"Opaque integration ID (int_xxx format)"},"title":{"type":"string","nullable":true,"description":"Calendar display name"},"description":{"type":"string","nullable":true,"description":"Calendar description"},"active":{"type":"boolean","description":"Whether this calendar is being synced"},"created_at":{"type":"string","format":"date-time","description":"When the calendar was discovered"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the calendar was last modified"}},"required":["id","integration_id","active","created_at"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}},"patch":{"summary":"Update calendar","tags":["Calendars"],"description":"Updates a calendar's properties. Accepts cal_xxx opaque ID format.\n\n**Supported updates:**\n- `active`: Enable/disable syncing for this calendar\n\nWhen a calendar is activated, its events will begin syncing on the next sync cycle (within 5 minutes).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque calendar ID (cal_xxx format)"},"integration_id":{"type":"string","description":"Opaque integration ID (int_xxx format)"},"title":{"type":"string","nullable":true,"description":"Calendar display name"},"description":{"type":"string","nullable":true,"description":"Calendar description"},"active":{"type":"boolean","description":"Whether this calendar is being synced"},"created_at":{"type":"string","format":"date-time","description":"When the calendar was discovered"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the calendar was last modified"}},"required":["id","integration_id","active","created_at"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/events":{"get":{"summary":"List user events","tags":["Events"],"description":"Returns events from the user's active calendars.\n\n**Filtering:**\n- `calendar_id`: Filter to a specific calendar (cal_xxx format)\n- `start_date`: Events ending after this date (YYYY-MM-DD)\n- `end_date`: Events starting before this date (YYYY-MM-DD)\n\n**Expand parameter**:\nBy default, `description`, `location`, `attendees`, `html_link`, `event_link`, `visibility`, and `response_status` are not included.\nUse `expand=description,location,attendees,html_link,event_link,visibility,response_status` to include these fields.\n\n**Pagination (cursor-only):**\n- `limit`: Maximum number of events per page (default: 100, max: 500)\n- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.\n\n**Ordering:** `start_time` ASC — earliest event first.\n\n**Note:** Only events from active calendars are returned. Cancelled events are excluded.","parameters":[{"schema":{"type":"string"},"in":"query","name":"calendar_id","required":false,"description":"Filter to a specific calendar (cal_xxx format)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"start_date","required":false,"description":"Events ending after this date (YYYY-MM-DD format)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"end_date","required":false,"description":"Events starting before this date (YYYY-MM-DD format)"},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false,"description":"Number of items to return (1-100, default 50)"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another."},{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: description, location, attendees, html_link, event_link, visibility, response_status"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque event ID (evt_xxx format)"},"calendar_id":{"type":"string","description":"Opaque calendar ID (cal_xxx format)"},"title":{"type":"string","nullable":true,"description":"Event title"},"description":{"type":"string","nullable":true,"description":"Event description or body"},"start_time":{"type":"string","format":"date-time","description":"Event start time (ISO8601)"},"end_time":{"type":"string","format":"date-time","description":"Event end time (ISO8601)"},"location":{"type":"string","nullable":true,"description":"Event location"},"status":{"type":"string","nullable":true,"description":"Event status (confirmed, tentative, cancelled)"},"all_day":{"type":"boolean","description":"Whether this is an all-day event"},"organizer_entity_id":{"type":"string","nullable":true,"description":"Entity ID of the organizer"},"attendee_entity_ids":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Entity IDs of attendees"},"attendees":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true},"description":"Raw attendee data from the calendar provider"},"html_link":{"type":"string","nullable":true,"description":"Link to view event in provider's web UI"},"event_link":{"type":"string","nullable":true,"description":"Video conference link if present"},"visibility":{"type":"string","nullable":true,"description":"Event visibility (default, public, private, confidential)"},"response_status":{"type":"string","nullable":true,"description":"Calendar owner's RSVP status (needsAction, accepted, declined, tentative)"},"update_count":{"type":"integer","description":"Number of meaningful changes detected during sync"},"created_at":{"type":"string","format":"date-time","description":"When the event was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the event was last modified"}},"required":["id","calendar_id","start_time","end_time","all_day","update_count","created_at"]}},"pagination":{"type":"object","oneOf":[{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[true]},"next_cursor":{"type":"string"}},"required":["limit","has_more","next_cursor"]},{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[false]}},"required":["limit","has_more"]}]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}},"post":{"tags":["Push"],"description":"Push a milestone, deadline, or scheduled item for a user","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/events/{id}":{"get":{"summary":"Get event by ID","tags":["Events"],"description":"Returns a single event by its ID. Accepts evt_xxx opaque ID format.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque event ID (evt_xxx format)"},"calendar_id":{"type":"string","description":"Opaque calendar ID (cal_xxx format)"},"title":{"type":"string","nullable":true,"description":"Event title"},"description":{"type":"string","nullable":true,"description":"Event description or body"},"start_time":{"type":"string","format":"date-time","description":"Event start time (ISO8601)"},"end_time":{"type":"string","format":"date-time","description":"Event end time (ISO8601)"},"location":{"type":"string","nullable":true,"description":"Event location"},"status":{"type":"string","nullable":true,"description":"Event status (confirmed, tentative, cancelled)"},"all_day":{"type":"boolean","description":"Whether this is an all-day event"},"organizer_entity_id":{"type":"string","nullable":true,"description":"Entity ID of the organizer"},"attendee_entity_ids":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Entity IDs of attendees"},"attendees":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true},"description":"Raw attendee data from the calendar provider"},"html_link":{"type":"string","nullable":true,"description":"Link to view event in provider's web UI"},"event_link":{"type":"string","nullable":true,"description":"Video conference link if present"},"visibility":{"type":"string","nullable":true,"description":"Event visibility (default, public, private, confidential)"},"response_status":{"type":"string","nullable":true,"description":"Calendar owner's RSVP status (needsAction, accepted, declined, tentative)"},"update_count":{"type":"integer","description":"Number of meaningful changes detected during sync"},"created_at":{"type":"string","format":"date-time","description":"When the event was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the event was last modified"}},"required":["id","calendar_id","start_time","end_time","all_day","update_count","created_at"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/commitments":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/commitments/{commitment_id}/resolve":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"commitment_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/connect-sessions":{"post":{"summary":"Create a durable connect session","tags":["Users"],"description":"Creates a durable connect session for invisible end-user onboarding. The session can be used from a partner app, email recovery flow, CLI handoff, or agent-driven flow and is exchanged into fresh pit_ tokens during provider OAuth.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"client_id":{"type":"string","minLength":1},"provider":{"type":"string","enum":["gmail","outlook","slack","google_calendar","google_meet","teams"]},"display":{"type":"string","enum":["popup","redirect"]},"return_to":{"type":"string","format":"uri"},"include_install":{"type":"boolean"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"session_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"activation_url":{"type":"string"},"expires_at":{"type":"string"},"organization_name":{"type":"string"},"partner_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"recommended_provider":{"anyOf":[{"type":"string","enum":["gmail","outlook","slack","google_calendar","google_meet","teams"]},{"type":"null"}]},"connected_providers":{"type":"array","items":{"type":"string","enum":["gmail","outlook","slack","google_calendar","google_meet","teams"]}},"cli":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"command":{"type":"string"},"json_command":{"type":"string"},"install_claude_code":{"type":"string"},"install_cursor":{"type":"string"},"install_claude_desktop":{"type":"string"}},"required":["command","json_command","install_claude_code","install_cursor","install_claude_desktop"]},{"type":"null"}]},"install":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"claude_code":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"recommended_scope":{"type":"string"},"command":{"type":"string"},"config_path":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"required":["client","recommended_scope","command","config_path","config"]},"cursor":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"install_url":{"type":"string"},"deeplink_url":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"required":["client","install_url","deeplink_url","config"]},"claude_desktop":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"config_path":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"required":["client","config_path","config"]},"chatgpt":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"beta":{"type":"boolean"},"url":{"type":"string"},"note":{"type":"string"}},"required":["client","beta","url","note"]},"codex":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"config_path":{"type":"string"},"config_toml":{"type":"string"},"login_command":{"type":"string"},"note":{"type":"string"}},"required":["client","config_path","config_toml","login_command","note"]}},"required":["claude_code","cursor","claude_desktop","chatgpt","codex"]},{"type":"null"}]}},"required":["session_id","user_id","activation_url","expires_at","organization_name","partner_name","recommended_provider","connected_providers","cli","install"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/connect-sessions/{session_id}":{"get":{"summary":"Resolve a durable connect session","tags":["Users"],"description":"Returns metadata for a durable connect session, including install artifacts and the recommended provider to connect next. Note: user_id is included because the frontend needs it for session exchange and OAuth flows. Session IDs are UUIDv4 (122 bits of entropy) and the endpoint is rate-limited per IP.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"session_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"session_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"activation_url":{"type":"string"},"expires_at":{"type":"string"},"organization_name":{"type":"string"},"partner_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"recommended_provider":{"anyOf":[{"type":"string","enum":["gmail","outlook","slack","google_calendar","google_meet","teams"]},{"type":"null"}]},"connected_providers":{"type":"array","items":{"type":"string","enum":["gmail","outlook","slack","google_calendar","google_meet","teams"]}},"cli":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"command":{"type":"string"},"json_command":{"type":"string"},"install_claude_code":{"type":"string"},"install_cursor":{"type":"string"},"install_claude_desktop":{"type":"string"}},"required":["command","json_command","install_claude_code","install_cursor","install_claude_desktop"]},{"type":"null"}]},"install":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"claude_code":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"recommended_scope":{"type":"string"},"command":{"type":"string"},"config_path":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"required":["client","recommended_scope","command","config_path","config"]},"cursor":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"install_url":{"type":"string"},"deeplink_url":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"required":["client","install_url","deeplink_url","config"]},"claude_desktop":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"config_path":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"required":["client","config_path","config"]},"chatgpt":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"beta":{"type":"boolean"},"url":{"type":"string"},"note":{"type":"string"}},"required":["client","beta","url","note"]},"codex":{"type":"object","additionalProperties":false,"properties":{"client":{"type":"string"},"config_path":{"type":"string"},"config_toml":{"type":"string"},"login_command":{"type":"string"},"note":{"type":"string"}},"required":["client","config_path","config_toml","login_command","note"]}},"required":["claude_code","cursor","claude_desktop","chatgpt","codex"]},{"type":"null"}]}},"required":["session_id","user_id","activation_url","expires_at","organization_name","partner_name","recommended_provider","connected_providers","cli","install"]}},"required":["success","data"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"410":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/connect-sessions/{session_id}/auth-session":{"post":{"summary":"Bootstrap a hidden auth session for MCP consent","tags":["Users"],"description":"Creates or reuses a hidden Supabase auth identity for the durable connect session and returns a one-time token hash that the browser can verify into a session without showing an Attrove sign-in screen.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"session_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"session_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"token_hash":{"type":"string"},"type":{"type":"string","enum":["magiclink"]},"display_email":{"type":"string"}},"required":["session_id","user_id","token_hash","type","display_email"]}},"required":["success","data"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"410":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/connect-sessions/{session_id}/exchange":{"post":{"summary":"Exchange a durable connect session for a pit_ token","tags":["Users"],"description":"Creates a fresh short-lived pit_ token for the durable connect session. The token is consumed by the standard provider OAuth flow.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","enum":["gmail","outlook","slack","google_calendar","google_meet","teams"]}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"session_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"session_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"token":{"type":"string"},"expires_at":{"type":"string"}},"required":["session_id","user_id","token","expires_at"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"410":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/conversations":{"get":{"summary":"List user's conversations","tags":["Conversations"],"description":"Returns conversations (Slack channels, email threads, etc.) for filtering RAG queries.\n\n**Use cases**:\n- Display channel picker UI for filtering RAG queries\n- Let users select which channels to query from\n\n**Optional filters**:\n- `integration_ids`: Filter to specific integrations (opaque IDs like int_xxx)\n- `synced_only`: If true, only return conversations where syncing is enabled\n\n**Pagination (cursor-only)**:\n- `limit`: Maximum number of conversations per page (default: 50, max: 100)\n- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.\n\nThe response `pagination` object contains `limit`, `has_more`, and (when `has_more=true`) `next_cursor`. There is no `offset` and no `total_count` — partners walk pages forward via cursor and use `has_more` to detect the last page.\n\n**Response**: Array of conversation objects with opaque IDs","parameters":[{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"integration_ids","required":false,"description":"Filter to specific integrations (int_xxx format)"},{"schema":{"type":"boolean"},"in":"query","name":"synced_only","required":false,"description":"Only return conversations where syncing is enabled"},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false,"description":"Number of items to return (1-100, default 50)"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another."},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"integration_id":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"},"provider":{"type":"string"},"import_messages":{"type":"boolean"}},"required":["id","integration_id","title","type","provider","import_messages"]}},"pagination":{"type":"object","oneOf":[{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[true]},"next_cursor":{"type":"string"}},"required":["limit","has_more","next_cursor"]},{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[false]}},"required":["limit","has_more"]}]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}},"patch":{"summary":"Update conversation sync settings","tags":["Conversations"],"description":"Enable or disable message syncing for one or more conversations.\n\n**Use case**: Partners can provide a channel picker UI where users select which Slack channels to sync.\n\n**Request body**:\n- `conversations`: Array of objects with `id` (opaque conv_xxx) and `import_messages` (boolean)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"conversations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^conv_[0-9A-Za-z]+$"},"import_messages":{"type":"boolean"}},"required":["id","import_messages"]}}},"required":["conversations"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"updated":{"type":"number"}},"required":["updated"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/entities":{"get":{"summary":"List contacts","tags":["Entities"],"description":"Returns contacts (people and bots) that the authenticated user has communicated with.\n\n**Use cases**:\n- Discover entity IDs for filtering messages by sender via `GET /v1/users/:user_id/messages?entity_id=ent_xxx`\n- Build a contact picker UI\n- Show sender details in inbox views\n\n**Filtering**:\n- `search`: Case-insensitive substring match on contact name, or exact match on an external ID (email address, Slack user ID)\n- `entity_type`: Filter by type (e.g., \"person\", \"bot\")\n- `is_bot`: Filter by bot status (true/false)\n\n**Pagination (cursor-only)**:\n- `limit`: Maximum number of contacts per page (default: 50, max: 100)\n- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.\n\nThe response `pagination` object contains `limit`, `has_more`, and (when `has_more=true`) `next_cursor`. There is no `offset` and no `total_count` — partners walk pages forward via cursor and use `has_more` to detect the last page.\n\n**Examples**:\n```\n# List all contacts\nGET /v1/users/:user_id/entities\n\n# Search by name or email\nGET /v1/users/:user_id/entities?search=john\n\n# Only non-bot contacts\nGET /v1/users/:user_id/entities?is_bot=false\n\n# Filter by type\nGET /v1/users/:user_id/entities?entity_type=person\n```","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"search","required":false,"description":"Search by name (substring, case-insensitive) or external ID (exact match)"},{"schema":{"type":"string"},"in":"query","name":"entity_type","required":false,"description":"Filter by entity type (e.g., \"person\", \"bot\")"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"is_bot","required":false,"description":"Filter by bot status"},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false,"description":"Number of items to return (1-100, default 50)"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another."},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^ent_[A-Za-z0-9:]+$"},"name":{"type":"string"},"entity_type":{"type":"string"},"external_ids":{"type":"array","items":{"type":"string"}},"is_bot":{"type":"boolean"},"avatar_uri":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","entity_type","external_ids","is_bot","avatar_uri"]}},"pagination":{"type":"object","oneOf":[{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[true]},"next_cursor":{"type":"string"}},"required":["limit","has_more","next_cursor"]},{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[false]}},"required":["limit","has_more"]}]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/entities/relationships":{"get":{"summary":"List entity relationships","tags":["Entities"],"description":"Returns pairs of entities that co-occur on messages, meetings, or calendar events, with interaction count and recency.","parameters":[{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Max results (default 200, max 500)"},{"schema":{"type":"string"},"in":"query","name":"min_interactions","required":false,"description":"Minimum co-occurrence count (default 1)"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"include_bots","required":false,"description":"Include bot entities (default false)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"entity_a":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^ent_[A-Za-z0-9:]+$"},"name":{"type":"string"},"entity_type":{"type":"string"},"external_ids":{"type":"array","items":{"type":"string"}},"is_bot":{"type":"boolean"},"avatar_uri":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","entity_type","external_ids","is_bot","avatar_uri"]},"entity_b":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^ent_[A-Za-z0-9:]+$"},"name":{"type":"string"},"entity_type":{"type":"string"},"external_ids":{"type":"array","items":{"type":"string"}},"is_bot":{"type":"boolean"},"avatar_uri":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","entity_type","external_ids","is_bot","avatar_uri"]},"co_occurrence_count":{"type":"integer","minimum":1},"last_interaction_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["entity_a","entity_b","co_occurrence_count","last_interaction_at"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"has_more":{"type":"boolean"},"total_count":{"type":"number"}},"required":["limit","offset","has_more"]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/entities/{id}":{"get":{"summary":"Retrieve a contact","tags":["Entities"],"description":"Retrieves a specific contact by its ID (ent_xxx format or raw UUID). The contact must belong to the authenticated user.\n\n**Response fields**:\n- `id`: Entity ID (ent_xxx opaque format)\n- `name`: Human-readable name\n- `entity_type`: Type of entity (\"person\", \"bot\", etc.)\n- `external_ids`: Platform-specific identifiers (email addresses, Slack user IDs, etc.)\n- `is_bot`: Whether this contact is a bot/automated sender\n- `avatar_uri`: URI to the contact's avatar image (null if unavailable)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^ent_[A-Za-z0-9:]+$"},"name":{"type":"string"},"entity_type":{"type":"string"},"external_ids":{"type":"array","items":{"type":"string"}},"is_bot":{"type":"boolean"},"avatar_uri":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","entity_type","external_ids","is_bot","avatar_uri"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/goals":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goal-events":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/archive":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/cancel":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/reopen":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/evaluate":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/snapshots":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/evidence":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/notes":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/status":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/acknowledge":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/acknowledgment":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/goals/{goal_id}/draft-follow-up":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goal-events":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/archive":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/cancel":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/reopen":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/evaluate":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/snapshots":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/evidence":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/notes":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/status":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/acknowledge":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/acknowledgment":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/users/{user_id}/goals/{goal_id}/draft-follow-up":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"goal_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/integrations/partner-info":{"get":{"summary":"Get partner organization info","tags":["Integrations"],"description":"Returns the organization name for the partner context. Used to display a meaningful name in the integration popup (e.g., \"Company X uses Attrove...\").\n\n**Authentication**: Requires pit_ or sk_ token with user_id.\n\n**Response**:\n- `organization_name`: Display name of the partner's organization\n- `partner_name`: Display name of the partner (optional, may differ from org)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"organization_name":{"type":"string"},"partner_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["organization_name"]}},"required":["success"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}}},"/v1/users/{user_id}/integrations/connect":{"get":{"summary":"Get OAuth authorization URL","tags":["Integrations"],"description":"Returns an OAuth authorization URL to connect a user's Gmail, Slack, Outlook, or other integration.\n\n**Flow**:\n1. Call this GET endpoint with `provider` to get an `authUrl`\n2. Redirect the user to the `authUrl`\n3. After user authorizes, they're redirected back with a `code`\n4. Call `POST /v1/users/:user_id/integrations/connect` with the `code` to complete the connection\n\n**Supported providers**: `gmail`, `slack`, `outlook`, `teams`","parameters":[{"schema":{"type":"string","enum":["gmail","slack","outlook","google_calendar","google_meet","teams"]},"in":"query","name":"provider","required":true,"description":"Integration provider (gmail, slack, outlook, google_calendar, google_meet, teams)"},{"schema":{"type":"string"},"in":"query","name":"state","required":false,"description":"OAuth state parameter. May be a JSON or base64url JSON object with redirect_url for per-flow completion redirects."},{"schema":{"type":"string"},"in":"query","name":"reconnect","required":false,"description":"Integration ID to reconnect (int_xxx format)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"authUrl":{"type":"string","description":"OAuth authorization URL to redirect to"}},"required":["success","authUrl"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}},"post":{"summary":"Complete OAuth connection","tags":["Integrations"],"description":"Exchanges an OAuth authorization code to complete an integration connection.\n\n**Flow**:\n1. Call `GET /v1/users/:user_id/integrations/connect` with `provider` to get an `authUrl`\n2. Redirect the user to the `authUrl`\n3. After user authorizes, they're redirected back with a `code`\n4. Call this POST endpoint with the `code`, `provider`, and `state` to complete the connection\n\n**Supported providers**: `gmail`, `slack`, `outlook`, `teams`\n\n**Reconnection**: Pass `reconnect` with an integration ID (int_xxx format) to reconnect an existing integration","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","description":"Integration provider (gmail, slack, outlook, teams)"},"code":{"type":"string","description":"OAuth authorization code"},"state":{"type":"string","description":"OAuth state parameter returned by the provider. Supports redirect_url in JSON/base64url JSON state."},"reconnect":{"type":"string","description":"Integration ID to reconnect (int_xxx format)"},"response_mode":{"type":"string","enum":["json","redirect"],"description":"Set to redirect for direct browser POST callbacks. Default json preserves XHR flows."}},"required":["provider","code"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"integration_id":{"type":"string","description":"Created/reconnected integration ID"},"redirect_url":{"type":"string","description":"Partner return URL with OAuth completion query parameters appended, when configured."}},"required":["success"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}}},"/v1/users/{user_id}/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"description":"Returns all integrations connected for a user.\n\n**Optional filters**:\n- `type`: Filter by integration type (e.g., `gmail`, `slack`)\n- `suite_id`: Filter by suite ID\n\n**Expand parameter**:\nBy default, `last_synced_at` is not included.\nUse `expand=last_synced_at` to include this field.\n\n**Response**: Array of integration objects with provider, status, and configuration","parameters":[{"schema":{"type":"string"},"in":"query","name":"type","required":false,"description":"Filter by integration type (gmail, slack, outlook)"},{"schema":{"type":"string"},"in":"query","name":"suite_id","required":false,"description":"Filter by suite ID"},{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: last_synced_at"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string"},"category":{"type":"string"},"provider":{"type":"string"},"name":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"auth_status":{"type":"string"},"updated_at":{"type":"string","nullable":true},"last_synced_at":{"type":"string","nullable":true}},"required":["id","type","provider","is_active"]}}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}}},"/v1/users/{user_id}/capabilities":{"get":{"summary":"List active capabilities","tags":["Integrations"],"description":"Returns the set of partner-facing capabilities the user has granted via active integrations.\n\nUse this as the **source of truth** for what a user can do. Webhook events (`capability.granted` / `capability.revoked`) are notifications; this endpoint is the snapshot you reconcile against after missed deliveries or new partner onboarding.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string","format":"uuid"},"capabilities":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string","enum":["email","chat","calendar","meet"]},"provider":{"type":"string"},"integration_id":{"type":"string","pattern":"^int_[0-9A-Za-z]+$"},"granted_at":{"type":"string","format":"date-time"},"account":{"oneOf":[{"type":"object","additionalProperties":false,"required":["kind","email"],"properties":{"kind":{"type":"string","enum":["email"]},"email":{"type":"string","format":"email"},"provider_account_id":{"type":"string","minLength":1}}},{"type":"object","additionalProperties":false,"required":["kind"],"properties":{"kind":{"type":"string","enum":["workspace"]},"workspace_name":{"type":"string","minLength":1},"workspace_domain":{"type":"string","minLength":1},"user_display_name":{"type":"string","minLength":1},"provider_account_id":{"type":"string","minLength":1}}}]}},"required":["capability","provider","integration_id","granted_at"]}}},"required":["user_id","capabilities"]}},"required":["success"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/status":{"get":{"summary":"Connection & freshness status","tags":["Integrations"],"description":"Returns one rollup read on whether the user's connected sources are current: `fresh`, `catching_up`, `needs_you`, or `not_connected`.\n\n`needs_you` means *connection health* requires a human (reconnect or grant a missing permission) — it is unrelated to the dashboard's \"Needs you\" panel, which tracks goal catches, not integration freshness.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"state":{"type":"string","enum":["fresh","catching_up","needs_you","not_connected"]},"summary":{"type":"string"},"as_of":{"type":"string","format":"date-time"},"needs_action":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string"},"integration_id":{"type":"string"},"reason":{"type":"string","enum":["reconnect","scope_missing"]},"connect_url":{"type":"string"}},"required":["provider","integration_id","reason","connect_url"]}},"sources":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string"},"integration_id":{"type":"string"},"identity":{"type":"string","nullable":true},"access":{"type":"array","items":{"type":"string","enum":["read","send"]}},"state":{"type":"string","enum":["fresh","delayed","stale","rate_limited","syncing","connecting","needs_reconnect","scope_missing"]},"state_reason":{"type":"string","nullable":true,"enum":["auth_expired","scope_missing","rate_limited","initial_backfill","sync_delayed","sync_stale","provider_unavailable"]},"sync_mode":{"type":"string","enum":["webhook","polling"]},"cadence":{"type":"object","additionalProperties":false,"properties":{"fresh_within_seconds":{"type":"integer"},"stale_after_seconds":{"type":"integer"}}},"last_successful_sync_at":{"type":"string","nullable":true},"last_failed_sync_at":{"type":"string","nullable":true},"last_error_code":{"type":"string","nullable":true},"last_item_at":{"type":"string","nullable":true},"coverage":{"type":"object","additionalProperties":false,"properties":{"messages":{"type":"integer"},"meetings":{"type":"integer"},"events":{"type":"integer"},"since":{"type":"string","nullable":true}}},"caveats":{"type":"array","items":{"type":"string","enum":["backfill_limited","partial","unsupported"]}}},"required":["provider","integration_id","access","state","sync_mode","cadence","coverage","caveats"]}}},"required":["state","summary","as_of","needs_action","sources"]}},"required":["success"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/integrations/{id}":{"get":{"summary":"Retrieve an integration","tags":["Integrations"],"description":"Retrieves details for a specific integration by ID.\n\n**Response fields**:\n- `id`: Opaque integration ID (e.g., `int_1Z`)\n- `type`: Provider type (gmail, slack, outlook, etc.)\n- `is_active`: Whether the integration is currently active\n- `auth_status`: Current authentication status\n- `created_at`: When the integration was created","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string","pattern":"^int_[A-Za-z0-9]+$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string"},"category":{"type":"string"},"provider":{"type":"string"},"name":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"auth_status":{"type":"string"},"email":{"type":"string","nullable":true},"last_synced_at":{"type":"string","nullable":true}},"required":["id","type","provider","is_active"]}},"required":["success"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}}},"/v1/users/{user_id}/integrations/{integration_id}":{"delete":{"summary":"Disconnect an integration","tags":["Integrations"],"description":"Disconnects a user's integration by its opaque ID (e.g., `int_1Z`). This will:\n- Revoke OAuth tokens where possible\n- Stop syncing data from this integration\n- Delete synced messages and threads associated with the integration\n- Remove the integration record\n\n**Getting the integration ID**: Call `GET /v1/users/:user_id` to retrieve the list of integrations with their IDs.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string","pattern":"^int_[0-9A-Za-z]+$"},"in":"path","name":"integration_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/meetings":{"get":{"summary":"List user meetings","tags":["Meetings"],"description":"Returns meetings from the user's connected meeting integrations (Google Meet, Zoom, Teams).\n\n**Filtering:**\n- `start_date`: Meetings starting after this date (YYYY-MM-DD)\n- `end_date`: Meetings starting before this date (YYYY-MM-DD)\n- `has_summary`: Filter by summary presence (true/false)\n- `provider`: Filter by provider (google_meet, zoom, teams, manual_meetings)\n\n**Expand parameter**:\nBy default, `summary`, `short_summary`, `action_items`, `attendees`, and `meeting_link` are not included.\nUse `expand=summary,short_summary,action_items,attendees,meeting_link` to include these fields.\n\n**Pagination (cursor-only):**\n- `limit`: Maximum number of meetings per page (default: 50, max: 100)\n- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.\n\n**Note:** Meetings are returned in reverse chronological order (most recent first).","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"start_date","required":false,"description":"Meetings starting after this date (YYYY-MM-DD format)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"end_date","required":false,"description":"Meetings starting before this date (YYYY-MM-DD format)"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"has_summary","required":false,"description":"Filter by summary presence"},{"schema":{"type":"string","enum":["google_meet","zoom","teams","manual_meetings"]},"in":"query","name":"provider","required":false,"description":"Filter by meeting provider"},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false,"description":"Number of items to return (1-100, default 50)"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another."},{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: summary, short_summary, action_items, attendees, meeting_link"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque meeting ID (mtg_xxx format)"},"title":{"type":"string","description":"Meeting title"},"meeting_code":{"type":"string","nullable":true,"description":"Meeting code (e.g., Google Meet code)"},"start_time":{"type":"string","format":"date-time","description":"Meeting start time (ISO8601)"},"end_time":{"type":"string","format":"date-time","description":"Meeting end time (ISO8601)"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary of the meeting"},"short_summary":{"type":"string","nullable":true,"description":"Brief one-line summary"},"action_items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"description":{"type":"string","description":"Action item description"},"assignee":{"type":"string","nullable":true,"description":"Person assigned to the action"},"due_date":{"type":"string","nullable":true,"description":"Due date for the action (ISO8601)"},"completed":{"type":"boolean","nullable":true,"description":"Whether the action has been completed"}},"required":["description"]},"description":"Extracted action items from the meeting"},"attendees":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","nullable":true,"description":"Attendee email address"},"name":{"type":"string","nullable":true,"description":"Attendee display name"},"is_organizer":{"type":"boolean","nullable":true,"description":"Whether this attendee is the organizer"},"response_status":{"type":"string","enum":["accepted","declined","tentative","needsAction"],"nullable":true,"description":"Attendee's response to the meeting invitation"}}},"description":"List of meeting attendees"},"meeting_link":{"type":"string","nullable":true,"description":"Link to join or view the meeting"},"has_transcript":{"type":"boolean","description":"Whether a transcript is available"},"has_notes":{"type":"boolean","description":"Whether smart notes are available"},"content_status":{"type":"string","enum":["none","notes_only","transcript_only","transcript_and_notes"],"description":"Indicates which content types are available: transcript, smart notes, both, or none"},"provider":{"type":"string","enum":["google_meet","zoom","teams","manual_meetings"],"description":"Meeting provider"},"event_id":{"type":"string","nullable":true,"description":"Linked calendar event ID (evt_xxx format)"},"created_at":{"type":"string","format":"date-time","description":"When the meeting was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the meeting was last modified"}},"required":["id","title","start_time","end_time","has_transcript","has_notes","content_status","provider","created_at"]}},"pagination":{"type":"object","oneOf":[{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[true]},"next_cursor":{"type":"string"}},"required":["limit","has_more","next_cursor"]},{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[false]}},"required":["limit","has_more"]}]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}},"delete":{"summary":"Archive a meeting by external_id","tags":["Meetings"],"description":"Reversibly archives (soft-deletes) the meeting matching the given external_id. Idempotent.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"external_id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Push"],"description":"Push a meeting transcript, summary, and attendees for a user","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/meetings/{id}":{"get":{"summary":"Get meeting by ID","tags":["Meetings"],"description":"Returns a single meeting by its opaque ID (mtg_xxx format).","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque meeting ID (mtg_xxx format)"},"title":{"type":"string","description":"Meeting title"},"meeting_code":{"type":"string","nullable":true,"description":"Meeting code (e.g., Google Meet code)"},"start_time":{"type":"string","format":"date-time","description":"Meeting start time (ISO8601)"},"end_time":{"type":"string","format":"date-time","description":"Meeting end time (ISO8601)"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary of the meeting"},"short_summary":{"type":"string","nullable":true,"description":"Brief one-line summary"},"action_items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"description":{"type":"string","description":"Action item description"},"assignee":{"type":"string","nullable":true,"description":"Person assigned to the action"},"due_date":{"type":"string","nullable":true,"description":"Due date for the action (ISO8601)"},"completed":{"type":"boolean","nullable":true,"description":"Whether the action has been completed"}},"required":["description"]},"description":"Extracted action items from the meeting"},"attendees":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","nullable":true,"description":"Attendee email address"},"name":{"type":"string","nullable":true,"description":"Attendee display name"},"is_organizer":{"type":"boolean","nullable":true,"description":"Whether this attendee is the organizer"},"response_status":{"type":"string","enum":["accepted","declined","tentative","needsAction"],"nullable":true,"description":"Attendee's response to the meeting invitation"}}},"description":"List of meeting attendees"},"meeting_link":{"type":"string","nullable":true,"description":"Link to join or view the meeting"},"has_transcript":{"type":"boolean","description":"Whether a transcript is available"},"has_notes":{"type":"boolean","description":"Whether smart notes are available"},"content_status":{"type":"string","enum":["none","notes_only","transcript_only","transcript_and_notes"],"description":"Indicates which content types are available: transcript, smart notes, both, or none"},"provider":{"type":"string","enum":["google_meet","zoom","teams","manual_meetings"],"description":"Meeting provider"},"event_id":{"type":"string","nullable":true,"description":"Linked calendar event ID (evt_xxx format)"},"created_at":{"type":"string","format":"date-time","description":"When the meeting was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the meeting was last modified"}},"required":["id","title","start_time","end_time","has_transcript","has_notes","content_status","provider","created_at"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}},"patch":{"summary":"Update meeting","tags":["Meetings"],"description":"Updates a meeting's summary, short summary, or action items.\n\n**Supported updates:**\n- `summary`: Replace the detailed summary\n- `short_summary`: Replace the one-line summary\n- `action_items`: Replace the action items list\n\n**Note:** This allows developers to add their own annotations or corrections to AI-generated summaries.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string"},"short_summary":{"type":"string"},"action_items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"assignee":{"type":"string"}},"required":["description"]}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Opaque meeting ID (mtg_xxx format)"},"title":{"type":"string","description":"Meeting title"},"meeting_code":{"type":"string","nullable":true,"description":"Meeting code (e.g., Google Meet code)"},"start_time":{"type":"string","format":"date-time","description":"Meeting start time (ISO8601)"},"end_time":{"type":"string","format":"date-time","description":"Meeting end time (ISO8601)"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary of the meeting"},"short_summary":{"type":"string","nullable":true,"description":"Brief one-line summary"},"action_items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"description":{"type":"string","description":"Action item description"},"assignee":{"type":"string","nullable":true,"description":"Person assigned to the action"},"due_date":{"type":"string","nullable":true,"description":"Due date for the action (ISO8601)"},"completed":{"type":"boolean","nullable":true,"description":"Whether the action has been completed"}},"required":["description"]},"description":"Extracted action items from the meeting"},"attendees":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","nullable":true,"description":"Attendee email address"},"name":{"type":"string","nullable":true,"description":"Attendee display name"},"is_organizer":{"type":"boolean","nullable":true,"description":"Whether this attendee is the organizer"},"response_status":{"type":"string","enum":["accepted","declined","tentative","needsAction"],"nullable":true,"description":"Attendee's response to the meeting invitation"}}},"description":"List of meeting attendees"},"meeting_link":{"type":"string","nullable":true,"description":"Link to join or view the meeting"},"has_transcript":{"type":"boolean","description":"Whether a transcript is available"},"has_notes":{"type":"boolean","description":"Whether smart notes are available"},"content_status":{"type":"string","enum":["none","notes_only","transcript_only","transcript_and_notes"],"description":"Indicates which content types are available: transcript, smart notes, both, or none"},"provider":{"type":"string","enum":["google_meet","zoom","teams","manual_meetings"],"description":"Meeting provider"},"event_id":{"type":"string","nullable":true,"description":"Linked calendar event ID (evt_xxx format)"},"created_at":{"type":"string","format":"date-time","description":"When the meeting was created"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the meeting was last modified"}},"required":["id","title","start_time","end_time","has_transcript","has_notes","content_status","provider","created_at"]},"warnings":{"type":"array","items":{"type":"string"}}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}},"delete":{"summary":"Archive a meeting by ID","tags":["Meetings"],"description":"Reversibly archives (soft-deletes) a meeting by its opaque ID (mtg_xxx). Idempotent — archiving an already-archived or non-existent meeting returns success.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/meetings/{id}/regenerate-summary":{"post":{"summary":"Regenerate meeting summary","tags":["Meetings"],"description":"Regenerates the meeting summary using AI based on the best available meeting content.\n\n**Requirements:**\n- Meeting must have transcript or smart notes content available\n\n**Note:** This will replace the existing summary, short summary, and action items.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"data":{"type":"object","additionalProperties":false,"properties":{"summary":{"type":"string","nullable":true,"description":"Regenerated meeting summary"},"short_summary":{"type":"string","nullable":true,"description":"Regenerated brief summary"},"action_items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"description":{"type":"string","description":"Action item description"},"assignee":{"type":"string","nullable":true,"description":"Person assigned to the action"},"due_date":{"type":"string","nullable":true,"description":"Due date for the action (ISO8601)"},"completed":{"type":"boolean","nullable":true,"description":"Whether the action has been completed"}},"required":["description"]},"description":"Regenerated action items"}},"required":["summary","short_summary","action_items"]},"warnings":{"type":"array","items":{"type":"string"}}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success"]}}}}}}},"/v1/users/{user_id}/messages":{"get":{"summary":"List messages","tags":["Messages"],"description":"Returns messages for the authenticated user with optional filtering.\n\n**Primary use case**: After calling `/v1/users/:user_id/query`, use `used_message_ids` to fetch full message content.\nFor non-message sources, use `used_meeting_ids` with `/v1/users/:user_id/meetings/:meeting_id` and `used_event_ids` with `/v1/users/:user_id/events/:event_id`.\n\n**Response fields**:\nEvery message includes `sender_name` (human-readable name, null if unresolved) and `sent_by` (platform-specific sender identifier: email address for Gmail/Outlook, Slack user ID for Slack, Microsoft Graph user ID or email address for Microsoft Teams; returns 'unknown' if unresolved).\n\n**Expand parameter**:\nHeavy fields are not included by default to keep list payloads small. Request them via `expand=`:\n- `body_text` — plain-text body\n- `body_html` — original HTML body (emails only)\n- `raw` — RFC 5322 wire format (emails only; null for non-email providers and messages synced before this was supported)\n- `headers` — parsed internet message headers as `[{ name, value }]` (emails only; null when unavailable)\n\nExample: `expand=body_text,raw,headers`.\n\n**Thread bundle (always included)**: `thread_id`, `parent_message_id`, `thread_position`, `conversation_id`, `primary_entity_id`, `entity_ids`. Use these to group messages and cross-reference contacts without extra queries.\n\n**Note on expand behavior**: Single-item endpoints (`GET /v1/users/:user_id/messages/:id`) always return all fields.\nList endpoints require `expand` for detailed fields to keep payloads lightweight.\n\n**Filtering**:\n- `ids`: Comma-separated message IDs (msg_xxx format) to fetch specific messages\n- `integration_id`: Filter to a specific integration (int_xxx format)\n- `conversation_id`: Filter to a specific conversation (conv_xxx format)\n- `sent_by`: Exact sender identifier (email address for Gmail/Outlook, Slack user ID for Slack, Microsoft Graph user ID or email for Teams)\n- `entity_id`: Filter by resolved contact (ent_xxx format from `GET /entities`, or raw UUID)\n- `entity_scope`: Controls how `entity_id` matches: \"sender\" (default) returns messages sent BY entity, \"conversation\" returns messages where entity is sender or recipient. Requires `entity_id`.\n- `start_date`: Messages received after this date (YYYY-MM-DD)\n- `end_date`: Messages received before this date (YYYY-MM-DD)\n- `exclude_bots`: Exclude bot/automated messages (true/false, default: false)\n\n**Pagination (cursor-only)**:\n- `limit`: Maximum number of messages per page (default: 50, max: 100)\n- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.\n\nThe response `pagination` object contains `limit`, `has_more`, and (when `has_more=true`) `next_cursor`. There is no `offset` and no `total_count` — partners walk pages forward via cursor and use `has_more` to detect the last page.\n\n**Polling for new messages**:\nUse `GET /v1/users/:user_id/sync-stats` to check if new data has arrived (non-metered), then call this endpoint\nwith `start_date` to fetch recent messages — this endpoint is not metered, unlike `/v1/users/:user_id/query`.\n\n**Examples**:\n```\n# List messages (lightweight, no body_text)\nGET /v1/users/:user_id/messages\n\n# List messages with content\nGET /v1/users/:user_id/messages?expand=body_text\n\n# Fetch specific messages with content\nGET /v1/users/:user_id/messages?ids=msg_1Z,msg_2B,msg_3C&expand=body_text\n\n# Filter by sender\nGET /v1/users/:user_id/messages?sent_by=john@acme.com&expand=body_text\n\n# Filter by resolved contact\nGET /v1/users/:user_id/messages?entity_id=ent_xxx&expand=body_text\n\n# Filter by contact - all messages where contact is sender or recipient\nGET /v1/users/:user_id/messages?entity_id=ent_xxx&entity_scope=conversation&expand=body_text\n```","parameters":[{"schema":{"type":"string"},"in":"query","name":"ids","required":false,"description":"Comma-separated message IDs (msg_xxx format)"},{"schema":{"type":"string"},"in":"query","name":"integration_id","required":false,"description":"Filter to a specific integration (int_xxx format)"},{"schema":{"type":"string"},"in":"query","name":"conversation_id","required":false,"description":"Filter to a specific conversation (conv_xxx format)"},{"schema":{"type":"string","minLength":1},"in":"query","name":"sent_by","required":false,"description":"Exact sender identifier (email address for Gmail/Outlook, Slack user ID for Slack)"},{"schema":{"type":"string"},"in":"query","name":"entity_id","required":false,"description":"Filter by resolved contact (ent_xxx format or UUID)"},{"schema":{"type":"string","enum":["sender","conversation"],"default":"sender"},"in":"query","name":"entity_scope","required":false,"description":"Controls how entity_id matches. \"sender\" (default): messages sent BY entity. \"conversation\": messages where entity is sender or recipient (per-message match). Requires entity_id."},{"schema":{"type":"string","format":"date"},"in":"query","name":"start_date","required":false,"description":"Messages after this date (YYYY-MM-DD format)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"end_date","required":false,"description":"Messages before this date (YYYY-MM-DD format)"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"exclude_bots","required":false,"description":"Exclude bot/automated messages from results (default: false)"},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false,"description":"Number of items to return (1-100, default 50)"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another."},{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: body_text, body_html, raw, headers"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^msg_[A-Za-z0-9]+$"},"integration_id":{"type":"string","pattern":"^int_[A-Za-z0-9]+$"},"body_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"body_html":{"anyOf":[{"type":"string"},{"type":"null"}]},"raw":{"anyOf":[{"type":"string"},{"type":"null"}]},"headers":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"received_at":{"type":"string"},"parent_message_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_position":{"anyOf":[{"type":"number"},{"type":"null"}]},"is_bot":{"type":"boolean"},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"primary_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"entity_ids":{"type":"array","items":{"type":"string"}},"sender_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"sent_by":{"type":"string","minLength":1},"display_source":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","integration_id","subject","received_at","parent_message_id","thread_id","thread_position","is_bot","conversation_id","primary_entity_id","entity_ids","sender_name","sent_by","display_source"]}},"pagination":{"type":"object","oneOf":[{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[true]},"next_cursor":{"type":"string"}},"required":["limit","has_more","next_cursor"]},{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[false]}},"required":["limit","has_more"]}]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}},"post":{"tags":["Push"],"description":"Push a message (email, chat, alert, or custom) for a user","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/messages/{id}":{"get":{"summary":"Retrieve a message","tags":["Messages"],"description":"Retrieves a specific message by its ID (msg_xxx format). The message must belong to the authenticated user.\n\n**Response fields**:\n- `id`: Message ID (msg_xxx opaque format)\n- `integration_id`: ID of the integration this message came from (int_xxx format)\n- `body_text`: The message content\n- `subject`: Email subject (for email messages)\n- `received_at`: When the message was received\n- `sender_name`: Human-readable sender name (null if unresolved)\n- `sent_by`: Platform-specific sender identifier (email address for Gmail/Outlook, Slack user ID for Slack, Microsoft Graph user ID or email address for Microsoft Teams; 'unknown' if unresolved)\n- `parent_message_id`: Parent message ID for threaded replies (msg_xxx format, null for top-level)\n- `thread_position`: Position within the thread (null for non-threaded messages)\n- `is_bot`: Whether this message was from a bot/automated sender\n- `conversation_id`: Conversation ID if applicable (conv_xxx format)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^msg_[A-Za-z0-9]+$"},"integration_id":{"type":"string","pattern":"^int_[A-Za-z0-9]+$"},"body_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"body_html":{"anyOf":[{"type":"string"},{"type":"null"}]},"raw":{"anyOf":[{"type":"string"},{"type":"null"}]},"headers":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"received_at":{"type":"string"},"parent_message_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_position":{"anyOf":[{"type":"number"},{"type":"null"}]},"is_bot":{"type":"boolean"},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"primary_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"entity_ids":{"type":"array","items":{"type":"string"}},"sender_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"sent_by":{"type":"string","minLength":1},"display_source":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","integration_id","subject","received_at","parent_message_id","thread_id","thread_position","is_bot","conversation_id","primary_entity_id","entity_ids","sender_name","sent_by","display_source"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/notes/{note_id}":{"get":{"tags":["Notes"],"description":"Fetch a single note by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string","minLength":1},"in":"path","name":"note_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Notes"],"description":"Archive a note by ID (reversible soft-delete). Idempotent.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string","minLength":1},"in":"path","name":"note_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/notes":{"get":{"tags":["Notes"],"description":"List notes for a user with optional filtering","parameters":[{"schema":{"type":"string"},"in":"query","name":"ids","required":false},{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["message","meeting","event","entity","goal"]},"in":"query","name":"ref_type","required":false},{"schema":{"type":"string","maxLength":255},"in":"query","name":"ref_id","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Notes"],"description":"Archive a note by external_id (reversible soft-delete)","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"external_id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Push"],"description":"Push an analyst note or observation for a user","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{user_id}/query":{"post":{"summary":"Query user's unified context with AI","tags":["Query (Metered)"],"description":"Performs semantic retrieval across the user's connected messages, meetings, and calendar events, then returns an AI-generated answer.\n\n**Billing**: This endpoint is metered. Each call consumes AI query credits.\n\n**Use cases**:\n- \"What did Sarah say about the Q4 budget?\"\n- \"Summarize my meeting with the engineering team last Tuesday\"\n- \"Find all discussions about the product launch\"\n\n**Parameters**:\n- `query`: The natural language question to answer (max 10,000 characters)\n- `client_timezone`: User's timezone for date-aware queries\n- `history`: Optional conversation history for follow-up questions (capped at 50 items / 64KB UTF-8; oldest are dropped past the cap with a `history_truncated_for_size_budget` warning, and a single message above the byte cap is rejected with `VALIDATION_OUT_OF_RANGE`)\n- `integration_ids`: Optional filter to specific integrations (opaque IDs like `int_xxx`)\n- `conversation_ids`: Optional filter to specific conversations (opaque IDs, e.g., \"conv_xxx\")\n- `retrieval_mode`: Optional retrieval strategy — `\"fast\"` (lowest latency), `\"auto\"` (adaptive, default), or `\"deep\"` (full pipeline)\n- `expand`: Optional comma-separated fields to include (e.g., \"sources\")\n- `instructions`: Optional custom instructions for the AI (controls output format, filtering, conditional behavior — overrides default style, max 20,000 chars)\n- `context`: Optional authoritative reference data the AI treats as ground truth (influences query rewriting but not used for vector search, max 20,000 chars)\n\n**Response structure**:\n- `answer`: AI-generated answer text\n- `used_message_ids`: Message IDs (`msg_xxx`) used as source context\n- `used_meeting_ids`: Meeting IDs (`mtg_xxx`) used as source context\n- `used_event_ids`: Event IDs (`evt_xxx`) used as source context\n- `used_note_ids`: Note IDs (`note_xxx`) used as source context\n- `sources`: Optional human-readable snippets (only with `expand=sources`)\n- If no relevant context is found, the request still succeeds with a plain-language `answer` and empty source ID arrays.\n\n**Expand parameter**:\nBy default, `sources` (title/snippet pairs) are not included to reduce payload size.\nUse `expand=sources` to include source snippets for display purposes.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":10000},"client_timezone":{"type":"string"},"history":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"role":{"type":"string","enum":["user","assistant","system"]},"content":{"type":"string"}},"required":["role","content"]}},"integration_ids":{"type":"array","items":{"anyOf":[{"type":"string","pattern":"^(int_[A-Za-z0-9]+|\\d+)$"},{"type":"integer","minimum":1}]},"description":"Filter to specific integrations by opaque ID (int_xxx). Numeric IDs are accepted for backward compatibility."},"conversation_ids":{"type":"array","items":{"type":"string"},"description":"Filter to specific conversations by opaque ID (conv_xxx)"},"allow_bot_messages":{"type":"boolean"},"retrieval_mode":{"type":"string","enum":["fast","auto","deep"],"description":"Optional retrieval strategy. Defaults to 'auto' for /query requests."},"expand":{"type":"string","description":"Comma-separated list of fields to include (e.g., 'sources')"},"instructions":{"type":"string","maxLength":20000,"description":"Custom instructions for the AI. Controls output format, filtering, and conditional behavior. Takes priority over default style. Max 20,000 chars."},"context":{"type":"string","maxLength":20000,"description":"Authoritative reference data for answer generation. The AI treats this as ground truth. Influences query rewriting but not used for vector search. Max 20,000 chars."}},"required":["query"]}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: sources"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"history":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"role":{"type":"string","enum":["user","assistant","system"]},"content":{"type":"string"}},"required":["role","content"]}},"answer":{"type":"string"},"used_message_ids":{"type":"array","items":{"type":"string","pattern":"^msg_[A-Za-z0-9]+$"}},"used_meeting_ids":{"type":"array","items":{"type":"string","pattern":"^mtg_(?:[A-Za-z0-9]+|~[A-Za-z0-9]+)$"}},"used_event_ids":{"type":"array","items":{"type":"string","pattern":"^evt_(?:[A-Za-z0-9]+|~[A-Za-z0-9]+)$"}},"used_note_ids":{"type":"array","items":{"type":"string","pattern":"^note_[A-Za-z0-9]+$"}},"sources":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"snippet":{"type":"string"}},"required":["title","snippet"]}},"usage":{"type":"object","additionalProperties":false,"properties":{"answer_generation":{"type":"object","additionalProperties":false,"description":"Synthesis chat-completion tokens only. See parent `usage` schema for full scope-coverage contract.","properties":{"model":{"type":"string"},"prompt_tokens":{"type":"integer","minimum":0},"completion_tokens":{"type":"integer","minimum":0},"total_tokens":{"type":"integer","minimum":0}},"required":["model","prompt_tokens","completion_tokens","total_tokens"]}},"required":["answer_generation"]},"no_context":{"type":"boolean","enum":[true]},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","enum":["records_truncated_for_token_budget","retrieval_degraded","thread_fetch_failed","meeting_hydration_failed","event_hydration_failed","history_truncated_for_size_budget"]},"message":{"type":"string"},"dropped_record_count":{"type":"integer"},"degradations":{"type":"array","items":{"type":"string"}},"failed_count":{"type":"integer"},"dropped_item_count":{"type":"integer"},"dropped_content_bytes":{"type":"integer"},"max_history_items":{"type":"integer"},"max_history_content_bytes":{"type":"integer"}},"required":["code","message"]}}},"required":["history","answer","used_message_ids","used_meeting_ids","used_event_ids","used_note_ids"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/search":{"post":{"summary":"Semantic search across user's context","tags":["Search (Metered)"],"description":"Performs semantic search across the user's connected integrations and returns raw matches from messages, meetings, and calendar events.\n\n**Billing**: This endpoint is metered. Each call consumes AI query credits.\n\n**Use this when you need**:\n- Raw communication data without AI summarization\n- Full conversation threads plus matching meetings/events\n- To build your own UI or processing on top of search results\n\n**Response structure**:\n- `key_messages`: Messages most relevant to the query\n- `conversations`: Conversation threads containing the key messages\n- `key_meetings`: Matched meetings (empty array when no meetings match)\n- `key_events`: Matched calendar events (empty array when no events match)\n- Every returned record includes `external_id` (partner-provided ID from ingest, or `null`)\n\n**Parameters**:\n- `query`: The search query (semantic, not keyword-based)\n- `integration_ids`: Optional filter to specific integrations (opaque IDs like `int_xxx`)\n- `conversation_ids`: Optional filter to specific conversations (opaque IDs, e.g., \"conv_xxx\")\n- `after_date`: Optional date filter (YYYY-MM-DD)\n- `before_date`: Optional date filter (YYYY-MM-DD)\n- `sender_domains`: Optional filter by sender email domains (e.g., [\"acme.com\"])\n- `entity_ids`: Optional filter by entity IDs (UUIDs)\n- `retrieval_mode`: Optional retrieval strategy — `\"fast\"` (lowest latency, default), `\"auto\"` (adaptive), or `\"deep\"` (full pipeline)\n- `expand`: Optional comma-separated fields to include (e.g., \"body_text,summary,description\")\n\n**Expand parameter**:\nBy default, expandable detail fields are omitted to reduce payload size.\nUse `expand=body_text` for message content, `expand=summary,short_summary,action_items,attendees,meeting_link` for meetings, and `expand=description,location,html_link,event_link,attendees` for calendar events.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":10000},"integration_ids":{"type":"array","items":{"anyOf":[{"type":"string","pattern":"^(int_[A-Za-z0-9]+|\\d+)$"},{"type":"integer","minimum":1}]},"description":"Filter to specific integrations by opaque ID (int_xxx). Numeric IDs are accepted for backward compatibility."},"conversation_ids":{"type":"array","items":{"type":"string"},"description":"Filter to specific conversations by opaque ID (conv_xxx)"},"after_date":{"type":"string","format":"date","description":"Filter results after this date (YYYY-MM-DD)"},"before_date":{"type":"string","format":"date","description":"Filter results before this date (YYYY-MM-DD)"},"allow_bot_messages":{"type":"boolean"},"sender_domains":{"type":"array","items":{"type":"string","minLength":1},"nullable":true,"description":"Filter by sender email domains (e.g., ['acme.com'])"},"entity_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"Filter by entity IDs (UUIDs)"},"retrieval_mode":{"type":"string","enum":["fast","auto","deep"],"description":"Optional retrieval strategy. Defaults to 'fast' for /search requests."},"debug_retrieval_plan":{"type":"boolean","description":"When true, asks the retrieval backend to include extra planner diagnostics."},"max_results":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of chunks to return. Chunks beyond rerank_top_k are appended in score order up to this cap."},"expand":{"type":"string","description":"Comma-separated list of fields to include (e.g., 'body_text,summary,action_items')"}},"required":["query"]}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: body_text, body_html, raw, headers, summary, short_summary, action_items, attendees, meeting_link, description, location, html_link, event_link, visibility, response_status"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"key_messages":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"message_id":{"type":"number"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Partner-provided external_id from ingest, or null when absent"},"thread_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"conversation_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"rank":{"type":"number"}},"required":["message_id","external_id"]}},"conversations":{"type":"object","description":"Map of conversation ID to conversation data with threads","additionalProperties":{"type":"object","properties":{"conversation_name":{"type":"string","nullable":true},"threads":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"message_id":{"type":"number"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Partner-provided external_id from ingest, or null when absent"},"received_at":{"type":"string"},"integration_type":{"type":"string"},"integration_type_generic":{"type":"string"},"sender_name":{"type":"string"},"recipient_names":{"type":"array","items":{"type":"string"}},"body_text":{"type":"string"},"display_source":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"thread_message_count":{"anyOf":[{"type":"number"},{"type":"null"}]},"thread_position":{"anyOf":[{"type":"number"},{"type":"null"}]},"parent_message_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"conversation_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversation_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"conversation_participants":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"}},"required":["name"]}}},"required":["message_id","external_id","received_at","integration_type","integration_type_generic","sender_name","recipient_names","thread_id","thread_message_count","thread_position","parent_message_id","conversation_type","conversation_id","conversation_participants","display_source"]}}}}}},"key_meetings":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"Opaque meeting ID (mtg_xxx)"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Partner-provided external_id from ingest, or null when absent"},"title":{"type":"string"},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time"},"summary":{"type":"string","nullable":true},"short_summary":{"type":"string","nullable":true},"action_items":{"type":"array"},"attendees":{"type":"array"},"meeting_link":{"type":"string","nullable":true},"has_transcript":{"type":"boolean"},"has_notes":{"type":"boolean"},"content_status":{"type":"string","enum":["none","notes_only","transcript_only","transcript_and_notes"]},"provider":{"type":"string"},"event_id":{"type":"string","nullable":true},"meeting_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"rank":{"type":"number"}},"required":["id","external_id","title","start_time","end_time","has_transcript","has_notes","content_status","provider","created_at"]}},"key_events":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"Opaque event ID (evt_xxx)"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Partner-provided external_id from ingest, or null when absent"},"calendar_id":{"type":"string"},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"all_day":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"rank":{"type":"number"}},"required":["id","external_id","calendar_id","title","start_time","end_time","all_day","created_at"]}},"key_notes":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"note_id":{"type":"number"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Partner-provided external_id from ingest, or null when absent"},"rank":{"type":"number"}},"required":["note_id","external_id"]}},"rerank_provider":{"type":"string","enum":["cohere","tinybert","none"],"description":"Reranking model used in the retrieval pipeline"},"degradations":{"type":"array","items":{"type":"string"},"description":"Stable degradation codes emitted by the retrieval pipeline when results may be incomplete"},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","enum":["records_truncated_for_token_budget","retrieval_degraded","thread_fetch_failed","meeting_hydration_failed","event_hydration_failed","note_hydration_failed","identifiers_partial"]},"message":{"type":"string"},"dropped_record_count":{"type":"integer"},"degradations":{"type":"array","items":{"type":"string"}},"failed_count":{"type":"integer"},"missing_count":{"type":"integer"}},"required":["code","message"]},"description":"Structured warnings about degraded or partially hydrated results"}},"required":["key_messages","conversations","key_meetings","key_events","key_notes"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}":{"get":{"summary":"Retrieve a user","tags":["Users"],"description":"Retrieves user details and a summary of their connected integrations.\n\n**Response fields**:\n- `user`: User profile including name, email, timezone, role\n- `integrations`: Array of connected integrations with provider, status, and auth state","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"user":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"onboarded":{"type":"boolean"}},"required":["id","email"]},"integrations":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"provider":{"type":"string"},"name":{"type":"string"},"is_active":{"type":"boolean"},"auth_status":{"type":"string"}},"required":["id","provider","name","is_active","auth_status"]}}},"required":["user","integrations"]}},"required":["success","data"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}},"patch":{"summary":"Update a user","tags":["Users"],"description":"Updates user profile fields. Only include fields you want to change.\n\n**Updatable fields**:\n- `first_name`: User's first name\n- `last_name`: User's last name\n- `role`: User's role/title\n- `timezone`: User's timezone (IANA format, e.g., \"America/New_York\")\n- `onboarded`: Whether user has completed onboarding","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role":{"type":"string"},"timezone":{"type":"string"},"onboarded":{"type":"boolean"},"user_id":{"type":"string","format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"onboarded":{"type":"boolean"}},"required":["id","email"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/sync-stats":{"get":{"summary":"Get user sync statistics","tags":["Users"],"description":"Returns sync statistics for a user including data counts and date ranges.\n\n**Response fields**:\n- `overall_status`: Overall sync status (syncing, complete, partial, error, pending)\n- `last_sync_at`: Timestamp of most recent sync across all integrations\n- `totals`: Aggregate counts for messages, meetings, and events\n- `integrations`: Per-integration breakdown with counts and sync status\n\n**Use cases**:\n- Display sync progress to end users\n- Show data availability before querying\n- Monitor integration health","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string"},"overall_status":{"type":"string","enum":["syncing","complete","partial","error","pending"]},"last_sync_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"totals":{"type":"object","additionalProperties":false,"properties":{"messages":{"type":"object","properties":{"count":{"type":"integer"},"first_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meetings":{"type":"object","properties":{"count":{"type":"integer"},"first_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"events":{"type":"object","properties":{"count":{"type":"integer"},"first_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}},"integrations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"category":{"type":"string"},"name":{"type":"string"},"sync_status":{"type":"string"},"last_synced_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"auth_status":{"type":"string"},"data":{"type":"object","additionalProperties":false,"properties":{"messages":{"type":"object","properties":{"count":{"type":"integer"},"first_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meetings":{"type":"object","properties":{"count":{"type":"integer"},"first_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"events":{"type":"object","properties":{"count":{"type":"integer"},"first_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}}}}},"required":["user_id","overall_status"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/threads/discover":{"post":{"summary":"Discover threads via semantic search","tags":["Threads"],"description":"Finds threads/conversations matching a semantic query.\n\nUses AI-powered semantic search to find relevant threads across all integrations.\nResults are ranked by relevance score.\n\n**Filtering options:**\n- `integration_ids`: Limit search to specific integrations\n- `integration_types`: Limit by integration type (e.g., \"slack\", \"gmail\")\n- `after_date` / `before_date`: Filter by time range\n\n**Example:**\n```json\n{\n  \"query\": \"discussions about PR #197 authentication fix\",\n  \"integration_types\": [\"slack\"],\n  \"limit\": 5\n}\n```","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"description":"Semantic search query"},"integration_ids":{"type":"array","items":{"type":"string"},"description":"Filter by integration IDs (int_xxx format)"},"integration_types":{"type":"array","items":{"type":"string"},"description":"Filter by integration type (slack, gmail, etc.)"},"after_date":{"type":"string","format":"date","description":"Filter threads with activity after this date (YYYY-MM-DD format)"},"before_date":{"type":"string","format":"date","description":"Filter threads with activity before this date (YYYY-MM-DD format)"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Maximum number of threads to return"}},"required":["query"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"threads":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"conversation_id":{"type":"string","description":"Opaque conversation ID (conv_xxx format)"},"integration_type":{"type":"string","description":"Integration type (slack, gmail, outlook, etc.)"},"title":{"type":"string","description":"Thread/conversation title"},"relevance_score":{"type":"number","minimum":0,"maximum":1,"description":"Semantic relevance score (0-1)"},"message_count":{"type":"integer","description":"Number of messages in the thread"},"last_activity":{"type":"string","format":"date-time","description":"Timestamp of last activity (ISO8601)"},"preview":{"type":"string","description":"Preview snippet from most relevant message"}},"required":["conversation_id","integration_type","title","relevance_score","message_count","last_activity","preview"]}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","enum":["UNKNOWN_INTEGRATION_TYPE","ENTITY_RESOLUTION_PARTIAL","ENTITY_RESOLUTION_FAILED","INVALID_MESSAGES_SKIPPED","INVALID_CONVERSATION_DATA"],"description":"Warning code identifying the type of data quality issue"},"message":{"type":"string","description":"Human-readable description of the warning"},"count":{"type":"integer","description":"Number of affected items (optional)"}},"required":["code","message"]},"description":"Data quality warnings - included when results may be degraded"}},"required":["threads"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/threads/{conversation_id}/analyze":{"post":{"summary":"Analyze a thread for insights","tags":["Threads"],"description":"Analyzes a conversation/thread and extracts structured insights.\n\nReturns:\n- **summary**: Detailed summary with specific facts, names, dates\n- **short_summary**: One-sentence summary of the key outcome\n- **sentiment**: Overall tone (positive, neutral, negative, mixed)\n- **action_items**: Tasks identified with owners and deadlines\n- **decisions**: Decisions made with who made them\n- **blockers**: Issues or blockers with who owns them\n- **participants**: List of people in the conversation\n\n**Example response:**\n```json\n{\n  \"summary\": \"Discussion about PR #197 authentication fix...\",\n  \"sentiment\": \"positive\",\n  \"action_items\": [\n    {\"description\": \"Review security implications\", \"owner\": \"Sarah\", \"deadline\": \"2025-01-27\"}\n  ],\n  \"decisions\": [\n    {\"description\": \"Use JWT tokens instead of session cookies\", \"made_by\": \"Mike\"}\n  ]\n}\n```","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"description":"No request body required"}}},"description":"No request body required"},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"conversation_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"summary":{"type":"string","description":"Detailed thread summary"},"short_summary":{"type":"string","description":"One-sentence summary"},"sentiment":{"type":"string","enum":["positive","neutral","negative","mixed"],"description":"Overall sentiment of the conversation"},"action_items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"owner":{"type":"string","nullable":true},"deadline":{"type":"string","nullable":true}},"required":["description"]},"description":"Extracted action items"},"decisions":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"made_by":{"type":"string","nullable":true}},"required":["description"]},"description":"Decisions made in the thread"},"blockers":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"owner":{"type":"string","nullable":true}},"required":["description"]},"description":"Blockers or issues identified"},"participants":{"type":"array","items":{"type":"string"},"description":"List of participant names"},"message_count":{"type":"integer","description":"Number of messages analyzed"},"date_range":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","enum":["UNKNOWN_INTEGRATION_TYPE","ENTITY_RESOLUTION_PARTIAL","ENTITY_RESOLUTION_FAILED","INVALID_MESSAGES_SKIPPED","INVALID_CONVERSATION_DATA"],"description":"Warning code identifying the type of data quality issue"},"message":{"type":"string","description":"Human-readable description of the warning"},"count":{"type":"integer","description":"Number of affected items (optional)"}},"required":["code","message"]},"description":"Data quality warnings - included when results may be degraded (e.g., participant names could not be resolved)"}},"required":["summary","short_summary","sentiment","action_items","decisions","blockers","participants","message_count","date_range"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/threads/{thread_id}/messages":{"get":{"summary":"List messages in a thread","tags":["Threads"],"description":"Returns a page of messages belonging to the specified thread, in thread order.\n\n**Path parameters:**\n- `user_id` — authenticated user's UUID (must match the caller's user)\n- `thread_id` — opaque thread ID (`thr_xxx`) or numeric for backwards compatibility\n\n**Default expand:** `body_html,headers` — overrideable via the `expand` query param. Add `raw` when you need RFC 5322 MIME.\n\n**Response fields:** identical shape to `GET /v1/users/:user_id/messages`, so a mailbox UI can switch between list + thread views without reshaping its parser.\n\n**Ordering:** `received_at` ASC — earliest message first.\n\n**Pagination (cursor-only):** default limit 50, max 100. Pass `pagination.next_cursor` back as `?cursor=` to walk forward. `has_more=false` means the last page.","parameters":[{"schema":{"type":"string","pattern":"^[0-9]+$"},"in":"query","name":"limit","required":false,"description":"Number of items to return (1-100, default 50)"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another."},{"schema":{"type":"string"},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to include. Valid options: body_text, body_html, raw, headers"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true},{"schema":{"type":"string"},"in":"path","name":"thread_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^msg_[A-Za-z0-9]+$"},"integration_id":{"type":"string","pattern":"^int_[A-Za-z0-9]+$"},"body_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"body_html":{"anyOf":[{"type":"string"},{"type":"null"}]},"raw":{"anyOf":[{"type":"string"},{"type":"null"}]},"headers":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"received_at":{"type":"string"},"parent_message_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_position":{"anyOf":[{"type":"number"},{"type":"null"}]},"is_bot":{"type":"boolean"},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"primary_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"entity_ids":{"type":"array","items":{"type":"string"}},"sender_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"sent_by":{"type":"string","minLength":1},"display_source":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","integration_id","subject","received_at","parent_message_id","thread_id","thread_position","is_bot","conversation_id","primary_entity_id","entity_ids","sender_name","sent_by","display_source"]}},"pagination":{"type":"object","oneOf":[{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[true]},"next_cursor":{"type":"string"}},"required":["limit","has_more","next_cursor"]},{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number"},"has_more":{"type":"boolean","enum":[false]}},"required":["limit","has_more"]}]}},"required":["success","data","pagination"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users":{"post":{"summary":"Create a user","tags":["Users"],"description":"Creates a new user or retrieves an existing user by email. Returns an API token (`sk_`) for authenticating requests on behalf of this user.\n\n**Authentication**:\n- `Authorization: Bearer <client_secret>` header\n- `X-Auth-Type: partner` header (recommended)\n- `client_id` in request body\n\n**Response**:\n- `id`: The user's unique identifier (UUID)\n- `token`: An `sk_` prefixed API token for this user","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","format":"email"},"client_id":{"type":"string","minLength":1},"first_name":{"type":"string"},"last_name":{"type":"string"},"role":{"type":"string"}},"required":["email","client_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"token":{"type":"string"}},"required":["id","token"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/tokens":{"post":{"summary":"Create an integration token","tags":["Users"],"description":"Creates a short-lived, single-use token (`pit_`) for initiating OAuth flows. This token expires in ~10 minutes.\n\n**Authentication**:\n- `Authorization: Bearer <client_secret>` header\n- `X-Auth-Type: partner` header (recommended)\n- `client_id` in request body\n\n**Usage**: Use the returned token to redirect end-users to connect their Gmail, Slack, or other integrations via the OAuth flow.\n\n**Response**:\n- `token`: A `pit_` prefixed integration token\n- `expires_at`: ISO 8601 timestamp when the token expires","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"client_id":{"type":"string","minLength":1}},"required":["client_id"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string"},"expires_at":{"type":"string"}},"required":["token","expires_at"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/connect-token":{"post":{"summary":"Create a connect token (CLI)","tags":["Users"],"description":"Generates a short-lived, single-use token (`pit_`) for initiating OAuth flows from the CLI. Accepts `sk_` token auth instead of partner credentials.\n\n**Authentication**:\n- `Authorization: Bearer <sk_token>` header\n- `X-User-ID: <user_id>` header\n\n**Usage**: Used by `npx @attrove/cli connect <service>` to open a browser OAuth flow.\n\n**Response**:\n- `token`: A `pit_` prefixed integration token\n- `expires_at`: ISO 8601 timestamp when the token expires (10 minutes)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string"},"expires_at":{"type":"string"}},"required":["token","expires_at"]}},"required":["success","data"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/{user_id}/rotate-token":{"post":{"summary":"Rotate a user's API token","tags":["Users"],"description":"Generates a new `sk_` token for the specified user, immediately invalidating the previous token. Connected integrations (Slack, Gmail, Outlook) are NOT affected.\n\n**Authentication**:\n- `Authorization: Bearer <client_secret>` header\n- `X-Auth-Type: partner` header (recommended)\n- `client_id` in request body","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"client_id":{"type":"string","minLength":1}},"required":["client_id"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"user_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string"},"token_preview":{"type":"string"}},"required":["token","token_preview"]}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/users/settings":{"get":{"summary":"Get organization sync settings","tags":["Settings"],"description":"Returns the current sync settings for the partner's organization.\n\n**Authentication**:\n- `Authorization: Bearer <client_secret>` header\n- `X-Auth-Type: partner` header\n\n**Response**:\n- `initial_sync_days`: Current initial sync depth in days (or null if not set)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"initial_sync_days":{"type":"integer","nullable":true}}}},"required":["success","data"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}},"patch":{"summary":"Update organization sync settings","tags":["Settings"],"description":"Updates sync settings for the partner's organization. Currently supports configuring the initial email sync depth (in days).\n\n**Authentication**:\n- `Authorization: Bearer <client_secret>` header\n- `X-Auth-Type: partner` header\n\n**Required fields**:\n- `initial_sync_days`: Number of days to sync on initial connection (7-90)\n\n**Optional fields**:\n- `client_id`: Partner client ID (not required if using header auth)","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"client_id":{"type":"string","minLength":1},"initial_sync_days":{"type":"integer","minimum":7,"maximum":90}},"required":["initial_sync_days"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":false,"properties":{"initial_sync_days":{"type":"integer","nullable":true}}}},"required":["success","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Optional additional error context"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/v1/webhooks":{"post":{"responses":{"200":{"description":"Default Response"}}},"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/{id}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/{id}/test":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/{id}/rotate-secret":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/{id}/deliveries":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/dead-letters":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/dead-letters/{id}/replay":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/dead-letters/{id}/dismiss":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"http://0.0.0.0:3000"}],"request_id":"req-78g"}