{"openapi":"3.0.4","info":{"title":"Hedy API","version":"1.5.0","description":"API for accessing and managing Hedy meeting sessions, highlights, to-dos, topics and webhooks. This API allows you to programmatically access your meeting transcripts, summaries, to-dos, topics and important highlights.","contact":{"name":"Hedy Support","url":"https://www.hedy.bot/contact","email":"support@hedy.bot"},"license":{"name":"Proprietary","url":"https://www.hedy.bot/terms-of-use"}},"servers":[{"url":"https://api.hedy.bot/","description":"Production server (US)"},{"url":"https://eu-api.hedy.bot/","description":"Production server (EU)"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Sessions","description":"Endpoints for managing meeting sessions"},{"name":"Highlights","description":"Endpoints for accessing meeting highlights"},{"name":"Webhooks","description":"Endpoints for configuring webhooks"},{"name":"Todos","description":"Endpoints for accessing user-specific to-do items"},{"name":"Topics","description":"Endpoints for managing meeting topics"},{"name":"Session Contexts","description":"Endpoints for managing session contexts (reusable context/instructions for sessions)"}],"components":{"parameters":{"paginationLimit":{"name":"limit","in":"query","description":"Number of items to return per page (default: 50, max: 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"paginationAfter":{"name":"after","in":"query","description":"Cursor for fetching next page. Use the 'next' value from the previous response.","schema":{"type":"string"}},"formatParam":{"name":"format","in":"query","description":"Response format. Use 'zapier' for a flat array without pagination wrapper.","schema":{"type":"string","enum":["zapier"]}}},"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","in":"header","name":"Authorization","description":"Add 'Bearer ' followed by your API key"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"internal_error"},"message":{"type":"string","example":"An unexpected error occurred"}}}}},"SessionList":{"type":"object","properties":{"sessionId":{"type":"string","example":"sess_123456789"},"title":{"type":"string","example":"Weekly Team Sync"},"startTime":{"type":"string","format":"date-time","example":"2024-03-15T14:30:00Z"},"duration":{"type":"number","description":"Duration in seconds","example":2700},"session_type":{"type":"string","description":"Type of session (e.g., meeting, lecture, interview)","example":"meeting"},"topic":{"$ref":"#/components/schemas/TopicInfo","nullable":true,"description":"Information about the topic associated with this session, if any."}}},"SessionZapier":{"type":"object","description":"Extended session object returned when ?format=zapier is used on the list endpoint.","properties":{"sessionId":{"type":"string","example":"sess_123456789"},"title":{"type":"string","example":"Weekly Team Sync"},"startTime":{"type":"string","format":"date-time","example":"2024-03-15T14:30:00Z"},"endTime":{"type":"string","format":"date-time","example":"2024-03-15T15:15:00Z"},"duration":{"type":"number","description":"Duration in seconds","example":2700},"session_type":{"type":"string","description":"Type of session (e.g., meeting, lecture, interview)","example":"meeting"},"transcript":{"type":"string","description":"Complete meeting transcript","example":"John: Let's review our progress..."},"conversations":{"type":"string","description":"Structured conversation history","example":"Q: What's the status?\nA: On track..."},"meeting_minutes":{"type":"string","description":"Formatted meeting minutes","example":"1. Project Updates\n- Status: On track"},"recap":{"type":"string","description":"Brief meeting summary","example":"Discussed Q1 goals and timeline"},"session_notes":{"type":"string","description":"User's session notes in Parchment JSON (Delta) format","example":"[{\"insert\":\"Key takeaway: focus on retention\\n\"}]"},"highlights":{"type":"array","description":"Array of highlights captured during this session","items":{"$ref":"#/components/schemas/EmbeddedHighlight"}},"topic":{"$ref":"#/components/schemas/TopicInfo","nullable":true,"description":"Information about the topic associated with this session, if any."}}},"SessionDetail":{"type":"object","properties":{"sessionId":{"type":"string","example":"sess_123456789"},"title":{"type":"string","example":"Weekly Team Sync"},"startTime":{"type":"string","format":"date-time","example":"2024-03-15T14:30:00Z"},"endTime":{"type":"string","format":"date-time","example":"2024-03-15T15:15:00Z"},"duration":{"type":"number","description":"Duration in seconds","example":2700},"session_type":{"type":"string","description":"Type of session (e.g., meeting, lecture, interview)","example":"meeting"},"transcript":{"type":"string","description":"Complete meeting transcript","example":"John: Let's review our progress..."},"conversations":{"type":"string","description":"Structured conversation history","example":"Q: What's the status?\nA: On track..."},"meeting_minutes":{"type":"string","description":"Formatted meeting minutes","example":"1. Project Updates\n- Status: On track"},"recap":{"type":"string","description":"Brief meeting summary","example":"Discussed Q1 goals and timeline"},"cleaned_transcript":{"type":"string","nullable":true,"description":"AI-cleaned version of the transcript (null if not yet generated)","example":"John: Let's review our progress on the Q1 roadmap..."},"cleaned_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the transcript was cleaned (null if not yet generated)","example":"2024-03-15T16:00:00Z"},"session_notes":{"type":"string","description":"User's session notes in Parchment JSON (Delta) format. Parse as JSON to extract rich text, or extract plain text from the 'insert' operations.","example":"[{\"insert\":\"Key takeaway: focus on retention\\n\"}]"},"user_todos":{"type":"array","description":"List of user-specific to-do items associated with this session","items":{"$ref":"#/components/schemas/TodoItem"}},"topic":{"$ref":"#/components/schemas/TopicInfo","nullable":true,"description":"Information about the topic associated with this session, if any."},"highlights":{"type":"array","description":"Array of highlights associated with this session (included in webhook payloads for session.ended and session.exported events)","items":{"$ref":"#/components/schemas/EmbeddedHighlight"}},"structured_conversations":{"type":"array","description":"Structured Q&A exchanges from the session (included in webhook payloads when available)","items":{"type":"object","properties":{"question":{"type":"string","description":"The question asked"},"answer":{"type":"string","description":"The AI-generated answer"},"timestamp":{"type":"string","format":"date-time","description":"When the exchange occurred"}}}},"exportedAt":{"type":"string","format":"date-time","description":"Timestamp when the session was manually exported (only present in session.exported webhook events, replaces endTime)","example":"2024-03-15T16:00:00Z"}}},"HighlightList":{"type":"object","description":"Summary highlight object returned by the /highlights list endpoint.","properties":{"highlightId":{"type":"string","example":"123456789"},"sessionId":{"type":"string","example":"123456789"},"timestamp":{"type":"string","format":"date-time","example":"2024-03-15T14:35:00Z"},"title":{"type":"string","example":"Key Decision on Mobile App"}}},"HighlightDetail":{"type":"object","description":"Full highlight object returned by /highlights/:highlightId and /highlights?format=zapier.","properties":{"highlightId":{"type":"string","example":"123456789"},"sessionId":{"type":"string","example":"123456789"},"timestamp":{"type":"string","format":"date-time","example":"2024-03-15T14:35:00Z"},"timeIndex":{"type":"number","description":"Timestamp in milliseconds from session start","example":300000},"title":{"type":"string","example":"Key Decision on Mobile App"},"rawQuote":{"type":"string","example":"yeah I think we should prioritize the mobile app"},"cleanedQuote":{"type":"string","example":"We should prioritize the mobile app"},"mainIdea":{"type":"string","example":"Team agreed to prioritize mobile app development"},"aiInsight":{"type":"string","example":"Strategic prioritization of mobile platform"}}},"EmbeddedHighlight":{"type":"object","description":"Highlight object embedded in session detail and Zapier responses. Uses highlightId and omits sessionId (implied by the parent session).","properties":{"highlightId":{"type":"string","example":"123456789"},"timestamp":{"type":"string","format":"date-time","example":"2024-03-15T14:35:00Z"},"timeIndex":{"type":"number","description":"Timestamp in milliseconds from session start","example":300000},"title":{"type":"string","example":"Key Decision on Mobile App"},"rawQuote":{"type":"string","example":"yeah I think we should prioritize the mobile app"},"cleanedQuote":{"type":"string","example":"We should prioritize the mobile app"},"mainIdea":{"type":"string","example":"Team agreed to prioritize mobile app development"},"aiInsight":{"type":"string","example":"Strategic prioritization of mobile platform"}}},"WebhookConfig":{"type":"object","description":"Webhook configuration as returned by the API. Note: signingSecret is never included in API responses.","properties":{"id":{"type":"string","example":"webhook_123456789"},"url":{"type":"string","example":"https://api.example.com/hedy-webhook"},"events":{"type":"array","items":{"type":"string","enum":["session.created","session.ended","session.exported","highlight.created","todo.exported"]},"example":["session.created","session.exported","highlight.created"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookEvent":{"type":"object","properties":{"event":{"type":"string","enum":["session.created","session.ended","session.exported","highlight.created","todo.exported"],"example":"session.created"},"data":{"oneOf":[{"$ref":"#/components/schemas/SessionDetail"},{"$ref":"#/components/schemas/HighlightDetail"},{"$ref":"#/components/schemas/TodoExportedData"}]},"timestamp":{"type":"string","format":"date-time"}}},"AllTodosItem":{"type":"object","description":"Represents a to-do item including its session ID.","properties":{"id":{"type":"string","description":"Unique identifier for the to-do item","example":"uuid-1234-abcd-5678"},"text":{"type":"string","description":"The content of the to-do item","example":"Follow up with John Doe about the report"},"dueDate":{"type":"string","description":"The due date for the to-do item, as generated by the LLM (e.g., 'Tomorrow', 'May 18, 2027 3pm', or empty string)","example":"Tomorrow"},"sessionId":{"type":"string","description":"ID of the session this to-do item belongs to","example":"sess_abcdef123"},"completed":{"type":"boolean","description":"Indicates whether the to-do item is marked as completed.","example":false},"topic":{"$ref":"#/components/schemas/TopicInfo","nullable":true,"description":"Information about the topic associated with the to-do's parent session, if any."}}},"TodoItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the to-do item","example":"uuid-1234-abcd-5678"},"text":{"type":"string","description":"The content of the to-do item","example":"Follow up with John Doe about the report"},"dueDate":{"type":"string","description":"The due date for the to-do item, as generated by the LLM (e.g., 'Tomorrow', 'May 18, 2027 3pm', or empty string)","example":"Tomorrow"},"completed":{"type":"boolean","description":"Indicates whether the to-do item is marked as completed.","example":false},"topic":{"$ref":"#/components/schemas/TopicInfo","nullable":true,"description":"Information about the topic associated with the to-do's parent session, if any."}}},"TodoExportedData":{"type":"object","description":"Payload structure for the 'todo.exported' webhook event.","properties":{"sessionId":{"type":"string","description":"ID of the session the todo belongs to","example":"sess_123456789"},"text":{"type":"string","description":"The text content of the exported to-do item","example":"Finalize the project proposal"},"id":{"type":"string","description":"Unique identifier (UUID) of the exported to-do item","example":"uuid-1234-abcd-5678"},"dueDate":{"type":"string","description":"The due date for the to-do item, as generated by the LLM (e.g., 'Tomorrow', 'May 18, 2027 3pm', or empty string)","example":"May 18, 2027 3pm"}}},"TopicInfo":{"type":"object","description":"Information about a meeting topic, including AI-generated insights such as session statistics and overview data.","properties":{"id":{"type":"string","description":"Document ID of the topic","example":"topic_123xyz"},"name":{"type":"string","example":"Project Alpha Discussion"},"description":{"type":"string","nullable":true,"example":"All about Project Alpha"},"color":{"type":"string","nullable":true,"description":"Hex color code","example":"#FF5733"},"iconName":{"type":"string","nullable":true,"example":"lightbulb_outline"},"topicContext":{"type":"string","nullable":true,"description":"Custom instructions/context for this topic (max 20,000 characters)","example":"Focus on technical details and action items"},"topicContextUpdatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When topicContext was last updated"},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"Topic creation timestamp (ISO string)"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"Topic last update timestamp (ISO string)"},"overview":{"type":"object","nullable":true,"description":"Parsed TopicOverviewResponse with AI-generated topic insights"},"overviewUpdatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the cached overview was last generated"},"dominantSessionType":{"type":"string","nullable":true,"description":"Most common session type for this topic","example":"brainstorm"},"sessionCount":{"type":"integer","nullable":true,"description":"Number of sessions under this topic","example":12},"lastSessionDate":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent session in this topic"}}},"SessionContextInfo":{"type":"object","description":"A reusable session context containing instructions/context that can be applied to sessions.","properties":{"id":{"type":"string","description":"Document ID of the session context","example":"ctx_abc123"},"title":{"type":"string","description":"Title of the session context (max 200 characters)","example":"Sales Call Context"},"content":{"type":"string","description":"Content/instructions for the session (max 20,000 characters)","example":"Focus on customer pain points and proposed solutions..."},"isDefault":{"type":"boolean","description":"Whether this is the default context for new sessions","example":true},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"Creation timestamp (ISO string)"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"Last update timestamp (ISO string)"}}},"CreateTopicRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the topic (max 100 characters)","example":"Weekly Standups"},"description":{"type":"string","description":"Description of the topic (max 500 characters)","example":"Team sync meetings"},"color":{"type":"string","description":"Hex color code (e.g., #FF5733)","example":"#4A90D9"},"iconName":{"type":"string","description":"Material icon name","example":"groups"},"topicContext":{"type":"string","description":"Custom instructions for this topic (max 20,000 characters)","example":"Focus on blockers and next steps"}}},"UpdateTopicRequest":{"type":"object","properties":{"name":{"type":"string","description":"New name for the topic (max 100 characters)"},"description":{"type":"string","description":"New description (max 500 characters)"},"color":{"type":"string","description":"New hex color code"},"iconName":{"type":"string","description":"New material icon name"},"topicContext":{"type":"string","nullable":true,"description":"New custom instructions (set to null to clear)"}}},"CreateSessionContextRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Title for the session context (max 200 characters)","example":"Interview Context"},"content":{"type":"string","description":"Content/instructions (max 20,000 characters)","example":"Focus on candidate experience and technical skills..."},"isDefault":{"type":"boolean","description":"Set as default context for new sessions","example":false}}},"UpdateSessionContextRequest":{"type":"object","properties":{"title":{"type":"string","description":"New title (max 200 characters)"},"content":{"type":"string","description":"New content (max 20,000 characters)"},"isDefault":{"type":"boolean","description":"Set as default context"}}}},"responses":{"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/sessions":{"get":{"tags":["Sessions"],"summary":"List sessions","description":"Returns a list of meeting sessions. Sessions are sorted by start time, newest first.\n\nSupports two response formats:\n- Standard API format with pagination (default)\n- Zapier format (flat array) when ?format=zapier is used\n\nZapier format returns all sessions by default. When limit or after parameters are provided with format=zapier, the flat array is paginated accordingly.\n\nNote: Only sessions with cloudSyncEnabled=true are returned.","parameters":[{"$ref":"#/components/parameters/paginationLimit"},{"$ref":"#/components/parameters/paginationAfter"},{"$ref":"#/components/parameters/formatParam"}],"responses":{"200":{"description":"Successfully retrieved sessions","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionList"}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean","example":true},"next":{"type":"string","example":"sess_123456789"},"total":{"type":"number","example":150}}}}},{"type":"array","description":"Zapier format response (returned when ?format=zapier is used)","items":{"$ref":"#/components/schemas/SessionZapier"}}]}}}},"400":{"description":"Bad request: invalid cursor (nonexistent, ineligible, or missing required fields) or invalid page size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sessions/{sessionId}":{"get":{"tags":["Sessions"],"summary":"Get session details","description":"Returns detailed information about a specific meeting session, including transcript, conversations, and meeting minutes.","parameters":[{"name":"sessionId","in":"path","required":true,"description":"Unique identifier of the session","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved session details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetail"},"example":{"sessionId":"sess_123456789","title":"Weekly Team Sync","startTime":"2024-03-15T14:30:00Z","endTime":"2024-03-15T15:15:00Z","duration":2700,"session_type":"meeting","transcript":"John: Let's review our progress...","cleaned_transcript":"John: Let's review our progress on the Q1 roadmap...","cleaned_at":"2024-03-15T16:00:00Z","conversations":"Q: What's the status?\nA: On track...","meeting_minutes":"1. Project Updates\n- Status: On track","recap":"Discussed Q1 goals and timeline","session_notes":"[{\"insert\":\"Key takeaway: focus on retention\\n\"}]","user_todos":[{"id":"uuid-todo-1","text":"Follow up with Marketing team re: campaign launch","dueDate":"Next Monday","completed":false,"topic":{"id":"topic_123xyz","name":"Project Alpha Discussion","color":"#FF5733","iconName":"lightbulb_outline"}},{"id":"uuid-todo-2","text":"Prepare slides for client presentation","dueDate":"2025-04-25T10:00:00Z","completed":true,"topic":{"id":"topic_456abc","name":"Client Onboarding","color":"#33AFFF","iconName":"person_add"}}],"topic":{"id":"topic_123xyz","name":"Project Alpha Discussion","color":"#FF5733","iconName":"lightbulb_outline"}}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/highlights":{"get":{"tags":["Highlights"],"summary":"List highlights","description":"Returns a list of highlights. Highlights are sorted by timestamp, newest first.\n\nSupports two response formats:\n- Standard API format with pagination (default)\n- Zapier format (flat array) when ?format=zapier is used\n\nZapier format returns all highlights by default. When limit or after parameters are provided with format=zapier, the flat array is paginated accordingly.","parameters":[{"$ref":"#/components/parameters/paginationLimit"},{"$ref":"#/components/parameters/paginationAfter"},{"$ref":"#/components/parameters/formatParam"}],"responses":{"200":{"description":"Successfully retrieved highlights","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/HighlightList"}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean","example":true},"next":{"type":"string","example":"high_123456789"},"total":{"type":"number","example":75}}}}},{"type":"array","description":"Zapier format response (returned when ?format=zapier is used)","items":{"$ref":"#/components/schemas/HighlightDetail"}}]}}}},"400":{"description":"Bad request: invalid cursor (nonexistent or missing timestamp field) or invalid page size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/highlights/{highlightId}":{"get":{"tags":["Highlights"],"summary":"Get highlight details","description":"Returns detailed information about a specific highlight, including the original quote, cleaned quote, and AI insights.","parameters":[{"name":"highlightId","in":"path","required":true,"description":"Unique identifier of the highlight","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved highlight details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HighlightDetail"}}}},"404":{"description":"Highlight not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create webhook","description":"Creates a new webhook subscription. Maximum of 50 webhooks per account.\n\nThe webhook URL must be HTTPS in production and will receive POST requests containing webhook event data.\n\nAvailable event types:\n- `session.created`: Sent when a new session is started. Payload uses the SessionDetail schema.\n- `session.ended`: Sent when a session finishes processing. Payload uses the SessionDetail schema (includes highlights array and structured_conversations).\n- `session.exported`: Sent when user manually exports a session via the app. Payload uses the SessionDetail schema with 'exportedAt' timestamp instead of 'endTime'.\n- `highlight.created`: Sent when a new highlight is generated. Payload uses the HighlightDetail schema.\n- `todo.exported`: Sent when a to-do item is marked for export. Payload uses the TodoExportedData schema (includes 'id', 'sessionId', 'text', 'dueDate').\n\nEach request will include the following headers:\n- X-Hedy-Signature: HMAC SHA-256 signature of the request body using your signing secret.\n- X-Hedy-Event: The type of event (e.g., \"session.created\").\n- Content-Type: application/json.\n\nTo verify webhook authenticity:\n1. Get the X-Hedy-Signature header value.\n2. Generate an HMAC SHA-256 of the raw request body using your signing secret.\n3. Compare the generated signature with the header value.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["url","event"],"description":"Subscribe to a single event using the 'event' field.","properties":{"url":{"type":"string","description":"HTTPS URL that will receive webhook events","example":"https://api.example.com/hedy-webhook"},"event":{"type":"string","description":"Single event to subscribe to","enum":["session.created","session.ended","session.exported","highlight.created","todo.exported"],"example":"session.created"}}},{"type":"object","required":["url","events"],"description":"Subscribe to multiple events using the 'events' array.","properties":{"url":{"type":"string","description":"HTTPS URL that will receive webhook events","example":"https://api.example.com/hedy-webhook"},"events":{"type":"array","description":"Array of events to subscribe to","items":{"type":"string","enum":["session.created","session.ended","session.exported","highlight.created","todo.exported"]},"example":["session.created","session.exported","highlight.created"]}}}]}}}},"responses":{"200":{"description":"Webhook created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/WebhookConfig"}}}}}},"400":{"description":"Invalid request (invalid URL, events, or webhook limit exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"Returns a list of configured webhooks for the authenticated user.","responses":{"200":{"description":"Successfully retrieved webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookConfig"}}}}}}}}}},"/webhooks/{webhookId}":{"delete":{"tags":["Webhooks"],"summary":"Delete webhook","description":"Deletes a webhook subscription.","parameters":[{"name":"webhookId","in":"path","required":true,"description":"ID of the webhook to delete","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"type":"string","example":"Webhook deleted successfully"}}}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/todos":{"get":{"tags":["Todos"],"summary":"Get all To-Do items","description":"Retrieves a list of all to-do items across all sessions for the authenticated user.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"A list of all to-do items.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AllTodosItem"}}}}},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sessions/{sessionId}/todos":{"get":{"tags":["Sessions","Todos"],"summary":"List to-do items for a session","description":"Returns a list of all user-specific to-do items associated with a specific session. Supports returning a flat array for Zapier integration via the `format=zapier` query parameter.","parameters":[{"name":"sessionId","in":"path","required":true,"description":"Unique identifier of the session","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Set to 'zapier' to receive a flat array response suitable for Zapier triggers.","schema":{"type":"string","enum":["zapier"]}}],"responses":{"200":{"description":"Successfully retrieved the list of to-do items","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/TodoItem"}}}},{"type":"array","description":"Zapier format response (when format=zapier)","items":{"$ref":"#/components/schemas/TodoItem"}}]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error or error during Zapier format processing","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"type":"array","description":"Empty array returned on error for Zapier format (when format=zapier)","items":{},"example":[]}]}}}}}}},"/sessions/{sessionId}/highlights":{"get":{"tags":["Sessions","Highlights"],"summary":"List highlights for a session","description":"Returns a list of all highlights associated with a specific session. Supports returning a flat array for Zapier integration via the `format=zapier` query parameter.","parameters":[{"name":"sessionId","in":"path","required":true,"description":"Unique identifier of the session","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Set to 'zapier' to receive a flat array response suitable for Zapier triggers.","schema":{"type":"string","enum":["zapier"]}}],"responses":{"200":{"description":"Successfully retrieved the list of highlights","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Standard response with wrapper","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","description":"Highlight with id and sessionId fields (note: this endpoint uses 'id' rather than 'highlightId')","properties":{"id":{"type":"string","example":"123456789"},"sessionId":{"type":"string","example":"sess_123456789"},"timestamp":{"type":"string","format":"date-time"},"timeIndex":{"type":"number","description":"Milliseconds from session start"},"title":{"type":"string"},"rawQuote":{"type":"string"},"cleanedQuote":{"type":"string"},"mainIdea":{"type":"string"},"aiInsight":{"type":"string"}}}}}},{"type":"array","description":"Zapier format response (when format=zapier)","items":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"timeIndex":{"type":"number"},"title":{"type":"string"},"rawQuote":{"type":"string"},"cleanedQuote":{"type":"string"},"mainIdea":{"type":"string"},"aiInsight":{"type":"string"}}}}]}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"type":"array","description":"Empty array returned on error for Zapier format","items":{},"example":[]}]}}}}}}},"/sessions/{sessionId}/todos/{todoId}":{"get":{"tags":["Sessions","Todos"],"summary":"Get specific to-do item","description":"Returns details for a specific user to-do item within a session, identified by its unique ID.","parameters":[{"name":"sessionId","in":"path","required":true,"description":"Unique identifier of the session","schema":{"type":"string"}},{"name":"todoId","in":"path","required":true,"description":"Unique identifier of the to-do item (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved to-do item details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/TodoItem"}}}}}},"404":{"description":"Session or To-do item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/topics/{topicId}/sessions":{"get":{"tags":["Topics","Sessions"],"summary":"List sessions for a topic","description":"Returns a list of all sessions associated with a specific topic, ordered by start time (descending). Each session includes its own details and the parent topic's information.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"topicId","in":"path","required":true,"description":"Unique identifier of the topic","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of sessions to return (default: 50, max: 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"startAfter","in":"query","description":"Session ID cursor for pagination. Returns sessions after this ID.","schema":{"type":"string"}},{"$ref":"#/components/parameters/formatParam"}],"responses":{"200":{"description":"Successfully retrieved sessions for the topic","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Standard response with wrapper","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","description":"Session associated with the topic.","properties":{"sessionId":{"type":"string","example":"sess_abc123"},"title":{"type":"string","example":"Session under Topic X"},"startTime":{"type":"string","format":"date-time"},"duration":{"type":"number","description":"Duration in seconds","example":2700},"session_type":{"type":"string","description":"Type of session (e.g., meeting, lecture, interview)","example":"meeting"},"topicInfo":{"$ref":"#/components/schemas/TopicInfo"}}}},"pagination":{"type":"object","properties":{"count":{"type":"integer","description":"Number of sessions in current page","example":10},"hasMore":{"type":"boolean","description":"Whether more sessions exist beyond the current page","example":true},"nextCursor":{"type":"string","nullable":true,"description":"Session ID to use as startAfter for the next page","example":"sess_xyz789"}}}}}}},{"type":"object","description":"Zapier format response (returned when ?format=zapier is used, no success wrapper)","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string"},"title":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"duration":{"type":"number","description":"Duration in seconds"},"session_type":{"type":"string"},"topicInfo":{"$ref":"#/components/schemas/TopicInfo"}}}},"pagination":{"type":"object","properties":{"count":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true}}}}}]}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/topics":{"get":{"tags":["Topics"],"summary":"List topics","description":"Returns a list of all topics for the authenticated user, ordered by last update time (descending). Each topic includes insights such as sessionCount, dominantSessionType, and overview when available.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/formatParam"}],"responses":{"200":{"description":"Successfully retrieved topics","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/TopicInfo"}}}},{"type":"array","description":"Zapier format response (returned when ?format=zapier is used)","items":{"$ref":"#/components/schemas/TopicInfo"}}]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Topics"],"summary":"Create topic","description":"Creates a new topic for organizing meeting sessions. Optionally include custom instructions (topicContext) that will be used for sessions under this topic.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTopicRequest"}}}},"responses":{"201":{"description":"Topic created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/TopicInfo"}}}}}},"400":{"description":"Validation error (invalid name, color format, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/topics/{topicId}":{"get":{"tags":["Topics"],"summary":"Get topic details","description":"Returns detailed information about a specific topic, including its topicContext if set and topic insights (sessionCount, dominantSessionType, overview, lastSessionDate).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"topicId","in":"path","required":true,"description":"Unique identifier of the topic","schema":{"type":"string"}},{"$ref":"#/components/parameters/formatParam"}],"responses":{"200":{"description":"Successfully retrieved topic details","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/TopicInfo"}}},{"$ref":"#/components/schemas/TopicInfo","description":"Zapier format response (returned when ?format=zapier is used)"}]}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"patch":{"tags":["Topics"],"summary":"Update topic","description":"Updates an existing topic. Only provided fields will be modified. Set topicContext to null to clear it.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"topicId","in":"path","required":true,"description":"Unique identifier of the topic to update","schema":{"type":"string"}},{"$ref":"#/components/parameters/formatParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTopicRequest"}}}},"responses":{"200":{"description":"Topic updated successfully","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/TopicInfo"}}},{"$ref":"#/components/schemas/TopicInfo","description":"Zapier format response (returned when ?format=zapier is used)"}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"tags":["Topics"],"summary":"Delete topic","description":"Deletes a topic and unlinks all associated sessions. Sessions are NOT deleted, only disassociated from the topic (their topicId is set to null).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"topicId","in":"path","required":true,"description":"Unique identifier of the topic to delete","schema":{"type":"string"}}],"responses":{"200":{"description":"Topic deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Topic deleted"}}}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/contexts":{"get":{"tags":["Session Contexts"],"summary":"List session contexts","description":"Returns all saved session contexts for the authenticated user, ordered by most recently updated.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"format","in":"query","required":false,"description":"Set to 'zapier' to receive a flat array response.","schema":{"type":"string","enum":["zapier"]}}],"responses":{"200":{"description":"Successfully retrieved session contexts","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionContextInfo"}}}},{"type":"array","description":"Zapier format response","items":{"$ref":"#/components/schemas/SessionContextInfo"}}]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Session Contexts"],"summary":"Create session context","description":"Creates a new session context. Free tier users are limited to 1 context. If isDefault is true, any existing default context will be unset.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionContextRequest"}}}},"responses":{"201":{"description":"Session context created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/SessionContextInfo"}}}}}},"400":{"description":"Validation error (title required, content too long, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Free tier limit exceeded (upgrade required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/contexts/{contextId}":{"get":{"tags":["Session Contexts"],"summary":"Get session context","description":"Returns a specific session context by its identifier.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"contextId","in":"path","required":true,"description":"Unique identifier of the session context","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Set to 'zapier' to receive a flat response.","schema":{"type":"string","enum":["zapier"]}}],"responses":{"200":{"description":"Successfully retrieved session context","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/SessionContextInfo"}}},{"$ref":"#/components/schemas/SessionContextInfo","description":"Zapier format response (returned when ?format=zapier is used)"}]}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"patch":{"tags":["Session Contexts"],"summary":"Update session context","description":"Updates an existing session context. Only provided fields will be modified. If isDefault is set to true, any existing default will be unset.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"contextId","in":"path","required":true,"description":"Unique identifier of the session context to update","schema":{"type":"string"}},{"$ref":"#/components/parameters/formatParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSessionContextRequest"}}}},"responses":{"200":{"description":"Session context updated successfully","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/SessionContextInfo"}}},{"$ref":"#/components/schemas/SessionContextInfo","description":"Zapier format response (returned when ?format=zapier is used)"}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"tags":["Session Contexts"],"summary":"Delete session context","description":"Deletes a session context. If the deleted context was the default, the most recently updated remaining context will be promoted to default.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"contextId","in":"path","required":true,"description":"Unique identifier of the session context to delete","schema":{"type":"string"}}],"responses":{"200":{"description":"Session context deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Session context deleted"}}}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}