{"openapi":"3.0.3","info":{"title":"Superscribe API","description":"REST API for accessing your Superscribe voice transcription recordings. Authenticate with an `ss_` API key created at https://superscribe.io/dashboard/api.","version":"1.0.0","contact":{"name":"Superscribe","url":"https://superscribe.io"}},"servers":[{"url":"https://superscribe.io/api/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key starting with `ss_`. Create one at https://superscribe.io/dashboard/api"}},"schemas":{"Recording":{"type":"object","properties":{"id":{"type":"string","example":"507f1f77bcf86cd799439011"},"transcript":{"type":"string","description":"Transcript text. For recordings with speaker turns (phone calls) this is a speaker-labelled dialogue, one utterance per line (e.g. \"You: Hi\\n+15551234567: Hello\"); otherwise the processed or raw transcript text.","example":"Hello world, this is a test recording."},"duration_seconds":{"type":"integer","example":42},"source":{"type":"string","enum":["microphone","file","phone_call","system_audio"],"example":"microphone"},"language":{"type":"string","nullable":true,"example":"en"},"was_translated":{"type":"boolean","example":false},"mode_id":{"type":"string","nullable":true},"direction":{"type":"string","enum":["inbound","outbound"],"nullable":true},"caller_number":{"type":"string","nullable":true,"example":"+15551234567"},"callee_number":{"type":"string","nullable":true,"example":"+18335522205"},"turns":{"type":"array","nullable":true,"description":"Speaker-diarized transcript turns (phone calls only)","items":{"type":"object","properties":{"speaker":{"type":"string","example":"agent","description":"`agent` = the device owner (the Superscribe user), `caller` = the other party"},"speaker_label":{"type":"string","example":"Siim","description":"Human-readable speaker name (contact-resolved on single-recording fetches)"},"is_owner":{"type":"boolean","example":true,"description":"True when this turn was spoken by the device owner"},"text":{"type":"string","example":"Hello, how can I help you?"},"start_time":{"type":"number","example":0.5},"end_time":{"type":"number","example":3.2}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"reprocessed_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","transcript","duration_seconds","source","was_translated","created_at","updated_at"]},"PaginatedRecordings":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Recording"}},"total":{"type":"integer","example":142},"hasMore":{"type":"boolean","example":true},"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20}},"required":["items","total","hasMore","page","limit"]},"SearchResult":{"allOf":[{"$ref":"#/components/schemas/PaginatedRecordings"},{"type":"object","properties":{"query":{"type":"string","example":"project meeting"},"search_mode":{"type":"string","enum":["semantic","text"],"description":"`semantic` = vector embedding search, `text` = regex fallback"}},"required":["query","search_mode"]}]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Recording not found"}},"required":["error"]}}},"paths":{"/recordings":{"get":{"operationId":"listRecordings","summary":"List recordings","description":"Returns a paginated list of your transcription recordings, newest first.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number (1-indexed)"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Results per page"},{"name":"dateFrom","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter recordings from this date (ISO 8601)"},{"name":"dateTo","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter recordings until this date (ISO 8601)"},{"name":"source","in":"query","schema":{"type":"string"},"description":"Filter by recording source: microphone, file, phone_call, system_audio — one value or several separated by | (e.g. \"phone_call|microphone\")"},{"name":"callerNumber","in":"query","schema":{"type":"string"},"description":"Filter by caller or callee phone number (E.164 format, e.g. +15551234567)"},{"name":"includeEmpty","in":"query","schema":{"type":"boolean","default":false},"description":"Include recordings whose transcript is empty (e.g. still processing). Excluded by default."},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","audioDuration"],"default":"createdAt"},"description":"Field to sort by"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"}],"responses":{"200":{"description":"Paginated list of recordings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedRecordings"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recordings/search":{"get":{"operationId":"searchRecordings","summary":"Search recordings","description":"Search recording transcripts. Uses semantic (vector embedding) search first; falls back to full-text regex if no semantic matches are found. The `search_mode` field in the response indicates which was used.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}},{"name":"dateFrom","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter recordings from this date (ISO 8601)"},{"name":"dateTo","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter recordings until this date (ISO 8601)"},{"name":"source","in":"query","schema":{"type":"string"},"description":"Filter by recording source: microphone, file, phone_call, system_audio — one value or several separated by | (e.g. \"phone_call|microphone\")"},{"name":"callerNumber","in":"query","schema":{"type":"string"},"description":"Filter by caller or callee phone number (E.164 format, e.g. +15551234567)"},{"name":"includeEmpty","in":"query","schema":{"type":"boolean","default":false},"description":"Include recordings whose transcript is empty (e.g. still processing). Excluded by default."}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"description":"Missing q parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recordings/{id}":{"get":{"operationId":"getRecording","summary":"Get recording","description":"Fetch a single recording by ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Recording ID (MongoDB ObjectId)"}],"responses":{"200":{"description":"Recording","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recording"}}}},"400":{"description":"Invalid ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recording not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}