{ "openapi": "3.1.0", "info": { "title": "Bota API", "description": "API for capturing, ingesting, and processing offline conversations via AI wearable devices", "version": "1.0.0", "contact": { "name": "Bota Support", "email": "support@bota.dev" } }, "servers": [ { "url": "https://api.bota.dev/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "End Users", "description": "Manage end users (wearable device users)" }, { "name": "Devices", "description": "Register, configure, and manage devices" }, { "name": "Recordings", "description": "Create and manage audio recordings" }, { "name": "Uploads", "description": "Upload and download recording audio files" }, { "name": "Transcriptions", "description": "Create and retrieve transcriptions" }, { "name": "Summaries", "description": "Create and retrieve AI-generated summaries" }, { "name": "Search", "description": "Semantic search over transcript chunks (RAG retrieval)" }, { "name": "AI Ask", "description": "Multi-turn Q&A over recordings (single- and cross-recording)" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key (sk_live_*, sk_test_*, rk_*), device token (dtok_*), or command-bound reset completion credential (rct_*; exact factory-reset ACK only)" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "EndUser": { "type": "object", "properties": { "id": { "type": "string", "example": "eu_abc123" }, "external_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "external_id", "name", "email", "metadata", "created_at", "updated_at" ] }, "DeviceSettings": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "enabled_connections": { "type": "object", "properties": { "wifi": { "type": "boolean" }, "cellular": { "type": "boolean" } }, "required": [ "wifi", "cellular" ] }, "heartbeat_enabled_connections": { "type": "object", "properties": { "wifi": { "type": "boolean" }, "cellular": { "type": "boolean" } }, "required": [ "wifi", "cellular" ] }, "upload_network_preference": { "type": "array", "items": { "type": "string", "enum": [ "wifi", "ble", "cellular" ] } }, "power_management": { "type": "object", "properties": { "wifi_idle_timeout_seconds": { "anyOf": [ { "type": "number", "enum": [ -1 ] }, { "type": "number", "enum": [ 0 ] }, { "type": "integer", "minimum": 10, "maximum": 2540 } ] }, "cellular_idle_timeout_seconds": { "anyOf": [ { "type": "number", "enum": [ -1 ] }, { "type": "number", "enum": [ 0 ] }, { "type": "integer", "minimum": 10, "maximum": 2540 } ] } }, "required": [ "wifi_idle_timeout_seconds", "cellular_idle_timeout_seconds" ] } }, "required": [ "enabled_connections", "heartbeat_enabled_connections", "upload_network_preference", "power_management" ] }, "upload": { "type": "object", "properties": { "streaming_enabled": { "type": "boolean" }, "streaming_chunk_kb": { "type": "integer" }, "daily_data_limit_mb": { "type": "integer" }, "allow_roaming": { "type": "boolean" }, "pause_on_low_battery": { "type": "boolean" }, "off_peak_hours": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "enabled", "start", "end", "timezone" ] } }, "required": [ "streaming_enabled", "streaming_chunk_kb", "daily_data_limit_mb", "allow_roaming", "pause_on_low_battery", "off_peak_hours" ] } }, "required": [ "connection", "upload" ] }, "Device": { "type": "object", "properties": { "id": { "type": "string", "example": "dev_abc123" }, "serial_number": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "model": { "type": "string", "enum": [ "bota_pin", "bota_note" ] }, "firmware_version": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "unbound", "bound" ] }, "end_user_id": { "type": [ "string", "null" ] }, "battery_percent": { "type": [ "integer", "null" ] }, "storage_used_mb": { "type": [ "integer", "null" ] }, "storage_total_mb": { "type": [ "integer", "null" ] }, "signal_strength_dbm": { "type": [ "integer", "null" ] }, "last_heartbeat_at": { "type": [ "string", "null" ], "format": "date-time" }, "recording_state": { "type": [ "object", "null" ], "additionalProperties": {} }, "metadata": { "type": "object", "additionalProperties": {} }, "settings": { "$ref": "#/components/schemas/DeviceSettings" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "serial_number", "name", "model", "firmware_version", "status", "end_user_id", "battery_percent", "storage_used_mb", "storage_total_mb", "signal_strength_dbm", "last_heartbeat_at", "recording_state", "metadata", "settings", "created_at", "updated_at" ] }, "Command": { "type": "object", "properties": { "id": { "type": "string" }, "device_id": { "type": "string" }, "type": { "type": "string", "enum": [ "start_recording", "stop_recording", "trigger_upload", "factory_reset" ] }, "status": { "type": "string", "enum": [ "pending", "delivered", "executed", "failed", "expired", "cancelled" ] }, "params": { "type": [ "object", "null" ], "additionalProperties": {} }, "grant_token": { "type": "string", "description": "Command authorization credential. Factory-reset completion credentials are omitted from read-only restricted-key responses." }, "result": { "type": [ "object", "null" ], "additionalProperties": {} }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "device_id", "type", "status", "params", "result", "error", "expires_at", "delivered_at", "executed_at", "created_at" ] }, "Recording": { "type": "object", "properties": { "id": { "type": "string", "example": "rec_abc123" }, "end_user_id": { "type": [ "string", "null" ] }, "device_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "streaming", "uploaded", "processing", "completed", "failed", "integrity_failure" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "file_size_bytes": { "type": [ "integer", "null" ] }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": {} }, "upload_method": { "type": [ "string", "null" ], "enum": [ "ble", "wifi_direct", "4g_direct", "unknown" ] }, "source": { "type": "string", "enum": [ "device", "app_import", "api_upload" ] }, "mime_type": { "type": [ "string", "null" ] }, "is_streaming": { "type": "boolean" }, "chunk_count": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "end_user_id", "device_id", "name", "status", "duration_seconds", "file_size_bytes", "recorded_at", "metadata", "upload_method", "source", "mime_type", "is_streaming", "chunk_count", "created_at", "updated_at" ] }, "TranscriptionSegment": { "type": "object", "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" }, "speaker": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "start", "end", "text" ] }, "Transcription": { "type": "object", "properties": { "id": { "type": "string", "example": "txn_abc123" }, "recording_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "provider": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "segments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/TranscriptionSegment" } }, "full_text": { "type": [ "string", "null" ] }, "word_count": { "type": [ "integer", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "recording_id", "status", "provider", "language", "segments", "full_text", "word_count", "confidence", "error_message", "started_at", "completed_at", "created_at", "updated_at" ] }, "Summary": { "type": "object", "properties": { "id": { "type": "string", "example": "sum_abc123" }, "transcription_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "provider": { "type": [ "string", "null" ] }, "template_id": { "type": [ "string", "null" ] }, "custom_prompt": { "type": [ "string", "null" ] }, "output": { "type": [ "object", "null" ], "additionalProperties": {} }, "error_message": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "transcription_id", "status", "provider", "template_id", "custom_prompt", "output", "error_message", "started_at", "completed_at", "created_at", "updated_at" ] }, "SearchResult": { "type": "object", "properties": { "chunk_id": { "type": "string", "example": "chk_abc123" }, "recording_id": { "type": "string", "example": "rec_abc123" }, "transcription_id": { "type": "string", "example": "txn_abc123" }, "chunk_text": { "type": "string" }, "speaker": { "type": [ "string", "null" ] }, "start_ms": { "type": "integer", "example": 754000 }, "end_ms": { "type": "integer", "example": 761200 }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time" }, "score": { "type": "number" } }, "required": [ "chunk_id", "recording_id", "transcription_id", "chunk_text", "speaker", "start_ms", "end_ms", "recorded_at", "score" ] }, "MessagePart": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "citation" ] }, "recording_id": { "type": "string" }, "start_ms": { "type": "integer" }, "quote": { "type": "string" } }, "required": [ "type", "recording_id", "start_ms" ] } ] }, "AskMessage": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_abc123" }, "role": { "type": "string", "enum": [ "user", "assistant", "system", "tool" ] }, "content": { "type": "string" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/MessagePart" } }, "tokens": { "type": "object", "properties": { "input": { "type": [ "integer", "null" ] }, "output": { "type": [ "integer", "null" ] }, "cached": { "type": [ "integer", "null" ] } }, "required": [ "input", "output", "cached" ] }, "model": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "finish_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "role", "content", "parts", "tokens", "model", "provider", "finish_reason", "created_at" ] }, "Session": { "type": "object", "properties": { "id": { "type": "string", "example": "as_abc123" }, "scope": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recording", "library", "selected", "folder" ] }, "recording_ids": { "type": "array", "items": { "type": "string" } }, "recording_title": { "type": [ "string", "null" ] } }, "required": [ "type", "recording_ids", "recording_title" ] }, "title": { "type": "string" }, "message_count": { "type": "integer" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_model": { "type": [ "string", "null" ] }, "last_provider": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "scope", "title", "message_count", "last_message_at", "last_model", "last_provider", "created_at", "updated_at" ] } }, "parameters": {} }, "paths": { "/end-users": { "post": { "tags": [ "End Users" ], "summary": "Create End User", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "maxLength": 255, "format": "email" }, "metadata": { "type": "object", "additionalProperties": {} } } } } } }, "responses": { "201": { "description": "End user created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUser" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "End Users" ], "summary": "List End Users", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "external_id", "in": "query" } ], "responses": { "200": { "description": "List of end users", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EndUser" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "data", "has_more" ] } } } } } } }, "/end-users/{id}": { "get": { "tags": [ "End Users" ], "summary": "Get End User", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "End user details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUser" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "End Users" ], "summary": "Update End User", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "maxLength": 255, "format": "email" }, "metadata": { "type": "object", "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "Updated end user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUser" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "End Users" ], "summary": "Delete End User", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices": { "post": { "tags": [ "Devices" ], "summary": "Register Device", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_number": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "maxLength": 128 }, "model": { "type": "string", "enum": [ "bota_pin", "bota_note", "bota_pin_pro" ] }, "firmware_version": { "type": "string", "maxLength": 32 }, "metadata": { "type": "object", "additionalProperties": {} }, "mac_address": { "type": "string", "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$" } }, "required": [ "serial_number", "model" ] } } } }, "responses": { "201": { "description": "Device registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Device already registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Devices" ], "summary": "List Devices", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "end_user_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "serial_number", "in": "query" } ], "responses": { "200": { "description": "List of devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "data", "has_more" ] } } } } } } }, "/devices/{id}": { "get": { "tags": [ "Devices" ], "summary": "Get Device", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Device details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Devices" ], "summary": "Update Device", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128 }, "firmware_version": { "type": "string", "maxLength": 32 }, "metadata": { "type": "object", "additionalProperties": {} }, "mac_address": { "type": "string", "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$" }, "settings": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "enabled_connections": { "type": "object", "properties": { "wifi": { "type": "boolean" }, "cellular": { "type": "boolean" } }, "required": [ "wifi", "cellular" ] }, "heartbeat_enabled_connections": { "type": "object", "properties": { "wifi": { "type": "boolean" }, "cellular": { "type": "boolean" } } }, "upload_network_preference": { "type": "array", "items": { "type": "string", "enum": [ "wifi", "ble", "cellular" ] }, "minItems": 1, "maxItems": 3 }, "power_management": { "type": "object", "properties": { "wifi_idle_timeout_seconds": { "anyOf": [ { "type": "number", "enum": [ -1 ] }, { "type": "number", "enum": [ 0 ] }, { "type": "integer", "minimum": 10, "maximum": 2540 }, { "type": "integer", "minimum": 1, "maximum": 9 } ] }, "cellular_idle_timeout_seconds": { "anyOf": [ { "type": "number", "enum": [ -1 ] }, { "type": "number", "enum": [ 0 ] }, { "type": "integer", "minimum": 10, "maximum": 2540 }, { "type": "integer", "minimum": 1, "maximum": 9 } ] } } } } }, "upload": { "type": "object", "properties": { "streaming_enabled": { "type": "boolean" }, "streaming_chunk_kb": { "type": "integer", "minimum": 64, "maximum": 1024 }, "daily_data_limit_mb": { "type": "integer", "minimum": 0, "maximum": 10000 }, "allow_roaming": { "type": "boolean" }, "pause_on_low_battery": { "type": "boolean" }, "off_peak_hours": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$" }, "end": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$" }, "timezone": { "type": "string", "minLength": 1 } }, "required": [ "enabled", "start", "end", "timezone" ] } } } } } } } } } }, "responses": { "200": { "description": "Updated device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/state": { "get": { "tags": [ "Devices" ], "summary": "Get Device State", "description": "Returns real-time device state (battery, storage, connectivity). This is a subset of the full device object.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Device state", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "battery_percent": { "type": [ "integer", "null" ] }, "storage_used_mb": { "type": [ "integer", "null" ] }, "storage_total_mb": { "type": [ "integer", "null" ] }, "signal_strength_dbm": { "type": [ "integer", "null" ] }, "last_heartbeat_at": { "type": [ "string", "null" ], "format": "date-time" }, "recording_state": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "id", "battery_percent", "storage_used_mb", "storage_total_mb", "signal_strength_dbm", "last_heartbeat_at", "recording_state" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/bind": { "post": { "tags": [ "Devices" ], "summary": "Bind Device", "description": "Bind a device to an end user. Returns a device token for device authentication.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "end_user_id": { "type": "string", "minLength": 1 }, "pk_d": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{128}$" } }, "required": [ "end_user_id" ] } } } }, "responses": { "200": { "description": "Device bound with token", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Device" }, { "type": "object", "properties": { "device_token": { "type": "string", "example": "dtok_..." } }, "required": [ "device_token" ] } ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Device already bound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/unbind": { "post": { "tags": [ "Devices" ], "summary": "Unbind Device", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Device unbound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/reset": { "post": { "tags": [ "Devices" ], "summary": "Reset Device", "description": "Creates a durable factory-reset command. The device remains bound until it wipes local recordings and acknowledges the exact command.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "Factory reset accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/heartbeat": { "post": { "tags": [ "Devices" ], "summary": "Device Heartbeat", "description": "Report device status (battery, storage, signal). Typically called by device firmware or mobile app.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "battery_percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "battery_mv": { "type": "integer", "minimum": 0 }, "is_charging": { "type": "boolean" }, "storage_used_mb": { "type": "integer", "minimum": 0 }, "storage_total_mb": { "type": "integer", "minimum": 0 }, "signal_strength_dbm": { "type": "integer", "maximum": 0 }, "firmware_version": { "type": "string", "maxLength": 32 }, "device_name": { "type": "string", "maxLength": 64 }, "device_state": { "type": "string", "maxLength": 32 }, "pending_recordings": { "type": "integer", "minimum": 0 }, "flags": { "type": "integer", "minimum": 0, "maximum": 255 }, "lte_status": { "type": "string", "enum": [ "off", "searching", "registered", "connected", "denied", "no_sim", "error", "low_voltage", "disabled" ] }, "wifi_status": { "type": "string", "enum": [ "off", "scanning", "connecting", "connected", "connect_failed", "no_credentials", "disabled", "error" ] }, "wifi_ssid": { "type": "string", "maxLength": 32 }, "lte_operator": { "type": "string", "maxLength": 64 }, "streaming_mode": { "type": "integer", "minimum": 0, "maximum": 1 }, "connection_type": { "type": "array", "items": { "type": "string", "enum": [ "wifi", "4g", "ble" ] } }, "upload_channel": { "type": [ "string", "null" ], "enum": [ "wifi", "4g", "ble" ] } } } } } }, "responses": { "200": { "description": "Heartbeat accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "pending_commands": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "start_recording", "stop_recording", "trigger_upload", "factory_reset" ] }, "params": { "type": "object", "additionalProperties": {} }, "grant_token": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "params", "grant_token", "expires_at" ] } } }, "required": [ "status" ] } } } } } } }, "/devices/{id}/wifi-config/grant": { "post": { "tags": [ "Devices" ], "summary": "Grant WiFi Config", "description": "Generate a time-limited grant for configuring device WiFi credentials.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_in_seconds": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 900 } } } } } }, "responses": { "201": { "description": "WiFi config grant created", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_blob": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "grant_blob", "expires_at" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/commands/{commandId}/ack": { "post": { "tags": [ "Devices" ], "summary": "Acknowledge Command", "description": "Acknowledges the exact device command. A successful factory-reset ACK atomically unbinds the device, revokes its device token, and clears device-level configuration. Restricted project keys require devices:write to acknowledge a factory reset.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "commandId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "executed", "failed" ] }, "result": { "type": "object", "properties": { "recording_id": { "type": "string" }, "started_at": { "type": "string" }, "stopped_at": { "type": "string" }, "duration_seconds": { "type": "number" }, "local_recordings_deleted": { "type": "integer", "minimum": 0 } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Command acknowledged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/commands": { "post": { "tags": [ "Devices" ], "summary": "Create Command", "description": "Send a remote command to a device (start/stop recording).", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start_recording", "stop_recording", "trigger_upload" ] }, "params": { "type": "object", "properties": { "max_duration_sec": { "type": "integer", "minimum": 1, "maximum": 86400 }, "upload_immediately": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": {} } } }, "idempotency_key": { "type": "string", "maxLength": 64 }, "ttl_seconds": { "type": "integer", "minimum": 10, "maximum": 3600, "default": 300 } }, "required": [ "type" ] } } } }, "responses": { "202": { "description": "Command queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Devices" ], "summary": "List Commands", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "pending", "delivered", "executed", "failed", "expired", "cancelled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "List of commands", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Command" } } }, "required": [ "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/commands/{commandId}": { "delete": { "tags": [ "Devices" ], "summary": "Cancel Command", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "commandId", "in": "path" } ], "responses": { "200": { "description": "Command cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recordings": { "post": { "tags": [ "Recordings" ], "summary": "Create Recording", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "end_user_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "maxLength": 255 }, "recorded_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": {} }, "streaming": { "type": "boolean" }, "upload_method": { "type": "string", "enum": [ "ble", "wifi_direct", "4g_direct", "import", "unknown" ] }, "source": { "type": "string", "enum": [ "device", "app_import", "api_upload" ] }, "encryption_version": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "201": { "description": "Recording created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Recordings" ], "summary": "List Recordings", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "end_user_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "streaming", "uploaded", "processing", "completed", "failed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "List of recordings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Recording" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "data", "has_more" ] } } } } } } }, "/recordings/{id}": { "get": { "tags": [ "Recordings" ], "summary": "Get Recording", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Recording details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Recordings" ], "summary": "Delete Recording", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recordings/{id}/finalize": { "post": { "tags": [ "Recordings" ], "summary": "Finalize Streaming Upload", "description": "Mark a streaming recording as complete after all chunks have been uploaded.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "total_chunks": { "type": "integer", "exclusiveMinimum": 0 }, "final_duration_ms": { "type": "integer", "exclusiveMinimum": 0 }, "final_file_size_bytes": { "type": "integer", "exclusiveMinimum": 0 }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "trailer_base64": { "type": "string", "maxLength": 16384 } }, "required": [ "total_chunks" ] } } } }, "responses": { "200": { "description": "Recording finalized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recordings/{id}/upload-url": { "post": { "tags": [ "Uploads" ], "summary": "Get Upload URL", "description": "Generate a pre-signed S3 URL for uploading a recording audio file.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content_type": { "type": "string", "enum": [ "audio/opus", "audio/ogg", "audio/wav", "audio/wave", "audio/x-wav", "audio/mpeg", "audio/mp3", "audio/mp4", "audio/x-m4a", "audio/aac", "audio/flac", "audio/webm" ] }, "file_size_bytes": { "type": "integer", "exclusiveMinimum": 0 } } } } } }, "responses": { "200": { "description": "Pre-signed upload URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_url": { "type": "string", "format": "uri" }, "upload_token": { "type": "string", "example": "up_..." }, "expires_in": { "type": "integer" }, "content_type": { "type": "string" } }, "required": [ "upload_url", "upload_token", "expires_in", "content_type" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recordings/{id}/download-url": { "get": { "tags": [ "Uploads" ], "summary": "Get Download URL", "description": "Generate a pre-signed S3 URL for downloading a recording audio file.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "wav", "mp3", "opus", "m4a", "flac" ] }, "required": false, "name": "format", "in": "query", "description": "Optional export format. When supplied, Bota may transcode the source audio before returning the URL." }, { "schema": { "type": "boolean" }, "required": false, "name": "use_enhanced", "in": "query", "description": "When true, return the enhanced audio version if available. Defaults to true when format is supplied, otherwise false." } ], "responses": { "200": { "description": "Pre-signed download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer" }, "content_type": { "type": [ "string", "null" ] }, "file_size_bytes": { "type": [ "integer", "null" ] } }, "required": [ "download_url", "expires_in", "content_type", "file_size_bytes" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recordings/{id}/upload-complete": { "post": { "tags": [ "Uploads" ], "summary": "Complete Upload", "description": "Mark a recording upload as complete. Triggers transcription if configured.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "duration_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "file_size_bytes": { "type": "integer", "exclusiveMinimum": 0 }, "content_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } }, "responses": { "200": { "description": "Upload completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transcriptions": { "post": { "tags": [ "Transcriptions" ], "summary": "Create Transcription", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "recording_id": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "provider": { "type": "string", "enum": [ "whisper", "deepgram", "assemblyai", "elevenlabs" ] } }, "required": [ "recording_id" ] } } } }, "responses": { "201": { "description": "Transcription job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcription" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Transcriptions" ], "summary": "List Transcriptions", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "recording_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "List of transcriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transcription" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "data", "has_more" ] } } } } } } }, "/transcriptions/{id}": { "get": { "tags": [ "Transcriptions" ], "summary": "Get Transcription", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Transcription details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcription" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/summaries": { "post": { "tags": [ "Summaries" ], "summary": "Create Summary", "description": "Create a summary from a transcription. Provide either template_id or prompt (not both).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "transcription_id": { "type": "string", "minLength": 1 }, "template_id": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 10, "maxLength": 10000 }, "provider": { "type": "string", "enum": [ "gemini", "openai", "claude" ] } }, "required": [ "transcription_id" ] } } } }, "responses": { "201": { "description": "Summary job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Summaries" ], "summary": "List Summaries", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "transcription_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "start_date", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "List of summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Summary" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "data", "has_more" ] } } } } } } }, "/summaries/{id}": { "get": { "tags": [ "Summaries" ], "summary": "Get Summary", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Summary details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recordings/search": { "post": { "tags": [ "Search" ], "summary": "Search Recordings", "description": "Semantic (hybrid dense + keyword) search over an end user's transcript chunks. Returns the top-K most relevant chunks with timestamps for citation deep-linking.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000 }, "recording_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 500 }, "recorded_after": { "type": "string", "format": "date-time" }, "recorded_before": { "type": "string", "format": "date-time" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "end_user_id": { "type": "string", "minLength": 1 } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "results" ] } } } }, "400": { "description": "Validation error or missing end_user_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask/sessions": { "post": { "tags": [ "AI Ask" ], "summary": "Create Session", "description": "Create a session for a scope (`recording`, `library`, or `selected`). With `initial_message` the session is created and the first message answered in one call (200, returns the ask result); without it, an empty session is returned (201).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recording" ] }, "recording_id": { "type": "string", "minLength": 1 } }, "required": [ "type", "recording_id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "library" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "selected" ] }, "recording_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 500 } }, "required": [ "type", "recording_ids" ] } ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "initial_message": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "provider": { "type": "string", "enum": [ "gemini", "openai", "claude" ] }, "context_refs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recording" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, "maxItems": 20 }, "stream": { "type": "boolean" } }, "required": [ "content" ] }, "end_user_id": { "type": "string", "minLength": 1 }, "stream": { "type": "boolean" } }, "required": [ "scope" ] } } } }, "responses": { "200": { "description": "Session created and first message answered", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "example": "as_abc123" }, "message": { "$ref": "#/components/schemas/AskMessage" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "session_id", "message", "sources" ] } } } }, "201": { "description": "Empty session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Validation error or missing end_user_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recording not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Recording transcription not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Prompt too long", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "LLM provider request failed (retryable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "AI Ask" ], "summary": "List Sessions", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "end_user_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "recording", "library", "selected", "folder" ] }, "required": false, "name": "scope_type", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "recording_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "List of sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "data", "has_more" ] } } } } } } }, "/ask/sessions/{id}": { "get": { "tags": [ "AI Ask" ], "summary": "Get Session", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "AI Ask" ], "summary": "Update Session", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "title" ] } } } }, "responses": { "200": { "description": "Updated session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "AI Ask" ], "summary": "Delete Session", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask/sessions/{id}/messages": { "get": { "tags": [ "AI Ask" ], "summary": "List Messages", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Messages, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AskMessage" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "required": [ "data", "has_more" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "AI Ask" ], "summary": "Send Message", "description": "Append a user message and get the assistant answer. This is the ask action for multi-turn conversations; scope is taken from the session.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "provider": { "type": "string", "enum": [ "gemini", "openai", "claude" ] }, "context_refs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recording" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, "maxItems": 20 }, "stream": { "type": "boolean" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Assistant answer", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "example": "as_abc123" }, "message": { "$ref": "#/components/schemas/AskMessage" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "session_id", "message", "sources" ] } } } }, "400": { "description": "Validation error or missing end_user_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recording or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Recording transcription not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Prompt too long", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "LLM provider request failed (retryable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": {} }