Skip to content

API.md

Latest commit

 

History

History
371 lines (272 loc) · 5.35 KB

API.md

File metadata and controls

371 lines (272 loc) · 5.35 KB
Raw

API Documentation

OpenPlaud API reference for all endpoints.

Base URL

http://localhost:3000/api

Authentication

All authenticated endpoints require a valid session cookie set by Better Auth.

Endpoints

Health

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "timestamp": "2025-01-22T12:00:00.000Z"
}

Authentication

POST /auth/sign-up

Create a new user account.

Body:

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "John Doe"
}

POST /auth/sign-in

Sign in to existing account.

Body:

{
  "email": "user@example.com",
  "password": "securepassword"
}

POST /auth/sign-out

Sign out current user.

Plaud Integration

POST /plaud/connect

Connect Plaud device using bearer token.

Body:

{
  "bearerToken": "Bearer eyJhbGc..."
}

Response:

{
  "success": true,
  "devices": [...]
}

GET /plaud/connection

Get current Plaud connection status.

Response:

{
  "connected": true,
  "lastSync": "2025-01-22T12:00:00.000Z",
  "devices": [...]
}

POST /plaud/sync

Manually trigger sync of recordings from Plaud device.

Response:

{
  "success": true,
  "newRecordings": 5,
  "updatedRecordings": 2,
  "errors": []
}

Recordings

GET /recordings

List all recordings for current user.

Query Parameters:

  • limit (optional): Number of results (default: 50)
  • offset (optional): Pagination offset (default: 0)

Response:

{
  "recordings": [
    {
      "id": "abc123",
      "filename": "Meeting Notes",
      "duration": 3600000,
      "startTime": "2025-01-22T10:00:00.000Z",
      "filesize": 15728640,
      "deviceSn": "888317426694681884"
    }
  ],
  "total": 100
}

GET /recordings/[id]

Get single recording by ID.

Response:

{
  "id": "abc123",
  "filename": "Meeting Notes",
  "duration": 3600000,
  "startTime": "2025-01-22T10:00:00.000Z",
  "transcription": {...},
  "aiEnhancements": {...}
}

GET /recordings/[id]/audio

Stream audio file.

Headers:

  • Range: Optional byte range (e.g., bytes=0-1023)

Response:

  • Content-Type: audio/mpeg, audio/opus, etc.
  • Supports HTTP range requests (206 Partial Content)

POST /recordings/[id]/transcribe

Transcribe a recording.

Body:

{
  "provider": "openai",
  "model": "whisper-1"
}

Response:

{
  "success": true,
  "transcriptionId": "xyz789",
  "text": "Transcribed text...",
  "detectedLanguage": "en"
}

Settings

GET /settings/user

Get user settings.

Response:

{
  "autoTranscribe": false,
  "emailNotifications": true,
  "notificationEmail": "user@example.com",
  "syncInterval": 300000,
  "defaultPlaybackSpeed": 1.0
}

PUT /settings/user

Update user settings.

Body:

{
  "autoTranscribe": true,
  "emailNotifications": true
}

PUT /settings/storage

Configure storage provider.

Body:

{
  "storageType": "s3",
  "s3Config": {
    "endpoint": "https://...",
    "bucket": "openplaud",
    "region": "us-east-1",
    "accessKeyId": "...",
    "secretAccessKey": "..."
  }
}

GET /settings/ai/providers

List AI providers.

Response:

{
  "providers": [
    {
      "id": "xyz",
      "provider": "openai",
      "baseUrl": null,
      "defaultModel": "whisper-1",
      "isDefaultTranscription": true
    }
  ]
}

POST /settings/ai/providers

Add new AI provider.

Body:

{
  "provider": "groq",
  "apiKey": "gsk_...",
  "baseUrl": "https://api.groq.com/openai/v1",
  "defaultModel": "whisper-large-v3",
  "isDefaultTranscription": true
}

PUT /settings/ai/providers/[id]

Update AI provider.

DELETE /settings/ai/providers/[id]

Delete AI provider.

POST /settings/test-email

Send test email to verify SMTP configuration.

Body:

{
  "email": "user@example.com"
}

Export & Backup

GET /export

Export recordings in various formats.

Query Parameters:

  • format: json | txt | srt | vtt

Response:

  • File download

POST /backup

Create backup of all user data.

Response:

{
  "success": true,
  "backupUrl": "/backups/user_20250122_120000.zip"
}

Error Responses

All errors follow this format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Error Codes

  • UNAUTHORIZED: Not authenticated
  • FORBIDDEN: Insufficient permissions
  • NOT_FOUND: Resource not found
  • INVALID_INPUT: Validation failed
  • PLAUD_API_ERROR: Plaud API failure
  • TRANSCRIPTION_FAILED: Transcription error
  • STORAGE_ERROR: Storage operation failed
  • EMAIL_SEND_FAILED: Email notification failed
  • INTERNAL_ERROR: Server error

Rate Limiting

Rate limiting is not currently enforced but may be added in future versions.

Webhooks

Webhooks are not currently supported but are planned for a future release.

SDK / Client Libraries

Currently, no official SDK is available. The API is RESTful and can be consumed by any HTTP client.

Example with JavaScript:

// Fetch recordings
const response = await fetch('/api/recordings', {
  credentials: 'include'  // Include session cookie
});
const data = await response.json();

For more details, see the source code in src/app/api/.