{"openapi":"3.1.0","info":{"title":"SuperWhisper API","version":"1.0.0","description":"Public API for accessing SuperWhisper organization data."},"servers":[{"url":"https://api.superwhisper.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API access token (starts with sk-sw-)"}}},"paths":{"/api/v1/stats/dimensions":{"get":{"tags":["Stats"],"summary":"Get stat dimensions","description":"Returns the distinct values available for filtering: voice models, language models, and app names.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Available filter dimensions","content":{"application/json":{"schema":{"type":"object","properties":{"voice_models":{"type":"array","items":{"type":"string"},"description":"Available voice model identifiers"},"language_models":{"type":"array","items":{"type":"string"},"description":"Available language model identifiers"},"app_names":{"type":"array","items":{"type":"string"},"description":"Application names seen in recordings"}},"required":["voice_models","language_models","app_names"],"$schema":"http://json-schema.org/draft-07/schema#"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token"}}}},"/api/v1/stats/summary":{"get":{"tags":["Stats"],"summary":"Get summary statistics","description":"Returns aggregated totals for recordings, duration, words, and processing times within a date range.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Summary statistics","content":{"application/json":{"schema":{"type":"object","properties":{"total_recordings":{"type":"number","description":"Total number of recordings"},"total_duration_minutes":{"type":"number","description":"Total recording duration in minutes"},"total_words":{"type":"number","description":"Total words transcribed"},"avg_llm_processing_seconds":{"type":"number","description":"Average LLM processing time in seconds"},"avg_voice_processing_seconds":{"type":"number","description":"Average voice processing time in seconds"}},"required":["total_recordings","total_duration_minutes","total_words","avg_llm_processing_seconds","avg_voice_processing_seconds"],"$schema":"http://json-schema.org/draft-07/schema#"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token"}},"parameters":[{"name":"start_date","in":"query","required":false,"description":"ISO 8601 start date (defaults to 7 days ago)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:?\\d{2})?)?$"}},{"name":"end_date","in":"query","required":false,"description":"ISO 8601 end date (defaults to now)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:?\\d{2})?)?$"}},{"name":"filter[member_email]","in":"query","required":false,"description":"Comma-separated member email addresses","schema":{"type":"string"}},{"name":"filter[voice_model]","in":"query","required":false,"description":"Comma-separated voice models","schema":{"type":"string"}},{"name":"filter[language_model]","in":"query","required":false,"description":"Comma-separated language models","schema":{"type":"string"}},{"name":"filter[app_name]","in":"query","required":false,"description":"Comma-separated app names","schema":{"type":"string"}}]}},"/api/v1/stats":{"get":{"tags":["Stats"],"summary":"Get paginated statistics","description":"Returns time-series usage statistics with optional grouping, filtering, and pagination. Supports JSON and CSV output formats.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Paginated statistics (or CSV file when format=csv)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"time_bucket":{"type":"string","description":"Start of the time period (ISO 8601)"},"recording_count":{"type":"number","description":"Number of recordings in this period"},"total_words":{"type":"number","description":"Total words transcribed"},"total_duration":{"type":"number","description":"Total duration in milliseconds"},"avg_llm_processing_time":{"type":"number","description":"Average LLM processing time in milliseconds"},"avg_voice_processing_time":{"type":"number","description":"Average voice processing time in milliseconds"},"avg_wpm":{"type":"number","description":"Average words per minute"}},"required":["time_bucket","recording_count","total_words","total_duration","avg_llm_processing_time","avg_voice_processing_time","avg_wpm"]}},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"page_size":{"type":"number","description":"Number of results per page"},"total_rows":{"type":"number","description":"Total number of results"},"total_pages":{"type":"number","description":"Total number of pages"},"count":{"type":"number","description":"Number of results returned in this page"}},"required":["page","page_size","total_rows","total_pages","count"]},"meta":{"type":"object","properties":{"start_date":{"type":"string","description":"Query start date"},"end_date":{"type":"string","description":"Query end date"},"granularity":{"type":"string","description":"Time bucket granularity used"},"group_by":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Grouping dimension used, if any"}},"required":["start_date","end_date","granularity","group_by"]}},"required":["data","pagination","meta"],"$schema":"http://json-schema.org/draft-07/schema#"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Unauthorized — missing or invalid bearer token"}},"parameters":[{"name":"start_date","in":"query","required":false,"description":"ISO 8601 start date (defaults to 7 days ago)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:?\\d{2})?)?$"}},{"name":"end_date","in":"query","required":false,"description":"ISO 8601 end date (defaults to now)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:?\\d{2})?)?$"}},{"name":"granularity","in":"query","required":false,"description":"Time bucket granularity (defaults to day)","schema":{"enum":["hour","day","week","month"]}},{"name":"group_by","in":"query","required":false,"description":"Dimension to group results by","schema":{"enum":["member_email","voice_model","language_model","app_name"]}},{"name":"page","in":"query","required":false,"description":"Page number (defaults to 1)","schema":{"type":"integer","minimum":1}},{"name":"page_size","in":"query","required":false,"description":"Results per page, max 1000 (defaults to 200)","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"format","in":"query","required":false,"description":"Response format (defaults to json)","schema":{"enum":["json","csv"]}},{"name":"filter[member_email]","in":"query","required":false,"description":"Comma-separated member email addresses","schema":{"type":"string"}},{"name":"filter[voice_model]","in":"query","required":false,"description":"Comma-separated voice models","schema":{"type":"string"}},{"name":"filter[language_model]","in":"query","required":false,"description":"Comma-separated language models","schema":{"type":"string"}},{"name":"filter[app_name]","in":"query","required":false,"description":"Comma-separated app names","schema":{"type":"string"}}]}}}}