{"openapi":"3.0.4","info":{"title":"Hedy API","version":"1.6.8","description":"API for accessing and managing Hedy meeting sessions, highlights, to-dos, topics, custom vocabulary 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)"},{"name":"Vocabulary","description":"Endpoints for managing the account custom vocabulary list"},{"name":"Account","description":"Endpoints for reading the authenticated user's own profile"}],"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":{"UserProfile":{"type":"object","description":"Profile of the user the API key belongs to, as returned by GET /me.","properties":{"id":{"type":"string","description":"Unique identifier of the authenticated user","example":"aBcDeFgHiJkLmNoPqRsTuVwXyZ12"},"email":{"type":"string","description":"Email address on the account. Empty string if not set.","example":"user@example.com"},"name":{"type":"string","description":"Display name on the account. Empty string if not set.","example":"Jane Doe"}}},"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 whole minutes, rounded up from any partial minute.","example":45},"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 whole minutes, rounded up from any partial minute.","example":45},"session_type":{"type":"string","description":"Type of session (e.g., meeting, lecture, interview)","example":"meeting"},"transcript":{"type":"string","description":"Transcript display string. Speaker labels resolve to the session’s current speaker names and change on rename; whitespace is collapsed.","example":"Ada: 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":"Markdown-capable meeting recap; legacy values may be plain text","example":"## Overview\n\nDiscussed Q1 goals.\n\n### Decisions\n\n- Ship Friday."},"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 whole minutes, rounded up from any partial minute.","example":45},"session_type":{"type":"string","description":"Type of session (e.g., meeting, lecture, interview)","example":"meeting"},"transcript":{"type":"string","description":"Transcript display string. Speaker labels resolve to the session’s current speaker names and change on rename; whitespace is collapsed.","example":"Ada: 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":"Markdown-capable meeting recap; legacy values may be plain text","example":"## Overview\n\nDiscussed Q1 goals.\n\n### Decisions\n\n- Ship Friday."},"cleaned_transcript":{"type":"string","nullable":true,"description":"AI-cleaned transcript display string (null if not yet generated). For current structured cleanups, speaker labels resolve to the session’s current speaker names and change on rename; turn separators and whitespace are preserved. Legacy or stale flat cleanups are returned unchanged.","example":"Ada:\nHello team.\n\nBob:\nNext topic."},"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. signingSecret is only returned from POST /webhooks (once at creation); all GET responses omit it.","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","suggestion.created"]},"example":["session.created","session.exported","highlight.created"]},"signingSecret":{"type":"string","description":"HMAC-SHA256 signing secret used to verify webhook request authenticity via the X-Hedy-Signature header. Returned ONLY from POST /webhooks, once at creation time. Store it securely — it is not recoverable.","example":"a1b2c3d4..."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookSessionPayload":{"type":"object","description":"Session fields carried by the `session.created`, `session.ended` and `session.exported` webhook events.\n\nThis is NOT the same shape as the REST `SessionDetail` schema. Webhook payloads use camelCase `sessionType` (REST uses `session_type`) and flat `topicId` / `topicName` / `topicInsights` (REST nests a `topic` object). `session.created` carries only `sessionId`, `title` and `startTime`; the remaining fields arrive on `session.ended`.","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:00.965Z"},"endTime":{"type":"string","format":"date-time","description":"Sent on `session.ended`. `session.exported` sends `exportedAt` instead.","example":"2024-03-15T15:15:00.168Z"},"exportedAt":{"type":"string","format":"date-time","description":"Sent on `session.exported` in place of `endTime`."},"duration":{"type":"number","description":"Duration in whole minutes, rounded up from any partial minute.","example":45},"sessionType":{"type":"string","description":"Type of session. Note the camelCase spelling — the REST API returns this same value as `session_type`.","example":"sales_meeting"},"transcript":{"type":"string"},"conversations":{"type":"string","description":"Structured conversation history rendered as text"},"structured_conversations":{"type":"array","description":"Machine-readable form of `conversations`. Note that `timestamp` here is epoch milliseconds, not an ISO date-time.","items":{"type":"object","properties":{"type":{"type":"string","enum":["suggestion","qa"],"description":"`suggestion` for messages Hedy raised on its own, `qa` for user-initiated exchanges.","example":"suggestion"},"question":{"type":"string","nullable":true},"answer":{"type":"string"},"timestamp":{"type":"number","nullable":true,"description":"Epoch milliseconds. Null on the rare row persisted without one.","example":1784642731477}}}},"meeting_minutes":{"type":"string"},"recap":{"type":"string"},"session_notes":{"type":"string","description":"User-authored notes in Parchment JSON (Delta) format; empty string when none. Emitted by client versions 3.4.0 and later."},"highlights":{"type":"array","items":{"$ref":"#/components/schemas/EmbeddedHighlight"}},"topicId":{"type":"string","description":"Omitted entirely when the session has no associated topic."},"topicName":{"type":"string","description":"Omitted when the session has no associated topic, and may be omitted on its own if the topic lookup fails while `topicId` resolves."},"topicInsights":{"type":"string","description":"JSON string containing the topic's cached overview/insights, when available."}}},"WebhookEvent":{"description":"The JSON body POSTed to a registered webhook URL.\n\n**The payload is flat.** The event-specific fields are merged into the top level alongside `event` — there is no nested `data` object and no top-level `timestamp`. The delivered body is exactly `{ event, ...eventData }`.\n\nDiscriminate on the `event` property or on the `X-Hedy-Event` request header.","example":{"event":"session.ended","sessionId":"sess_123456789","title":"Weekly Team Sync","startTime":"2024-03-15T14:30:00.965Z","endTime":"2024-03-15T15:15:00.168Z","duration":45,"sessionType":"sales_meeting","transcript":"John: Let's review our progress...","recap":"## Overview\n\nDiscussed Q1 goals.","highlights":[]},"oneOf":[{"title":"Session events (session.created, session.ended, session.exported)","allOf":[{"type":"object","required":["event"],"properties":{"event":{"type":"string","enum":["session.created","session.ended","session.exported"]}}},{"$ref":"#/components/schemas/WebhookSessionPayload"}]},{"title":"highlight.created","allOf":[{"type":"object","required":["event"],"properties":{"event":{"type":"string","enum":["highlight.created"]}}},{"$ref":"#/components/schemas/HighlightDetail"}]},{"title":"todo.exported","allOf":[{"type":"object","required":["event"],"properties":{"event":{"type":"string","enum":["todo.exported"]}}},{"$ref":"#/components/schemas/TodoExportedData"}]},{"title":"suggestion.created","allOf":[{"type":"object","required":["event"],"properties":{"event":{"type":"string","enum":["suggestion.created"]}}},{"$ref":"#/components/schemas/SuggestionData"}]}]},"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},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of the latest to-do state update"},"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"}}},"SuggestionData":{"type":"object","description":"Payload structure for the 'suggestion.created' webhook event.","properties":{"suggestionId":{"type":"string","description":"ID of the automatic suggestion message","example":"msg_123456789"},"sessionId":{"type":"string","description":"ID of the session where the suggestion was displayed","example":"sess_123456789"},"message":{"type":"string","description":"The suggestion text shown to the user","example":"Ask about the budget timeline."},"sessionType":{"type":"string","description":"Resolved session type name, when available","example":"business"},"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the suggestion event was created","example":"2026-06-19T12:34:56.000Z"}}},"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. Topics created in the app are stored without a leading hash.","example":"4A90D9"},"iconName":{"type":"string","nullable":true,"description":"Icon codepoint as a number, in decimal or 0x hex.","example":"59475"},"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":"Session type seed for new sessions under this topic; recomputed automatically from session history after sessions accumulate","example":"business_meetings"},"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, with or without the leading hash (e.g., #FF5733 or FF5733)","example":"#4A90D9"},"iconName":{"type":"string","description":"Icon codepoint as a number, in decimal or 0x hex (e.g., 59475 or 0xe853). Any emoji codepoint renders. Icon names such as 'groups' are accepted by the API but fall back to a default folder icon in the app.","example":"59475"},"topicContext":{"type":"string","description":"Custom instructions for this topic (max 20,000 characters)","example":"Focus on blockers and next steps"},"dominantSessionType":{"type":"string","nullable":true,"enum":["business_meetings","lecture_class","coaching_mentoring","recruitment_call","job_interview_candidate","negotiation","sales_meeting","journalism","spiritual_teaching","solo_brainstorm","group_brainstorm","personal_conversation","medical_consultation"],"description":"Seeds the session type for sessions started under this topic. Recomputed automatically from history after sessions accumulate.","example":"business_meetings"}}},"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, with or without the leading hash"},"iconName":{"type":"string","description":"New icon codepoint as a number, in decimal or 0x hex. See the create request for details."},"topicContext":{"type":"string","nullable":true,"description":"New custom instructions (set to null to clear)"},"dominantSessionType":{"type":"string","nullable":true,"enum":["business_meetings","lecture_class","coaching_mentoring","recruitment_call","job_interview_candidate","negotiation","sales_meeting","journalism","spiritual_teaching","solo_brainstorm","group_brainstorm","personal_conversation","medical_consultation"],"description":"Seeds the session type for sessions started under this topic. Recomputed automatically from history after sessions accumulate. Set to null to clear.","example":"negotiation"}}},"Vocabulary":{"type":"object","required":["terms","enabled"],"properties":{"terms":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"The account custom vocabulary terms."},"enabled":{"type":"boolean","description":"Whether custom vocabulary matching is enabled."}}},"SetVocabularyRequest":{"type":"object","required":["terms"],"properties":{"terms":{"type":"array","maxItems":100,"items":{"type":"string","minLength":2,"maxLength":50},"description":"Complete replacement list. Terms must be unique case-insensitively and cannot contain < > { } [ ] \\ | ` or ~; any stored terms omitted here are removed."},"enabled":{"type":"boolean","description":"Whether custom vocabulary matching is enabled. Omit to preserve the stored value."}}},"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":{"/vocabulary":{"get":{"tags":["Vocabulary"],"summary":"Get custom vocabulary","description":"Returns the complete account custom vocabulary list and whether vocabulary matching is enabled.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Custom vocabulary retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Vocabulary"}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"put":{"tags":["Vocabulary"],"summary":"Replace custom vocabulary","description":"Replaces the complete account custom vocabulary list. Any stored terms omitted from the supplied list are removed; omit enabled to preserve its current value.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetVocabularyRequest"}}}},"responses":{"200":{"description":"Custom vocabulary replaced successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Vocabulary"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/me":{"get":{"tags":["Account"],"summary":"Get the authenticated user's profile","description":"Returns the profile of the user the API key belongs to. Useful as a lightweight credential check: it exercises the same authentication, region routing and subscription checks as every other API-key endpoint, but reads a single document rather than a collection.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"The authenticated user's profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - the account does not have an active Pro subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/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}":{"patch":{"tags":["Sessions"],"summary":"Assign session to topic","description":"Moves a cloud-synced session to a topic and invalidates affected topic overview caches. Set topicId to null or an empty string to remove the assignment. Repeating the current assignment succeeds without writing unless the session has Cloud Sync off or the target topic is being deleted. Only topicId is accepted; other request fields are ignored.","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/formatParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topicId"],"properties":{"topicId":{"type":"string","nullable":true,"description":"Topic document ID, or null or an empty string to unassign."}}}}}},"responses":{"200":{"description":"Session topic assignment updated","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","required":["sessionId","topicId"],"properties":{"sessionId":{"type":"string"},"topicId":{"type":"string","nullable":true}}}}},{"type":"object","description":"Zapier format response (returned when ?format=zapier is used)","required":["sessionId","topicId"],"properties":{"sessionId":{"type":"string"},"topicId":{"type":"string","nullable":true}}}]}}}},"400":{"description":"validation_error: topicId is missing or is neither a string nor null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"session_not_found: session does not exist; not_found: topic does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"session_not_synced: session has Cloud Sync off; turn on Cloud Sync before moving or unassigning it. deletion_in_progress: target topic is being deleted; unassigning a synced session remains allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}},"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":45,"session_type":"meeting","transcript":"Ada: Let's review our progress...","cleaned_transcript":"Ada:\nHello team.\n\nBob:\nNext topic.","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":"## Overview\n\nDiscussed Q1 goals.\n\n### Decisions\n\n- Ship Friday.","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":"59475"}},{"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":"57543"}}],"topic":{"id":"topic_123xyz","name":"Project Alpha Discussion","color":"#FF5733","iconName":"59475"}}}}},"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\n**The delivered body is described by the `WebhookEvent` schema** (see the Schemas section). It is flat: the event-specific fields sit at the top level alongside `event`, with no nested `data` object and no top-level `timestamp`.\n\nAvailable event types:\n- `session.created`: Sent when a new session is started. Payload is a minimal stub containing only `sessionId`, `title`, and `startTime`; the remaining WebhookSessionPayload fields are populated on the subsequent `session.ended` event.\n- `session.ended`: Sent when a session finishes processing. Includes highlights array, structured_conversations, sessionType, session_notes (user-authored notes in Parchment JSON / Delta format; empty string if none), and (when the session is linked to a topic) topicId, topicName, and topicInsights, in addition to the base WebhookSessionPayload fields.\n- `session.exported`: Sent when a user manually exports a session via the app. Same fields as `session.ended` (including `session_notes` and `topicInsights` when the linked topic has a cached overview), but with an `exportedAt` timestamp instead of `endTime`. Note that `topicInsights` is resolved from the topic's current cached overview at export time, so it can differ from the value previously sent on `session.ended` if the topic overview has been regenerated since.\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- `suggestion.created`: Sent each time Hedy displays an automatic feedback suggestion during a live session. Payload uses the SuggestionData schema (`suggestionId` — the id of the suggestion message, `sessionId`, `message`, `sessionType`, `timestamp`). Fires once per suggestion; expect multiple per session (at most about one per minute).\n\n**Note on webhook payload field naming:** Webhook payloads use camelCase field names (`sessionType`, `topicId`, `topicName`) and flat topic fields, unlike the REST API's SessionDetail schema which uses snake_case (`session_type`) and a nested `topic` object. For session events, `topicId` and `topicName` are omitted entirely when the session has no associated topic; `topicName` alone may be omitted if the topic lookup fails but `topicId` resolves.\n\n**Client version requirement:** Webhook payloads are constructed on-device by the Hedy desktop/mobile app and relayed to your webhook URL. Hedy desktop/mobile client versions 3.2.0 and later introduce the following changes:\n\n- `session.exported` reaches full field parity with `session.ended`, gaining `sessionType`, `topicId`, `topicName`, `topicInsights`, and a corrected `duration` value (previously often `0`).\n- `session.ended` gains `sessionType` (previously absent; `topicId`, `topicName`, and `topicInsights` were already present when the session was linked to a topic).\n\nHedy desktop/mobile client versions 3.4.0 and later additionally emit `session_notes` on both `session.ended` and `session.exported` (Parchment JSON / Delta format; empty string when the user has not authored any notes).\n\nEvents fired by devices still running older versions will emit the older reduced payload shape.\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","suggestion.created"],"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","suggestion.created"]},"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"}}}}}},"patch":{"tags":["Sessions","Todos"],"summary":"Update to-do state","description":"Updates completion, due date, or both for a stable-id to-do item without replacing the session's to-do array. An empty dueDate clears the due date.","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"todoId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"completed":{"type":"boolean"},"dueDate":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"To-do state updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/TodoItem"}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session or to-do item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/topics/{topicId}/sessions":{"get":{"tags":["Topics","Sessions"],"summary":"List sessions for a topic","description":"Returns a page of sessions associated with a specific topic, ordered by start time (descending); use the `startAfter` cursor to retrieve subsequent pages. 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 whole minutes, rounded up from any partial minute.","example":45},"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 whole minutes, rounded up from any partial minute."},"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"}}}}}}