Quick Start Guide

Get up and running with the VoiceStamp API in 5 minutes

What You'll Build

By the end of this guide, you'll have:

  • Authenticated with the VoiceStamp API
  • Created your first voice recording
  • Retrieved and managed voice files
  • Sent a voice recording via email

Prerequisites

  • A VoiceStamp account (sign up at voicestamp.vps.webdock.cloud)
  • Basic knowledge of HTTP APIs and JSON
  • Your preferred HTTP client (curl, Postman, or code)

Step 1: Get Your API Token

VoiceStamp uses Bearer token authentication. You can use either user session tokens or the static API token.

For this tutorial: Contact support to get a development API token, or follow theauthentication flow to generate a user session token.

Step 2: Make Your First API Call

Let's start by verifying your authentication works:

curl -X GET "https://voicestamp.vps.webdock.cloud/api/v1/auth/verify" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

You should receive a response like:

{
  "valid": true,
  "user": {
    "id": "user-uuid",
    "email": "you@example.com",
    "role": "user"
  },
  "expires_at": "2025-10-23T10:30:00Z"
}

Step 3: Create a Voice Recording

Now let's create your first voice recording (VoiceStamp):

curl -X POST "https://voicestamp.vps.webdock.cloud/api/v1/voicestamps" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First VoiceStamp",
    "description": "A test recording from the API",
    "audio_data": "base64_encoded_audio_file_here",
    "duration": 5.2
  }'

Response:

{
  "success": true,
  "data": {
    "id": "vst-uuid",
    "title": "My First VoiceStamp",
    "description": "A test recording from the API",
    "duration": 5.2,
    "file_url": "https://voicestamp.app/files/vst-uuid.wav",
    "created_at": "2025-01-14T10:30:00Z",
    "status": "completed"
  }
}

Step 4: Retrieve Your Voice Recordings

Get a list of all your voice recordings:

curl -X GET "https://voicestamp.vps.webdock.cloud/api/v1/voicestamps" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Step 5: Share a Voice Recording via Email

Use the Email API to share your voice recording:

curl -X POST "https://voicestamp.vps.webdock.cloud/api/v1/email/send" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "9",
    "recipient_email": "friend@example.com",
    "recipient_name": "Friend Name",
    "variables": {
      "sender_name": "Your Name",
      "voicestamp_url": "https://voicestamp.app/listen/vst-uuid",
      "message": "Check out my voice recording!"
    }
  }'

Step 6: JavaScript Example

Here's how to do the same thing in JavaScript:

// VoiceStamp API Client
const API_BASE = 'https://voicestamp.vps.webdock.cloud/api/v1';
const API_TOKEN = 'your_token_here';

const apiClient = {
  async request(endpoint, options = {}) {
    const response = await fetch(`${API_BASE}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
    
    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }
    
    return response.json();
  },

  // Create a voice recording
  async createVoiceStamp(data) {
    return this.request('/voicestamps', {
      method: 'POST',
      body: JSON.stringify(data)
    });
  },

  // Get all voice recordings
  async getVoiceStamps() {
    return this.request('/voicestamps');
  },

  // Send email
  async sendEmail(templateId, recipientEmail, variables) {
    return this.request('/email/send', {
      method: 'POST',
      body: JSON.stringify({
        template_id: templateId,
        recipient_email: recipientEmail,
        variables
      })
    });
  }
};

// Usage example
async function demo() {
  try {
    // Create a voice recording
    const newVST = await apiClient.createVoiceStamp({
      title: 'Demo Recording',
      description: 'Created via JavaScript',
      audio_data: 'base64_audio_here',
      duration: 3.5
    });
    
    console.log('Created VoiceStamp:', newVST);
    
    // Get all recordings
    const recordings = await apiClient.getVoiceStamps();
    console.log('All recordings:', recordings);
    
    // Send via email
    await apiClient.sendEmail('9', 'friend@example.com', {
      sender_name: 'Demo User',
      voicestamp_url: newVST.data.file_url,
      message: 'Check out this demo!'
    });
    
    console.log('Email sent successfully!');
    
  } catch (error) {
    console.error('Error:', error);
  }
}

// Run the demo
demo();

Next Steps

Congratulations! You've successfully integrated with the VoiceStamp API. Here's what you can explore next:

VoiceStamps API Reference

Explore all voice recording endpoints, advanced features, and file management

Email API Reference

Learn about email templates, variables, and advanced sending options

More Code Examples

Working examples in Python, PHP, and other languages

SDKs & Libraries

Official SDKs and community libraries for faster development

Quick Start Guide - VoiceStamp API Documentation