Voice Notes

Manage voice note recordings and transcriptions.

---

List Voice Notes

GET /v1/recordings

Retrieve a paginated list of voice notes.

Query Parameters

Parameter	Type	Required	Description	Default
page	integer	No	Page number (0-indexed). See Pagination	0
limit	integer	No	Results per page (max: 100). See Pagination	50
status	string	No	Filter by status: transcribed, processing, failed	-
date_from	string	No	Filter by start date (ISO 8601), e.g. 2025-10-01	-
date_to	string	No	Filter by end date (ISO 8601), e.g. 2025-10-31	-

See also: Filtering best practices

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

# List all recordings
recordings = client.recordings.list(limit=10)

for record in recordings:
    print(record.id)

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function listRecordings() {
  const recordings = await client.recordings.list({ limit: 10 });

  for (const record of recordings.data) {
    console.log(record.id);
  }
}

cURL

curl -X GET "https://api.vocafuse.com/v1/recordings?limit=10" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

{
  "recordings": [
    {
      "id": "3d219a45-af16-4e2f-b018-dd8e44b4cf12",
      "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
      "user_id": null,
      "original_filename": "recording-2025-10-06T17-33-30-532Z.webm",
      "s3_key": "63f8fa32-0740-4263-9bed-578156b3526b/3d219a45-af16-4e2f-b018-dd8e44b4cf12.webm",
      "s3_bucket": "async-api-audio-dev-227647310470",
      "duration_seconds": 16.45,
      "file_size_bytes": 252287,
      "audio_format": "webm",
      "sample_rate": null,
      "channels": 1,
      "bit_rate": null,
      "audio_codec": null,
      "status": "transcribed",
      "features": null,
      "client_ip": null,
      "user_agent": null,
      "upload_source": null,
      "custom_tags": null,
      "created_at": "2025-10-06T17:33:31",
      "updated_at": "2025-10-06T17:33:45",
      "processed_at": null,
      "uri": "/v1/recordings/3d219a45-af16-4e2f-b018-dd8e44b4cf12"
    }
  ],
  "uri": "/v1/recordings?page=0&limit=10",
  "first_page_uri": "/v1/recordings?page=0&limit=10",
  "next_page_uri": "/v1/recordings?page=1&limit=10",
  "previous_page_uri": null,
  "page": 0,
  "page_size": 10,
  "total": 10
}

The response includes pagination metadata for navigating through results.

Response Fields

Field	Type	Description
id	string	Unique voice note identifier
tenant_id	string	Your VocaFuse account identifier
user_id	string	End user identifier (from JWT token identity)
original_filename	string	Original file name from upload
duration_seconds	number	Recording duration in seconds
file_size_bytes	integer	File size in bytes
audio_format	string	Audio format (webm, mp3, ogg, wav)
status	string	Processing status (see below)
created_at	string	ISO 8601 timestamp when created
updated_at	string	ISO 8601 timestamp of last update
uri	string	API endpoint for this voice note

Status Values

Status	Description
processing	Voice note is being transcribed
transcribed	Transcription completed successfully
failed	Processing failed

---

Get Voice Note

GET /v1/recordings/{recording_id}

Retrieve details of a specific voice note.

Path Parameters

Parameter	Type	Description
recording_id	string	The recording ID (e.g., rec_abc123)

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

recording = client.recordings.get('rec_123')

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function getRecording() {
  const recording = await client.recordings('rec_123').get();
  console.log(recording.data);
}

cURL

curl -X GET "https://api.vocafuse.com/v1/recordings/{recording_id}" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

{
  "id": "606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "user_id": null,
  "original_filename": "recording.mp3",
  "s3_key": "63f8fa32-0740-4263-9bed-578156b3526b/606cf8f5-b294-4b9c-ad0e-3afeb99c6804.mp3",
  "s3_bucket": "async-api-audio-dev-227647310470",
  "duration_seconds": 5.0,
  "file_size_bytes": 235790,
  "audio_format": "mp3",
  "sample_rate": null,
  "channels": 1,
  "bit_rate": null,
  "audio_codec": null,
  "status": "transcribed",
  "features": null,
  "client_ip": null,
  "user_agent": null,
  "upload_source": null,
  "custom_tags": null,
  "created_at": "2025-08-28T15:54:31",
  "updated_at": "2025-08-28T15:54:34",
  "processed_at": null,
  "uri": "/v1/recordings/606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "subresource_uris": {
    "transcription": "/v1/recordings/606cf8f5-b294-4b9c-ad0e-3afeb99c6804/transcription"
  }
}

---

Get Transcription

GET /v1/recordings/{recording_id}/transcription

Retrieve the transcription for a completed voice note.

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

transcription = client.recordings(
  'rec_123'
).transcription.get()

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function getTranscription() {
  const transcription = await client.recordings('rec_123').transcription.get();
  console.log(transcription.data.text);
}

cURL

curl -X GET "https://api.vocafuse.com/v1/recordings/{recording_id}/transcription" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

{
  "id": "b585a2af-56b3-435d-a51c-024d4cccfe0f",
  "recording_id": "606cf8f5-b294-4b9c-ad0e-3afeb99c6804",
  "tenant_id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "text": "This is an audio recording test to be uploaded to my API. I'm playing some music in the background which might provide a more thorough test.",
  "confidence": 0.95,
  "language": "english",
  "provider": "openai",
  "model": "whisper-1",
  "processing_duration_ms": 1367,
  "words": "[]",
  "created_at": "2025-08-28T15:54:34",
  "updated_at": "2025-08-28T15:54:34",
  "uri": "/v1/recordings/606cf8f5-b294-4b9c-ad0e-3afeb99c6804/transcription"
}

warning

Not Ready Error: Returns 404 with error code TRANSCRIPTION_NOT_READY if transcription is still processing. Use webhooks instead of polling.

---

Delete Voice Note

DELETE /v1/recordings/{recording_id}

Delete a voice note and its transcription.

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

client.recordings('rec_123').delete()

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function deleteRecording() {
  await client.recordings('rec_123').delete();
}

cURL

curl -X DELETE "https://api.vocafuse.com/v1/recordings/{recording_id}" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response:

Status Code: 204 No Content

No response body is returned for successful deletions.