Speech-to-Text Adapter - API Contract

GET /api/v1/speech/api/v1/speech

List speech recognition sessions (history)

Public

Response Example

{
  "data": [
    {
      "session_id": "stt_9c1d4e7f",
      "mentor_id": "usr_mentor_042",
      "field_id": "fld_mentor_notes",
      "locale": "no-NO",
      "status": "completed",
      "duration_seconds": 32,
      "transcript": "Two participants asked about rent support. I shared NAV guide links with the group.",
      "created_at": "2026-03-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

GET /api/v1/speech/api/v1/speech/:id

Get a speech recognition session by ID

Public

Response Example

{
  "session_id": "stt_9c1d4e7f",
  "mentor_id": "usr_mentor_042",
  "field_id": "fld_mentor_notes",
  "locale": "no-NO",
  "status": "completed",
  "transcript": "Two participants asked about rent support. I shared NAV guide links with the group.",
  "confidence": 0.94,
  "duration_seconds": 32,
  "created_at": "2026-03-20T14:22:00Z"
}

POST /api/v1/speech/api/v1/speech/start

Start a speech recognition session for a form field

Public

Request Example

{
  "field_id": "fld_mentor_notes",
  "report_session_id": "sess_4f2a1b9c",
  "locale": "no-NO",
  "mentor_id": "usr_mentor_042"
}

Response Example

{
  "session_id": "stt_9c1d4e7f",
  "field_id": "fld_mentor_notes",
  "status": "listening",
  "locale": "no-NO",
  "started_at": "2026-03-20T14:22:00Z",
  "stream_url": "/api/v1/speech/stt_9c1d4e7f/stream"
}

PUT /api/v1/speech/api/v1/speech/:id

Update or correct a speech transcript

Public

Request Example

{
  "transcript": "Two participants asked about rent support. I shared NAV guide links with the group and booked a follow-up.",
  "correction_reason": "mentor_edited"
}

Response Example

{
  "session_id": "stt_9c1d4e7f",
  "transcript": "Two participants asked about rent support. I shared NAV guide links with the group and booked a follow-up.",
  "status": "corrected",
  "updated_at": "2026-03-20T14:27:00Z"
}

DELETE /api/v1/speech/api/v1/speech/:id

Delete a speech recognition session

Public

Response Example

{
  "deleted": true,
  "session_id": "stt_9c1d4e7f"
}

POST /api/v1/speech/api/v1/speech/:id/stop

Stop an active speech recognition session and return transcript

Public

Response Example

{
  "session_id": "stt_9c1d4e7f",
  "status": "completed",
  "transcript": "Two participants asked about rent support. I shared NAV guide links with the group.",
  "confidence": 0.94,
  "duration_seconds": 32,
  "stopped_at": "2026-03-20T14:22:32Z"
}

POST /api/v1/speech/api/v1/speech/permission

Request microphone permission for the current device/session

Public

Request Example

{
  "mentor_id": "usr_mentor_042",
  "device_type": "mobile"
}

Response Example

{
  "permission_granted": true,
  "device_type": "mobile",
  "granted_at": "2026-03-20T14:05:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}