VoiceStamps API

Complete REST API for VoiceStamp creation, management, sharing, and conversion. Create voice-annotated content with audio, images, and interactive elements.

Quick Start

1. Create a draft: POST /api/v1/security/vst/draft

2. Upload files: POST /api/v1/security/vst/{vstId}/audio

3. Complete package: POST /api/v1/security/vst/{vstId}/complete-package

4. Share: POST /api/v1/voicestamps/{id}/share

Core CRUD Operations

5 endpoints

GET/api/v1/voicestamps

Auth Required

List VoiceStamps

Get all VoiceStamps for the authenticated user with pagination and filtering.

Query Parameters

pagelimitstatussearch

POST/api/v1/voicestamps

Auth Required

Create VoiceStamp

Create a new VoiceStamp with metadata.

Request Body

titledescriptionvoice_tagsmetadata

GET/api/v1/voicestamps/{id}

Auth Required

Get VoiceStamp

Retrieve detailed information about a specific VoiceStamp.

Query Parameters

include_manifestinclude_sharing

PUT/api/v1/voicestamps/{id}

Auth Required

Update VoiceStamp

Update VoiceStamp metadata, title, description, or voice tags.

Request Body

titledescriptionvoice_tagsmetadata

DELETE/api/v1/voicestamps/{id}

Auth RequiredDestructive

Delete VoiceStamp

Permanently delete a VoiceStamp and all associated files.

Sharing & Collaboration

6 endpoints

POST/api/v1/voicestamps/{id}/share

Auth Required

Create Share Link

Generate a shareable link for a VoiceStamp with privacy controls.

Request Body

privacyexpires_atpassword

POST/api/v1/voicestamps/{id}/share/email

Auth Required

Share via Email

Share a VoiceStamp directly via email using template ID 100.

Request Body

recipient_emailrecipient_namemessage

POST/api/v1/voicestamps/{id}/share/sms

Auth Required

Share via SMS

Share a VoiceStamp directly via SMS using template ID 100.

Request Body

recipient_phonemessage

GET/api/v1/voicestamp/public/{code}

Access Public Share

Access a publicly shared VoiceStamp using the share code.

Query Parameters

track_view

GET/api/v1/voicestamp/public/{code}/data

Get Public Share Data

Get metadata for a publicly shared VoiceStamp.

Returns

VoiceStamp metadata, sharing info, view counts

POST/api/v1/security/vst/reply/{token}

Submit Reply

Submit a reply to a shared VoiceStamp using reply token.

Request Body

messageaudio_file

File Management

6 endpoints

POST/api/v1/security/vst/draft

Auth Required

Create Draft

Create a new VoiceStamp draft for file uploads.

Returns

VST ID for subsequent file operations

POST/api/v1/security/vst/{vstId}/image

Auth Required

Upload Image

Upload an image file to associate with a VoiceStamp.

Request Body

image_fileposition

GET/api/v1/security/vst/{vstId}/image/{filename}

Auth Required

Get Image

Retrieve an uploaded image file.

Returns

Binary image data

POST/api/v1/security/vst/{vstId}/audio

Auth Required

Upload Audio

Upload an audio file for voice recording.

Request Body

audio_filedurationformat

GET/api/v1/security/vst/{vstId}/audio/{filename}

Auth Required

Get Audio

Retrieve an uploaded audio file.

Returns

Binary audio data

GET/api/v1/files/{filename}

Serve File

Serve any VoiceStamp file by filename.

Returns

Binary file data

Package & Conversion

7 endpoints

GET/api/v1/security/vst/{vstId}/manifest

Auth Required

Get Manifest

Retrieve the VoiceStamp package manifest with all metadata.

Returns

Complete manifest JSON with voice tags, timestamps, files

PUT/api/v1/security/vst/{vstId}/manifest

Auth Required

Update Manifest

Update the VoiceStamp manifest with new voice tags or metadata.

Request Body

voice_tagsmetadatatimestamps

POST/api/v1/security/vst/{vstId}/drawings

Auth Required

Save Drawings

Save drawing/annotation data to the VoiceStamp package.

Request Body

drawing_datacoordinates

POST/api/v1/security/vst/{vstId}/upload-txt

Auth Required

Upload Text

Upload text content or transcription to the package.

Request Body

text_contenttype

POST/api/v1/security/vst/{vstId}/complete-package

Auth Required

Complete Package

Finalize the VoiceStamp package and trigger conversion.

Returns

Package completion status and download info

GET/api/v1/security/vst/{vstId}/package

Auth Required

Get Package

Download the complete VoiceStamp package as ZIP.

Returns

ZIP file containing all VoiceStamp assets

POST/api/v1/security/vst/{vstId}/convert

Auth Required

Convert to VST

Convert uploaded assets to final VST format.

Returns

Conversion job status and progress

Advanced Features

6 endpoints

GET/api/v1/security/vst/{vstId}/thumbnail

Auth Required

Get Thumbnail

Get the auto-generated thumbnail for a VoiceStamp.

Returns

Binary thumbnail image

POST/api/v1/security/vst/{vstId}/thumbnail/generate

Auth Required

Generate Thumbnail

Generate a new thumbnail from the VoiceStamp content.

Request Body

timestampstyle

POST/api/v1/security/vst/{vstId}/thumbnail/regenerate

Auth Required

Regenerate Thumbnail

Regenerate the thumbnail with updated parameters.

Request Body

timestampstyleforce

POST/api/v1/voicestamps/{id}/transcribe

Auth Required

Transcribe Audio

Generate text transcription of the voice recording.

Returns

Transcription text and confidence scores

GET/api/v1/security/vst/{vstId}/download

Auth Required

Download Package

Download the complete VoiceStamp package.

Returns

Download URL or direct file stream

POST/api/v1/security/ai/translate

Auth Required

AI Translation

Translate VoiceStamp text content using AI.

Request Body

texttarget_languagesource_language

VSTFile Data Structure

Complete data model for VoiceStamp files returned by API endpoints.

{
  "id": integer,
  "user_id": string,
  "voice_note_id": string|null,
  "title": string,
  "description": string|null,
  "draft_image_path": string|null,
  "thumbnail_path": string|null,
  "draft_audio_path": string|null,
  "vst_file_path": string|null,
  "file_size_bytes": integer,
  "conversion_status": enum: draft|processing|completed|failed,
  "aws_s3_bucket": string|null,
  "aws_s3_key": string|null,
  "manifest_s3_key": string|null,
  "package_s3_key": string|null,
  "metadata": object,
  "voice_tags": array,
  "created_at": timestamp,
  "updated_at": timestamp
}

Complete Workflow Example

1. Create Draft VoiceStamp

POST /api/v1/security/vst/draft
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "title": "My First VoiceStamp",
  "description": "Testing the API workflow"
}

// Response
{
  "success": true,
  "vst_id": 12345,
  "status": "draft"
}

2. Upload Audio File

POST /api/v1/security/vst/12345/audio
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

{
  "audio_file": [binary audio data],
  "duration": 30.5,
  "format": "mp3"
}

// Response
{
  "success": true,
  "audio_url": "https://voicestamp.vps.webdock.cloud/api/v1/security/vst/12345/audio/recording.mp3"
}

3. Complete Package

POST /api/v1/security/vst/12345/complete-package
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "voice_tags": [
    {
      "timestamp": 5.2,
      "x": 120,
      "y": 80,
      "note": "Important point here"
    }
  ]
}

// Response
{
  "success": true,
  "status": "completed",
  "download_url": "https://voicestamp.vps.webdock.cloud/api/v1/security/vst/12345/download"
}

4. Share via Email

POST /api/v1/voicestamps/12345/share/email
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "recipient_email": "friend@example.com",
  "recipient_name": "Friend Name",
  "message": "Check out my first VoiceStamp!"
}

// Response
{
  "success": true,
  "share_code": "ABC123",
  "public_url": "https://voicestamp.app/share/ABC123",
  "email_sent": true
}

Error Handling

Authentication Errors

HTTP 401 Unauthorized
{
  "error": "invalid_token",
  "message": "The provided token is invalid or expired"
}

Validation Errors

HTTP 422 Unprocessable Entity
{
  "error": "validation_failed",
  "message": "The given data was invalid",
  "errors": {
    "title": ["The title field is required"]
  }
}

Resource Not Found

HTTP 404 Not Found
{
  "error": "resource_not_found",
  "message": "VoiceStamp not found"
}