ActionVibe API Documentation

Complete REST API reference for programmatic access to ActionVibe transcription services.

Base URL

https://api.actionvibe.ai

All API endpoints are accessed via Supabase Edge Functions.

Authentication

ActionVibe API supports two authentication methods:

API Tokens (Recommended)

Generate workspace-scoped API tokens for programmatic access:

# Generate a token via the dashboard
# Settings → API Tokens → Generate New Token

Use the token in your requests:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.actionvibe.ai/api/transcriptions

JWT Tokens

You can also use Supabase JWT tokens from authenticated sessions:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.actionvibe.ai/api/transcriptions

Rate Limits

Endpoint Type	Limit
Upload endpoints	10 requests/minute
Read endpoints	100 requests/minute
Token management	20 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

API Endpoints

Transcriptions

Upload Transcription

Upload an audio or video file for transcription.

Endpoint: POST /api-transcriptions

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: multipart/form-data

Parameters:

Field	Type	Required	Description
file	File	Yes	Audio/video file (MP3, MP4, WAV, WebM, OGG)
title	String	No	Transcription title (default: "API Upload")
language	String	No	Language code (default: "en")

Request Example:

curl -X POST https://api.actionvibe.ai/api/transcriptions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@meeting.mp3" \
  -F "title=Team Standup" \
  -F "language=en"

Response (201 Created):

{
  "transcription_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "File uploaded successfully. Transcription is being processed.",
  "estimated_time": "2-5 minutes"
}

Error Responses:

{
  "error": "File too large. Maximum size is 100MB",
  "code": "FILE_TOO_LARGE"
}

Common error codes:

NO_FILE_PROVIDED (400)
UNSUPPORTED_FILE_TYPE (400)
FILE_TOO_LARGE (400)
MONTHLY_LIMIT_EXCEEDED (400)
UNAUTHORIZED (401)

Get Transcription

Retrieve a specific transcription by ID.

Endpoint: GET /api-transcription?id={transcription_id}

Headers:

Authorization: Bearer YOUR_API_TOKEN

Request Example:

curl https://api.actionvibe.ai/api/transcription/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Team Standup",
  "content": "Full transcription text...",
  "summary": "AI-generated summary of the meeting...",
  "status": "completed",
  "language": "en",
  "file_size": 5242880,
  "duration": 1800,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:05:00Z"
}

Status Values:

processing - Transcription in progress
completed - Transcription finished successfully
failed - Transcription failed (check error message)

List Transcriptions

Get a paginated list of transcriptions in your workspace.

Endpoint: GET /api-transcriptions-list

Query Parameters:

Parameter	Type	Default	Description
page	Integer	1	Page number
limit	Integer	20	Items per page (max 100)
status	String	all	Filter by status: `all`, `completed`, `processing`, `failed`

Request Example:

curl "https://api.actionvibe.ai/api/transcriptions-list?page=1&limit=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response (200 OK):

{
  "transcriptions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Team Standup",
      "status": "completed",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total_count": 100,
    "total_pages": 5
  }
}

API Tokens

Manage API tokens for your workspace.

Generate Token

Create a new API token for programmatic access.

Endpoint: POST /api-tokens

Request Body:

{
  "action": "generate",
  "name": "Production API",
  "workspaceId": "workspace-uuid",
  "permissions": {
    "read": true,
    "write": true,
    "admin": false
  },
  "expiresInDays": 365
}

Response (200 OK):

{
  "token": "sk_live_abc123...",
  "tokenId": "token-uuid",
  "name": "Production API",
  "workspace": {
    "id": "workspace-uuid",
    "name": "My Workspace",
    "type": "team"
  },
  "permissions": {
    "read": true,
    "write": true,
    "admin": false
  },
  "expiresAt": "2026-01-15T10:00:00Z",
  "createdAt": "2025-01-15T10:00:00Z"
}

Important: Save the token securely. It will only be shown once.

List Tokens

Get all API tokens for your account.

Endpoint: POST /api-tokens

Request Body:

{
  "action": "list"
}

Response (200 OK):

{
  "tokens": [
    {
      "id": "token-uuid",
      "name": "Production API",
      "permissions": {
        "read": true,
        "write": true
      },
      "workspace": {
        "id": "workspace-uuid",
        "name": "My Workspace"
      },
      "is_active": true,
      "created_at": "2025-01-15T10:00:00Z",
      "last_used_at": "2025-01-18T14:30:00Z",
      "expires_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Revoke Token

Deactivate an API token.

Endpoint: POST /api-tokens

Request Body:

{
  "action": "revoke",
  "tokenId": "token-uuid"
}

Response (200 OK):

{
  "message": "API token revoked successfully"
}

Usage Analytics

Get usage statistics for your workspace.

Endpoint: GET /api-usage

Query Parameters:

Parameter	Type	Default	Description
period	String	month	`day`, `week`, `month`
start_date	String	(current period)	ISO 8601 date
end_date	String	(current period)	ISO 8601 date

Request Example:

curl "https://api.actionvibe.ai/api/usage?period=month&start_date=2025-01-01" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response (200 OK):

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "summary": {
    "total_transcriptions": 150,
    "total_hours": 225.5,
    "total_uploads": 150,
    "success_rate": 98.7
  },
  "limits": {
    "monthly_upload_limit": 1200,
    "remaining_uploads": 800
  }
}

Error Handling

All API errors return a consistent JSON structure:

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

HTTP Status Codes

Status	Description
200	Success
201	Resource created
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
429	Rate limit exceeded
500	Server error

Common Error Codes

Code	Description
`INVALID_REQUEST`	Malformed request data
`UNAUTHORIZED`	Invalid or missing authentication
`FORBIDDEN`	Insufficient permissions
`NOT_FOUND`	Resource not found
`FILE_TOO_LARGE`	File exceeds size limit
`UNSUPPORTED_FILE_TYPE`	Invalid file format
`RATE_LIMITED`	Too many requests
`MONTHLY_LIMIT_EXCEEDED`	Usage limit reached

Code Examples

cURL

Upload a file:

curl -X POST https://api.actionvibe.ai/api/transcriptions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@recording.mp3" \
  -F "title=Important Meeting"

Get transcription:

curl https://api.actionvibe.ai/api/transcription/TRANSCRIPTION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

JavaScript/Node.js

// Upload a file
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('title', 'Team Meeting');

const response = await fetch('https://api.actionvibe.ai/api/transcriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiToken}`
  },
  body: formData
});

const result = await response.json();
console.log('Transcription ID:', result.transcription_id);

// Get transcription
const transcription = await fetch(
  `https://api.actionvibe.ai/api/transcription/${result.transcription_id}`,
  {
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  }
).then(res => res.json());

console.log('Transcript:', transcription.content);

Python

import requests

api_token = "YOUR_API_TOKEN"
base_url = "https://api.actionvibe.ai"

# Upload file
with open('meeting.mp3', 'rb') as f:
    files = {'file': f}
    data = {'title': 'Team Meeting'}
    headers = {'Authorization': f'Bearer {api_token}'}

    response = requests.post(
        f'{base_url}/api/transcriptions',
        files=files,
        data=data,
        headers=headers
    )

    result = response.json()
    transcription_id = result['transcription_id']
    print(f'Transcription ID: {transcription_id}')

# Get transcription
response = requests.get(
    f'{base_url}/api/transcription/{transcription_id}',
    headers=headers
)

transcription = response.json()
print(f'Content: {transcription["content"]}')

Best Practices

Security

Store tokens securely: Never commit API tokens to version control
Use environment variables: Keep tokens in environment variables or secure vaults
Rotate tokens regularly: Generate new tokens and revoke old ones periodically
Use workspace-specific tokens: Create separate tokens for different environments
Monitor token usage: Check last_used_at to identify unused tokens

Performance

Implement retry logic: Handle transient errors with exponential backoff
Respect rate limits: Implement client-side rate limiting
Use appropriate timeouts: Set reasonable timeout values for uploads
Poll efficiently: When checking transcription status, use intervals (e.g., every 30 seconds)

Error Handling

async function uploadWithRetry(file, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await uploadFile(file);
      return response;
    } catch (error) {
      if (error.code === 'RATE_LIMITED') {
        // Wait before retrying
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error; // Don't retry other errors
    }
  }
  throw new Error('Max retries exceeded');
}

Support

API Status: Monitor uptime and incidents via your dashboard
Email Support: support@actionvibe.ai
Documentation: docs.actionvibe.ai

Changelog

2025-01-15

Initial API release
Added transcription upload endpoint
Added transcription retrieval endpoints
Added API token management
Added usage analytics endpoint