{"openapi":"3.1.0","info":{"title":"Sylva API","version":"1.0.0","description":"The Sylva REST API gives Team plan accounts programmatic read/write access to all their data — conversations, tasks, notes, captures, entities, topics, voice notes, collections, research items, and meetings.\n\n## Authentication\n\nAll API endpoints require a Bearer token obtained via [OAuth 2.0 Authorization Code flow](https://mysylva.app/developers#authentication).\n\n```\nAuthorization: Bearer sylva_oauth_<token>\n```\n\n## Rate Limiting\n\nAll `/api/v1/*` endpoints are limited to **1,000 requests per minute** per user. Exceeded requests return HTTP 429.\n\n## Pagination\n\nAll list endpoints support `limit` (max 200, default 50), `offset`, `sort`, and `order` query params. Responses include a `meta` object with `total`, `limit`, `offset`, and `has_more`.\n\n## Errors\n\nErrors follow `{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"...\" } }`. See the `Error` schema for all codes.","contact":{"name":"Sylva","url":"https://mysylva.app/contact"}},"servers":[{"url":"https://app.mysylva.app","description":"Production"}],"tags":[{"name":"Conversations","description":"Threaded discussions with messages"},{"name":"Messages","description":"Individual entries within a conversation"},{"name":"Tasks","description":"To-do items with due dates and status"},{"name":"Notes","description":"Free-form notes"},{"name":"Captures","description":"Items captured from external sources"},{"name":"Entities","description":"People, organizations, projects in the knowledge graph"},{"name":"Topics","description":"Organizational groupings for conversations"},{"name":"Meetings","description":"Meeting recordings with transcripts and AI analysis"},{"name":"VoiceNotes","description":"Voice memos with transcripts (read-only via API)"},{"name":"Collections","description":"Custom typed tables of items"},{"name":"Research","description":"Saved research items with AI summaries"},{"name":"Profile","description":"Current user profile"},{"name":"Bulk","description":"Bulk import and export for migrations"},{"name":"Webhooks","description":"Real-time event notifications"},{"name":"OAuth","description":"OAuth 2.0 token endpoint"}],"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code","enum":["UNAUTHORIZED","SCOPE_REQUIRED","FORBIDDEN","FEATURE_LOCKED","NOT_FOUND","INVALID_REQUEST","RATE_LIMITED","SERVER_ERROR","NOT_SUPPORTED","IMPORT_ERROR"],"example":"INVALID_REQUEST"},"message":{"type":"string","description":"Human-readable error message","example":"title is required"},"required_scope":{"type":"string","description":"Required scope (only present for SCOPE_REQUIRED)","example":"tasks:write"}}}}},"PaginationMeta":{"type":"object","required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer","description":"Total number of records matching the query","example":142},"limit":{"type":"integer","description":"Page size used","example":50},"offset":{"type":"integer","description":"Page offset used","example":0},"has_more":{"type":"boolean","description":"True if more records exist beyond this page","example":true}}},"Conversation":{"type":"object","description":"A conversation thread containing messages","required":["id","user_id","is_archived","is_pinned"],"properties":{"id":{"type":"string","format":"uuid","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"user_id":{"type":"string","format":"uuid","readOnly":true},"title":{"type":"string","nullable":true,"example":"Q2 product planning"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","nullable":true},"is_main_thread":{"type":"boolean","default":false,"readOnly":true},"is_archived":{"type":"boolean","default":false,"example":false},"is_pinned":{"type":"boolean","default":false,"example":false},"is_ask_sylva":{"type":"boolean","default":false,"readOnly":true},"topic_id":{"type":"string","format":"uuid","nullable":true},"folder_id":{"type":"string","format":"uuid","nullable":true},"summary":{"type":"string","nullable":true,"readOnly":true},"summary_generated_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"tag_ids":{"type":"array","items":{"type":"string"},"default":[],"example":[]},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}},"example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","user_id":"e2302adf-7a8a-4355-b6b0-06f50328dd7b","title":"Q2 product planning","context":"work","is_archived":false,"is_pinned":true,"tag_ids":[],"created_at":"2026-05-01T14:23:00Z","updated_at":"2026-05-04T09:15:00Z"}},"ConversationCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","example":"Q2 product planning"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"},"tag_ids":{"type":"array","items":{"type":"string"},"default":[]}}},"ConversationUpdate":{"type":"object","properties":{"title":{"type":"string"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"},"is_archived":{"type":"boolean"},"is_pinned":{"type":"boolean"},"tag_ids":{"type":"array","items":{"type":"string"}},"folder_id":{"type":"string","format":"uuid","nullable":true}}},"Message":{"type":"object","description":"An individual message within a conversation","required":["id","conversation_id","user_id","role","message_type"],"properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"role":{"type":"string","enum":["user","assistant","system"],"example":"user"},"content":{"type":"string","nullable":true,"example":"What did we decide about pricing?"},"message_type":{"type":"string","enum":["text","voice","reaction"],"default":"text"},"audio_url":{"type":"string","nullable":true,"format":"uri"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","nullable":true},"is_pinned":{"type":"boolean","default":false},"is_bookmarked":{"type":"boolean","default":false},"extracted_entities":{"type":"object","additionalProperties":true,"default":{},"readOnly":true},"metadata":{"type":"object","additionalProperties":true,"default":{}},"created_at":{"type":"string","format":"date-time","readOnly":true}}},"MessageCreate":{"type":"object","required":["content"],"properties":{"content":{"type":"string","example":"What did we decide about pricing?"},"role":{"type":"string","enum":["user","assistant","system"],"default":"user"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"}}},"MessageUpdate":{"type":"object","properties":{"content":{"type":"string"},"is_bookmarked":{"type":"boolean"},"is_pinned":{"type":"boolean"}}},"Task":{"type":"object","description":"A to-do item","required":["id","user_id","content","status"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"content":{"type":"string","description":"What needs to be done","example":"Review Q2 metrics report"},"notes":{"type":"string","nullable":true,"description":"Additional details","example":"Focus on conversion funnel"},"status":{"type":"string","enum":["pending","completed","dismissed"],"example":"pending","default":"pending"},"due_date":{"type":"string","format":"date-time","nullable":true,"example":"2026-05-15T17:00:00Z"},"snoozed_until":{"type":"string","format":"date-time","nullable":true},"is_long_term":{"type":"boolean","default":false,"description":"True for goals/long-term tasks (no due date pressure)"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"personal"},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"conversation_id":{"type":"string","format":"uuid","nullable":true,"description":"Source conversation that produced this task"},"message_id":{"type":"string","format":"uuid","nullable":true,"description":"Source message that produced this task"},"source_type":{"type":"string","nullable":true,"example":"api"},"source_id":{"type":"string","format":"uuid","nullable":true},"last_referenced":{"type":"string","format":"date-time","readOnly":true},"completed_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true}},"example":{"id":"8b1d3e5f-2a4c-4d6e-8f0a-1b2c3d4e5f60","user_id":"e2302adf-7a8a-4355-b6b0-06f50328dd7b","content":"Review Q2 metrics report","notes":"Focus on conversion funnel","status":"pending","due_date":"2026-05-15T17:00:00Z","is_long_term":false,"context":"work","tag_ids":[],"conversation_id":null,"created_at":"2026-05-05T10:00:00Z"}},"TaskCreate":{"type":"object","required":["content"],"properties":{"content":{"type":"string","example":"Review Q2 metrics report"},"notes":{"type":"string","nullable":true,"example":"Focus on conversion funnel"},"due_date":{"type":"string","format":"date-time","nullable":true,"example":"2026-05-15T17:00:00Z"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"},"is_long_term":{"type":"boolean","default":false},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"conversation_id":{"type":"string","format":"uuid","nullable":true}}},"TaskUpdate":{"type":"object","properties":{"content":{"type":"string"},"notes":{"type":"string","nullable":true},"due_date":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["pending","completed","dismissed"],"example":"pending"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"},"is_long_term":{"type":"boolean"},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"snoozed_until":{"type":"string","format":"date-time","nullable":true}}},"Note":{"type":"object","description":"A free-form note","required":["id","user_id","title","framework"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"title":{"type":"string","example":"Pricing decision rationale"},"content":{"type":"string","description":"Markdown body","default":"","example":"We chose tiered pricing because..."},"raw_content":{"type":"string","nullable":true,"description":"Original unprocessed content"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","nullable":true},"framework":{"type":"string","description":"Note type/framework","default":"manual","example":"manual"},"template_key":{"type":"string","nullable":true},"is_auto_generated":{"type":"boolean","default":false,"readOnly":true},"parent_id":{"type":"string","format":"uuid","nullable":true},"parent_type":{"type":"string","nullable":true,"example":"topic"},"source_message_ids":{"type":"array","items":{"type":"string"},"default":[],"readOnly":true},"tag_ids":{"type":"array","items":{"type":"string"},"default":[]},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}},"example":{"id":"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","user_id":"e2302adf-7a8a-4355-b6b0-06f50328dd7b","title":"Pricing decision rationale","content":"We chose tiered pricing because...","context":"work","framework":"manual","tag_ids":[],"created_at":"2026-05-04T16:30:00Z","updated_at":"2026-05-04T16:30:00Z"}},"NoteCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","example":"Pricing decision rationale"},"content":{"type":"string","example":"We chose tiered pricing because..."},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"},"tag_ids":{"type":"array","items":{"type":"string"},"default":[]},"conversation_id":{"type":"string","format":"uuid","nullable":true}}},"NoteUpdate":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"},"tag_ids":{"type":"array","items":{"type":"string"}}}},"Capture":{"type":"object","description":"An item captured from an external source (browser extension, email, API, etc.)","required":["id","user_id","source","content","context"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"source":{"type":"string","description":"Origin of the capture","example":"api","examples":["api","web","email","slack","extension"]},"source_id":{"type":"string","nullable":true,"description":"External ID for deduplication"},"title":{"type":"string","nullable":true,"example":"Weekly metrics report"},"content":{"type":"string","description":"Body of the capture","example":"Revenue up 12% WoW. Churn down to 3.1%."},"sender":{"type":"string","nullable":true,"example":"alice@example.com"},"recipients":{"type":"array","items":{"type":"string"},"nullable":true},"source_url":{"type":"string","format":"uri","nullable":true,"example":"https://internal-dashboard.example.com/reports/42"},"captured_at":{"type":"string","format":"date-time"},"ingested_at":{"type":"string","format":"date-time","readOnly":true},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"},"is_processed":{"type":"boolean","default":false,"readOnly":true},"is_actionable":{"type":"boolean","default":false},"ai_summary":{"type":"string","nullable":true,"readOnly":true},"extracted_tasks":{"type":"array","items":{"type":"object"},"default":[],"readOnly":true},"metadata":{"type":"object","additionalProperties":true,"default":{}},"tag_ids":{"type":"array","items":{"type":"string"},"default":[]},"conversation_id":{"type":"string","nullable":true},"parent_capture_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true}}},"CaptureCreate":{"type":"object","required":["content"],"properties":{"content":{"type":"string","example":"Revenue up 12% WoW. Churn down to 3.1%."},"title":{"type":"string","example":"Weekly metrics report"},"source":{"type":"string","default":"api","example":"api"},"source_id":{"type":"string","nullable":true,"description":"Optional unique ID for deduplication"},"source_url":{"type":"string","format":"uri","nullable":true},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"},"captured_at":{"type":"string","format":"date-time","description":"Defaults to now if omitted"},"tag_ids":{"type":"array","items":{"type":"string"},"default":[]}}},"CaptureUpdate":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"},"tag_ids":{"type":"array","items":{"type":"string"}},"is_actionable":{"type":"boolean"},"is_processed":{"type":"boolean"}}},"Entity":{"type":"object","description":"A person, organization, project, or concept in the knowledge graph","required":["id","user_id","name","type"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","example":"Acme Corp"},"type":{"type":"string","enum":["person","organization","project","decision","commitment","concept"],"example":"organization"},"aliases":{"type":"array","items":{"type":"string"},"default":[],"example":["Acme","ACME"]},"attributes":{"type":"object","additionalProperties":true,"default":{},"example":{"industry":"SaaS","website":"acme.com"}},"mention_count":{"type":"integer","default":1,"readOnly":true},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"default":0.5,"readOnly":true},"is_active":{"type":"boolean","default":true},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"both"},"first_seen_at":{"type":"string","format":"date-time","readOnly":true},"last_seen_at":{"type":"string","format":"date-time","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"EntityCreate":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","example":"Acme Corp"},"type":{"type":"string","enum":["person","organization","project","decision","commitment","concept"],"example":"organization"},"aliases":{"type":"array","items":{"type":"string"},"default":[]},"attributes":{"type":"object","additionalProperties":true,"default":{}},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"both"}}},"EntityUpdate":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["person","organization","project","decision","commitment","concept"]},"aliases":{"type":"array","items":{"type":"string"}},"attributes":{"type":"object","additionalProperties":true},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"},"is_active":{"type":"boolean"}}},"Topic":{"type":"object","description":"An organizational grouping for conversations","required":["id","user_id","name"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","example":"Customer Discovery"},"description":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"example":"#3b82f6"},"icon":{"type":"string","nullable":true,"example":"lightbulb"},"status":{"type":"string","enum":["active","candidate","archived"],"default":"candidate"},"is_pinned":{"type":"boolean","default":false},"parent_topic_id":{"type":"string","format":"uuid","nullable":true},"quality_score":{"type":"number","format":"float","default":0,"readOnly":true},"conversations_count":{"type":"integer","default":0,"readOnly":true},"messages_count":{"type":"integer","default":0,"readOnly":true},"access_count":{"type":"integer","default":0,"readOnly":true},"last_active_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"TopicCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Customer Discovery"},"description":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"example":"#3b82f6"},"icon":{"type":"string","nullable":true}}},"TopicUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","candidate","archived"]},"is_pinned":{"type":"boolean"}}},"Meeting":{"type":"object","description":"A meeting recording with transcript and AI analysis","required":["id","user_id","title","context","status","analysis_status"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"title":{"type":"string","example":"Acme Corp — kickoff"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"personal"},"status":{"type":"string","enum":["recording","completed","failed"],"example":"completed"},"analysis_status":{"type":"string","enum":["pending","analyzing","done","failed"],"default":"pending"},"analysis_error":{"type":"string","nullable":true,"readOnly":true},"duration_seconds":{"type":"integer","nullable":true,"example":1830},"audio_size_bytes":{"type":"integer","format":"int64","nullable":true,"readOnly":true},"audio_storage_path":{"type":"string","nullable":true,"readOnly":true},"transcript_text":{"type":"string","nullable":true,"readOnly":true,"description":"Full transcript text"},"ai_summary":{"type":"object","additionalProperties":true,"nullable":true,"readOnly":true,"description":"AI-generated structured summary (action items, decisions, key points)"},"speaker_labels":{"type":"object","additionalProperties":true,"default":{},"readOnly":true},"transcribed_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"conversation_id":{"type":"string","format":"uuid","nullable":true},"tag_ids":{"type":"array","items":{"type":"string"},"default":[]},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"MeetingCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","example":"Acme Corp — kickoff"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"},"transcript_text":{"type":"string","nullable":true,"description":"Optional. Provide transcript text to trigger AI analysis; without it the meeting is saved as done with no summary"},"tag_ids":{"type":"array","items":{"type":"string"},"default":[]}}},"MeetingUpdate":{"type":"object","properties":{"title":{"type":"string"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"},"tag_ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["recording","completed","failed"]}}},"VoiceNote":{"type":"object","description":"A voice memo with transcript and AI summary. Cannot be created via API (audio upload is app-only); read and metadata-update only.","required":["id","user_id","title","analysis_status"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"title":{"type":"string","example":"Brainstorm — pricing tiers"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","nullable":true},"transcript":{"type":"string","nullable":true,"readOnly":true},"duration_seconds":{"type":"integer","default":0,"readOnly":true},"analysis_status":{"type":"string","enum":["pending","analyzing","done","failed"],"default":"pending"},"voice_summary":{"type":"object","additionalProperties":true,"nullable":true,"readOnly":true},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"conversation_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"VoiceNoteUpdate":{"type":"object","properties":{"title":{"type":"string"},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"}}},"Collection":{"type":"object","description":"A custom typed table of items","required":["id","user_id","name","schema"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","example":"Vendors"},"description":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true,"default":"database"},"schema":{"type":"object","description":"Field definitions for items in this collection","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"}}}}},"example":{"fields":[{"name":"vendor_name","type":"string","required":true},{"name":"annual_cost","type":"number"}]}},"conversation_id":{"type":"string","format":"uuid","nullable":true},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"context":{"type":"string","nullable":true,"description":"Profile slug the collection belongs to, or null for none (shows under every profile)","example":"work"},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"CollectionCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Vendors"},"description":{"type":"string","nullable":true},"schema":{"type":"object","additionalProperties":true,"example":{"fields":[]}},"icon":{"type":"string","nullable":true,"default":"database"},"context":{"type":"string","nullable":true,"description":"Profile slug, or null / \"none\" for no profile. Omitted = none (an API call has no active profile)."}}},"CollectionUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"schema":{"type":"object","additionalProperties":true},"icon":{"type":"string","nullable":true},"context":{"type":"string","nullable":true,"description":"Profile slug, or null / \"none\" for no profile. Omitted = unchanged."}}},"CollectionItem":{"type":"object","description":"An item within a collection","required":["id","user_id","collection_id","data"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"collection_id":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true,"description":"Field values matching the collection's schema","example":{"vendor_name":"Acme Corp","annual_cost":24000}},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"CollectionItemCreate":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"example":{"vendor_name":"Acme Corp","annual_cost":24000}}}},"ResearchItem":{"type":"object","description":"A saved research item (URL or pasted text) with AI summary","required":["id","user_id","url_type","status","source_type"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"url":{"type":"string","format":"uri","nullable":true,"example":"https://example.com/article"},"url_type":{"type":"string","description":"Content type detected from URL","example":"article"},"title":{"type":"string","nullable":true,"example":"The Future of SaaS Pricing"},"thumbnail_url":{"type":"string","format":"uri","nullable":true},"author":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true,"example":"example.com"},"source_type":{"type":"string","enum":["url","paste","file"],"default":"url"},"pasted_text":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true},"ai_summary":{"type":"string","nullable":true,"readOnly":true},"ai_notes":{"type":"string","nullable":true,"description":"AI-generated structured notes"},"ai_notes_sections":{"type":"object","additionalProperties":true,"nullable":true,"readOnly":true},"status":{"type":"string","enum":["pending","extracting","analyzing","complete","failed"],"default":"pending"},"error":{"type":"string","nullable":true,"readOnly":true},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","nullable":true},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"},"default":[]},"conversation_id":{"type":"string","format":"uuid","nullable":true},"message_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"ResearchItemCreate":{"type":"object","description":"Provide either url OR pasted_text","properties":{"url":{"type":"string","format":"uri","example":"https://example.com/article"},"pasted_text":{"type":"string","description":"Use this for text not from a URL"},"title":{"type":"string","nullable":true},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work","default":"work"}}},"ResearchItemUpdate":{"type":"object","properties":{"title":{"type":"string"},"context":{"type":"string","description":"A profile slug such as work or personal, or both","example":"work"},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"ai_notes":{"type":"string","nullable":true}}},"Profile":{"type":"object","description":"Current user profile","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"avatar_url":{"type":"string","format":"uri","nullable":true},"timezone":{"type":"string","nullable":true,"example":"America/Los_Angeles"},"subscription_tier":{"type":"string","nullable":true,"example":"team"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","description":"A webhook endpoint that receives event notifications","required":["id","user_id","url","events","is_active"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","readOnly":true},"url":{"type":"string","format":"uri","description":"HTTPS URL that receives POST callbacks","example":"https://yourapp.com/webhooks/sylva"},"description":{"type":"string","nullable":true,"example":"Production webhook"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to subscribe to. Use ['*'] for all events.","example":["task.created","task.updated","task.deleted"]},"is_active":{"type":"boolean","default":true},"failure_count":{"type":"integer","default":0,"readOnly":true,"description":"Consecutive delivery failures"},"last_success_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"last_failure_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"WebhookEndpointCreate":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","example":"https://yourapp.com/webhooks/sylva"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string","enum":["*","conversation.created","conversation.updated","conversation.deleted","message.created","message.updated","message.deleted","task.created","task.updated","task.deleted","note.created","note.updated","note.deleted","capture.created","capture.updated","capture.deleted","entity.created","entity.updated","entity.deleted","topic.created","topic.updated","topic.deleted","meeting.created","meeting.updated","meeting.deleted","collection.created","collection.updated","collection.deleted"]},"example":["task.created","task.updated"]}}},"WebhookEndpointCreateResponse":{"type":"object","required":["data","secret"],"properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"HMAC signing secret. Returned ONCE on creation. Save it — used to verify the X-Sylva-Signature header on incoming webhook requests.","example":"a3f9c12b8e4d7f6a5b3c1d2e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a"}}},"WebhookEndpointUpdate":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string","example":"task.created"},"response_status":{"type":"integer","nullable":true,"example":200},"attempt_number":{"type":"integer","example":1},"delivered_at":{"type":"string","format":"date-time","nullable":true},"next_retry_at":{"type":"string","format":"date-time","nullable":true,"description":"If non-null, this delivery will be retried"},"created_at":{"type":"string","format":"date-time"}}},"WebhookPayload":{"type":"object","description":"Payload sent to your webhook URL","required":["id","type","created_at","data"],"properties":{"id":{"type":"string","description":"Unique event ID for idempotent processing","example":"evt_a3f9c12b8e4d7f6a5b3c1d"},"type":{"type":"string","description":"Event type","example":"task.created"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Full entity object after the change. For .deleted events, contains the deleted record."},"previous_data":{"type":"object","additionalProperties":true,"nullable":true,"description":"Entity state before the change. Only present for .updated events."}}},"BulkImportRequest":{"type":"object","required":["entity","items"],"properties":{"entity":{"type":"string","enum":["tasks","notes","captures","topics","conversations"],"example":"tasks"},"items":{"type":"array","maxItems":500,"items":{"type":"object","additionalProperties":true},"description":"Up to 500 items. user_id is automatically stamped — do not include it."}}},"BulkImportResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"imported":{"type":"integer","example":47},"ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}}},"BulkExportRequest":{"type":"object","required":["entity"],"properties":{"entity":{"type":"string","enum":["tasks","notes","captures","topics","conversations","entities","meetings","research","voice_notes","collections"],"example":"tasks"},"filters":{"type":"object","description":"Optional equality filters","properties":{"context":{"type":"string","description":"A profile slug such as work or personal, or both"},"status":{"type":"string"},"source":{"type":"string"},"type":{"type":"string"},"is_active":{"type":"boolean"},"is_long_term":{"type":"boolean"}}},"limit":{"type":"integer","maximum":10000,"default":10000}}},"BulkExportResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","properties":{"entity":{"type":"string"},"exported":{"type":"integer"},"total":{"type":"integer"},"truncated":{"type":"boolean","description":"True if there are more records than the limit returned"}}}}}},"securitySchemes":{"BearerAuth":{"type":"oauth2","description":"OAuth 2.0 with Authorization Code flow. Register an app in Settings → Developer to get client credentials.","flows":{"authorizationCode":{"authorizationUrl":"https://app.mysylva.app/api/oauth/authorize","tokenUrl":"https://app.mysylva.app/api/oauth/token","refreshUrl":"https://app.mysylva.app/api/oauth/token","scopes":{"conversations:read":"View conversations and threads","conversations:write":"Create, update, and delete conversations","messages:read":"View messages","messages:write":"Create and manage messages","tasks:read":"View tasks","tasks:write":"Create, update, and delete tasks","notes:read":"View notes","notes:write":"Create, update, and delete notes","captures:read":"View captures","captures:write":"Create, update, and delete captures","entities:read":"View entities in your knowledge graph","entities:write":"Create and update entities","topics:read":"View topics","topics:write":"Create and manage topics","voice_notes:read":"View voice notes and transcripts","voice_notes:write":"Create and manage voice notes","collections:read":"View collections and items","collections:write":"Create and manage collections","research:read":"View research items","research:write":"Create and manage research items","meetings:read":"View meeting recordings and transcripts","meetings:write":"Create and manage meetings","webhooks:read":"View webhook endpoints and deliveries","webhooks:write":"Create and manage webhook endpoints","profile:read":"View your profile and account information"}}}}}},"paths":{"/api/v1/conversations":{"get":{"summary":"List conversations","description":"Returns a paginated list of the authenticated user's conversations.","tags":["Conversations"],"operationId":"listConversations","security":[{"BearerAuth":["conversations:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}},{"name":"is_archived","in":"query","description":"Filter by archive state","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Paginated list of conversations","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create conversation","description":"Creates a new conversation.","tags":["Conversations"],"operationId":"createConversation","security":[{"BearerAuth":["conversations:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCreate"}}}},"responses":{"201":{"description":"Conversation created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations/{id}":{"get":{"summary":"Get conversation","tags":["Conversations"],"operationId":"getConversation","security":[{"BearerAuth":["conversations:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Conversation ID"}],"responses":{"200":{"description":"Conversation details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update conversation","tags":["Conversations"],"operationId":"updateConversation","security":[{"BearerAuth":["conversations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationUpdate"}}}},"responses":{"200":{"description":"Conversation updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Move a conversation to Trash","description":"The conversation and its messages are hidden everywhere and deleted for good after 30 days. They can be restored from Trash in the app until then. The Main Thread can't be deleted.","tags":["Conversations"],"operationId":"deleteConversation","security":[{"BearerAuth":["conversations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Conversation ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks":{"get":{"summary":"List tasks","description":"Returns a paginated list of the authenticated user's tasks.","tags":["Tasks"],"operationId":"listTasks","security":[{"BearerAuth":["tasks:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"status","in":"query","description":"Filter by status","schema":{"type":"string","enum":["pending","completed","dismissed"]}},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"is_long_term","in":"query","description":"Filter long-term goals only","schema":{"type":"boolean"}},{"name":"due_before","in":"query","description":"Tasks due before this date","schema":{"type":"string","format":"date-time"}},{"name":"due_after","in":"query","description":"Tasks due after this date","schema":{"type":"string","format":"date-time"}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of tasks","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create task","description":"Creates a new task.","tags":["Tasks"],"operationId":"createTask","security":[{"BearerAuth":["tasks:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"201":{"description":"Task created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks/{id}":{"get":{"summary":"Get task","tags":["Tasks"],"operationId":"getTask","security":[{"BearerAuth":["tasks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Task ID"}],"responses":{"200":{"description":"Task details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update task","tags":["Tasks"],"operationId":"updateTask","security":[{"BearerAuth":["tasks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Task ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"}}}},"responses":{"200":{"description":"Task updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete task","tags":["Tasks"],"operationId":"deleteTask","security":[{"BearerAuth":["tasks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Task ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/notes":{"get":{"summary":"List notes","description":"Returns a paginated list of the authenticated user's notes.","tags":["Notes"],"operationId":"listNotes","security":[{"BearerAuth":["notes:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of notes","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create note","description":"Creates a new note.","tags":["Notes"],"operationId":"createNote","security":[{"BearerAuth":["notes:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteCreate"}}}},"responses":{"201":{"description":"Note created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/notes/{id}":{"get":{"summary":"Get note","tags":["Notes"],"operationId":"getNote","security":[{"BearerAuth":["notes:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Note ID"}],"responses":{"200":{"description":"Note details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Note"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update note","tags":["Notes"],"operationId":"updateNote","security":[{"BearerAuth":["notes:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Note ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteUpdate"}}}},"responses":{"200":{"description":"Note updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Note"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete note","tags":["Notes"],"operationId":"deleteNote","security":[{"BearerAuth":["notes:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Note ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/captures":{"get":{"summary":"List captures","description":"Returns a paginated list of the authenticated user's captures.","tags":["Captures"],"operationId":"listCaptures","security":[{"BearerAuth":["captures:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"source","in":"query","description":"Filter by source (api, web, email, etc.)","schema":{"type":"string"}},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"is_processed","in":"query","description":"Filter by processed status","schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of captures","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Capture"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create capture","description":"Creates a new capture.","tags":["Captures"],"operationId":"createCapture","security":[{"BearerAuth":["captures:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureCreate"}}}},"responses":{"201":{"description":"Capture created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Capture"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/captures/{id}":{"get":{"summary":"Get capture","tags":["Captures"],"operationId":"getCapture","security":[{"BearerAuth":["captures:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Capture ID"}],"responses":{"200":{"description":"Capture details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Capture"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update capture","tags":["Captures"],"operationId":"updateCapture","security":[{"BearerAuth":["captures:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Capture ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureUpdate"}}}},"responses":{"200":{"description":"Capture updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Capture"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete capture","tags":["Captures"],"operationId":"deleteCapture","security":[{"BearerAuth":["captures:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Capture ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/entities":{"get":{"summary":"List entities","description":"Returns a paginated list of the authenticated user's entities.","tags":["Entities"],"operationId":"listEntities","security":[{"BearerAuth":["entities:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"type","in":"query","description":"Filter by entity type","schema":{"type":"string","enum":["person","organization","project","decision","commitment","concept"]}},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of entities","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create entity","description":"Creates a new entity.","tags":["Entities"],"operationId":"createEntity","security":[{"BearerAuth":["entities:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityCreate"}}}},"responses":{"201":{"description":"Entity created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Entity"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/entities/{id}":{"get":{"summary":"Get entity","tags":["Entities"],"operationId":"getEntity","security":[{"BearerAuth":["entities:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Entity ID"}],"responses":{"200":{"description":"Entity details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Entity"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update entity","tags":["Entities"],"operationId":"updateEntity","security":[{"BearerAuth":["entities:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Entity ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUpdate"}}}},"responses":{"200":{"description":"Entity updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Entity"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete entity","tags":["Entities"],"operationId":"deleteEntity","security":[{"BearerAuth":["entities:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Entity ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/topics":{"get":{"summary":"List topics","description":"Returns a paginated list of the authenticated user's topics.","tags":["Topics"],"operationId":"listTopics","security":[{"BearerAuth":["topics:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"status","in":"query","description":"Filter by status","schema":{"type":"string","enum":["active","candidate","archived"]}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of topics","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Topic"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create topic","description":"Creates a new topic.","tags":["Topics"],"operationId":"createTopic","security":[{"BearerAuth":["topics:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicCreate"}}}},"responses":{"201":{"description":"Topic created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Topic"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/topics/{id}":{"get":{"summary":"Get topic","tags":["Topics"],"operationId":"getTopic","security":[{"BearerAuth":["topics:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Topic ID"}],"responses":{"200":{"description":"Topic details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Topic"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update topic","tags":["Topics"],"operationId":"updateTopic","security":[{"BearerAuth":["topics:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Topic ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicUpdate"}}}},"responses":{"200":{"description":"Topic updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Topic"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete topic","tags":["Topics"],"operationId":"deleteTopic","security":[{"BearerAuth":["topics:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Topic ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/meetings":{"get":{"summary":"List meetings","description":"Returns a paginated list of the authenticated user's meetings.","tags":["Meetings"],"operationId":"listMeetings","security":[{"BearerAuth":["meetings:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"status","in":"query","description":"Filter by status","schema":{"type":"string","enum":["recording","completed","failed"]}},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of meetings","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Meeting"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create meeting","description":"Creates a new meeting.","tags":["Meetings"],"operationId":"createMeeting","security":[{"BearerAuth":["meetings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingCreate"}}}},"responses":{"201":{"description":"Meeting created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Meeting"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/meetings/{id}":{"get":{"summary":"Get meeting","tags":["Meetings"],"operationId":"getMeeting","security":[{"BearerAuth":["meetings:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Meeting ID"}],"responses":{"200":{"description":"Meeting details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Meeting"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update meeting","tags":["Meetings"],"operationId":"updateMeeting","security":[{"BearerAuth":["meetings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Meeting ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingUpdate"}}}},"responses":{"200":{"description":"Meeting updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Meeting"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete meeting","tags":["Meetings"],"operationId":"deleteMeeting","security":[{"BearerAuth":["meetings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Meeting ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/voice-notes":{"get":{"summary":"List voicenotes","description":"Returns a paginated list of the authenticated user's voicenotes.","tags":["VoiceNotes"],"operationId":"listVoiceNotes","security":[{"BearerAuth":["voice_notes:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"analysis_status","in":"query","description":"Filter by analysis status","schema":{"type":"string","enum":["pending","analyzing","done","failed"]}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of voicenotes","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VoiceNote"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/voice-notes/{id}":{"get":{"summary":"Get voicenote","tags":["VoiceNotes"],"operationId":"getVoiceNote","security":[{"BearerAuth":["voice_notes:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"VoiceNote ID"}],"responses":{"200":{"description":"VoiceNote details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoiceNote"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update voicenote","tags":["VoiceNotes"],"operationId":"updateVoiceNote","security":[{"BearerAuth":["voice_notes:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"VoiceNote ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceNoteUpdate"}}}},"responses":{"200":{"description":"VoiceNote updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoiceNote"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete voicenote","tags":["VoiceNotes"],"operationId":"deleteVoiceNote","security":[{"BearerAuth":["voice_notes:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"VoiceNote ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/collections":{"get":{"summary":"List collections","description":"Returns a paginated list of the authenticated user's collections.","tags":["Collections"],"operationId":"listCollections","security":[{"BearerAuth":["collections:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"}],"responses":{"200":{"description":"Paginated list of collections","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create collection","description":"Creates a new collection.","tags":["Collections"],"operationId":"createCollection","security":[{"BearerAuth":["collections:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreate"}}}},"responses":{"201":{"description":"Collection created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Collection"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/collections/{id}":{"get":{"summary":"Get collection","tags":["Collections"],"operationId":"getCollection","security":[{"BearerAuth":["collections:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Collection ID"}],"responses":{"200":{"description":"Collection details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Collection"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update collection","tags":["Collections"],"operationId":"updateCollection","security":[{"BearerAuth":["collections:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Collection ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdate"}}}},"responses":{"200":{"description":"Collection updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Collection"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete collection","tags":["Collections"],"operationId":"deleteCollection","security":[{"BearerAuth":["collections:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Collection ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/research":{"get":{"summary":"List research","description":"Returns a paginated list of the authenticated user's research.","tags":["Research"],"operationId":"listResearch","security":[{"BearerAuth":["research:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"},{"name":"status","in":"query","description":"Filter by status","schema":{"type":"string","enum":["pending","extracting","analyzing","complete","failed"]}},{"name":"context","in":"query","description":"Filter by context","schema":{"type":"string","description":"A profile slug such as work or personal, or both"}},{"name":"search","in":"query","description":"Full-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of research","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResearchItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create researchitem","description":"Creates a new researchitem.","tags":["Research"],"operationId":"createResearchItem","security":[{"BearerAuth":["research:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchItemCreate"}}}},"responses":{"201":{"description":"ResearchItem created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ResearchItem"}}}}}},"400":{"description":"Invalid request — missing required fields or invalid values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/research/{id}":{"get":{"summary":"Get researchitem","tags":["Research"],"operationId":"getResearchItem","security":[{"BearerAuth":["research:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ResearchItem ID"}],"responses":{"200":{"description":"ResearchItem details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ResearchItem"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update researchitem","tags":["Research"],"operationId":"updateResearchItem","security":[{"BearerAuth":["research:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ResearchItem ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchItemUpdate"}}}},"responses":{"200":{"description":"ResearchItem updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ResearchItem"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete researchitem","tags":["Research"],"operationId":"deleteResearchItem","security":[{"BearerAuth":["research:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ResearchItem ID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","example":true}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations/{id}/messages":{"get":{"summary":"List messages in a conversation","tags":["Messages"],"operationId":"listMessages","security":[{"BearerAuth":["messages:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Conversation ID"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"}],"responses":{"200":{"description":"Paginated list of messages","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a message in a conversation","tags":["Messages"],"operationId":"createMessage","security":[{"BearerAuth":["messages:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Conversation ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageCreate"}}}},"responses":{"201":{"description":"Message created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Message"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/messages/{id}":{"get":{"summary":"Get a message","tags":["Messages"],"operationId":"getMessage","security":[{"BearerAuth":["messages:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Message details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Message"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a message","tags":["Messages"],"operationId":"updateMessage","security":[{"BearerAuth":["messages:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageUpdate"}}}},"responses":{"200":{"description":"Message updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Message"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Move a message to Trash","description":"The message is hidden everywhere and deleted for good after 30 days. It can be restored from Trash in the app until then.","tags":["Messages"],"operationId":"deleteMessage","security":[{"BearerAuth":["messages:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/collections/{id}/items":{"get":{"summary":"List collection items","tags":["Collections"],"operationId":"listCollectionItems","security":[{"BearerAuth":["collections:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Collection ID"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"}],"responses":{"200":{"description":"Paginated items","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CollectionItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create collection item","tags":["Collections"],"operationId":"createCollectionItem","security":[{"BearerAuth":["collections:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Collection ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionItemCreate"}}}},"responses":{"201":{"description":"Item created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CollectionItem"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/profile":{"get":{"summary":"Get current user profile","tags":["Profile"],"operationId":"getProfile","security":[{"BearerAuth":["profile:read"]}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Profile"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/bulk/import":{"post":{"summary":"Bulk import","description":"Import up to 500 items at once. user_id is automatically stamped — do not include it. Use for initial data migration.","tags":["Bulk"],"operationId":"bulkImport","security":[{"BearerAuth":["tasks:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkImportRequest"}}}},"responses":{"201":{"description":"Imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkImportResponse"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Import validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/bulk/export":{"post":{"summary":"Bulk export","description":"Export up to 10,000 records at once for migration or backup. Returns full entity objects.","tags":["Bulk"],"operationId":"bulkExport","security":[{"BearerAuth":["tasks:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkExportRequest"}}}},"responses":{"200":{"description":"Exported records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkExportResponse"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"operationId":"listWebhooks","security":[{"BearerAuth":["webhooks:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"}],"responses":{"200":{"description":"Paginated endpoints","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create webhook endpoint","description":"Creates a webhook endpoint. The signing secret is returned ONCE in the response — save it immediately.","tags":["Webhooks"],"operationId":"createWebhook","security":[{"BearerAuth":["webhooks:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Endpoint created (secret returned only here)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreateResponse"}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}":{"get":{"summary":"Get webhook endpoint","tags":["Webhooks"],"operationId":"getWebhook","security":[{"BearerAuth":["webhooks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update webhook endpoint","tags":["Webhooks"],"operationId":"updateWebhook","security":[{"BearerAuth":["webhooks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete webhook endpoint","tags":["Webhooks"],"operationId":"deleteWebhook","security":[{"BearerAuth":["webhooks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}/deliveries":{"get":{"summary":"List webhook deliveries","description":"Returns the delivery log for a specific webhook endpoint, most recent first.","tags":["Webhooks"],"operationId":"listWebhookDeliveries","security":[{"BearerAuth":["webhooks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Page offset"},{"name":"sort","in":"query","schema":{"type":"string","default":"created_at"},"description":"Field to sort by"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"}],"responses":{"200":{"description":"Paginated deliveries","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}/test":{"post":{"summary":"Send a test webhook","description":"Sends a test.ping payload to the endpoint to verify it's reachable and signature verification works.","tags":["Webhooks"],"operationId":"testWebhook","security":[{"BearerAuth":["webhooks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Test sent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sent":{"type":"boolean"},"event_id":{"type":"string"}}}}}}}},"401":{"description":"Authentication required — invalid or missing access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — missing required scope or feature not available on this plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 1,000 requests/minute per user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/oauth/token":{"post":{"summary":"Exchange authorization code or refresh token for an access token","description":"Standard OAuth 2.0 token endpoint (RFC 6749). Supports both authorization_code and refresh_token grants. PKCE (`code_verifier`, S256) is required for authorization_code. Client credentials (client_id, and client_secret for every app that has one) may be sent in the body OR via Basic Auth header (`Authorization: Basic base64(client_id:client_secret)`) and are required for both grants.","tags":["OAuth"],"operationId":"tokenExchange","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"],"example":"authorization_code"},"code":{"type":"string","description":"Authorization code (for authorization_code grant)"},"redirect_uri":{"type":"string","description":"Must exactly match the redirect_uri used in the authorization request"},"client_id":{"type":"string"},"client_secret":{"type":"string"},"code_verifier":{"type":"string","description":"PKCE code verifier (required for authorization_code)"},"refresh_token":{"type":"string","description":"Refresh token (for refresh_token grant)"}}}}}},"responses":{"200":{"description":"Tokens issued","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","example":"sylva_oauth_aabbccdd..."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","example":3600,"description":"Access token lifetime in seconds"},"refresh_token":{"type":"string","example":"sylva_refresh_eeffaabb..."},"scope":{"type":"string","example":"tasks:read tasks:write"}}}}}},"400":{"description":"Invalid request — missing or invalid parameters, or invalid grant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}