API Documentation

API v1 Documentation

Barevalue API v1 Documentation

Overview

The Barevalue API v1 allows you to integrate podcast editing services with AI assistants (Claude Code, ChatGPT) and automation tools. Submit AI audio editing orders programmatically using your credit balance.

Base URL: https://barevalue.com/api/v1

Rate Limit: 10 requests per minute per API key (conservative beta limit)

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer bv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Obtaining an API Key

Log in to your Barevalue account
Navigate to Settings → API Keys
Click Generate Key
Copy and securely store the key (it's only shown once)

Key Security

API keys are hashed on our servers; we cannot retrieve them
Revoke compromised keys immediately from Settings
Use different keys for different applications
Never commit API keys to version control

Endpoints

Get Account Information

GET /api/v1/account

Returns your account balance, AI subscription status, and pricing information.

Response:

{
  "id": 413,
  "email": "user@example.com",
  "name": "John Doe",
  "credit_balance": 150.00,
  "credit_balance_formatted": "$150.00",
  "ai_bonus_minutes": 60,
  "ai_bonus_expires_at": "2026-02-05T00:00:00Z",
  "ai_subscription": {
    "tier": "creator",
    "minutes_limit": 300,
    "minutes_used": 45,
    "minutes_remaining": 255,
    "period_end": "2026-02-01T00:00:00Z",
    "cancel_at_period_end": false,
    "pending_tier": null
  },
  "pricing": {
    "audio_per_minute": 1.29,
    "currency": "USD"
  },
  "is_verified": true,
  "locale": "en"
}

Estimate Order Minutes

POST /api/v1/orders/estimate

Check if you have enough subscription minutes for an order. AI editing uses subscription minutes, not per-minute billing.

Request Body:

Field	Type	Required	Description
`duration_minutes`	integer	Yes	Estimated audio duration in minutes (1-300)

Request Example:

{
  "duration_minutes": 45
}

Response (can afford):

{
  "duration_minutes": 45,
  "can_afford": true,
  "minutes_available": {
    "bonus": 30,
    "student": 0,
    "subscription": 60,
    "total": 90
  },
  "minutes_applied": {
    "bonus": 30,
    "student": 0,
    "subscription": 15,
    "total": 45
  },
  "minutes_remaining_after": 45,
  "subscription_tier": "free"
}

Response (cannot afford):

{
  "duration_minutes": 100,
  "can_afford": false,
  "minutes_available": {
    "bonus": 30,
    "student": 0,
    "subscription": 60,
    "total": 90
  },
  "minutes_applied": {
    "bonus": 30,
    "student": 0,
    "subscription": 60,
    "total": 90
  },
  "minutes_remaining_after": 0,
  "subscription_tier": "free",
  "minutes_short": 10,
  "upgrade_required": true,
  "message": "You need 10 more minutes. Upgrade your subscription for more minutes.",
  "available_upgrades": [
    { "name": "Starter", "minutes_limit": 120, "price_monthly": 12 },
    { "name": "Creator", "minutes_limit": 180, "price_monthly": 24 },
    { "name": "Pro", "minutes_limit": 360, "price_monthly": 49 }
  ]
}

Get Presigned Upload URL (Single File)

POST /api/v1/orders/upload-url

Generate a presigned S3 URL for direct file upload. Use this for single-track recordings.

Request Body:

Field	Type	Required	Description
`filename`	string	Yes	Original filename (e.g., "episode-42.mp3")
`content_type`	string	No	MIME type (default: audio/mpeg)

Request Example:

{
  "filename": "episode-42.mp3",
  "content_type": "audio/mpeg"
}

Response:

{
  "upload_url": "https://barevalue-files.s3.amazonaws.com/...",
  "upload_method": "PUT",
  "upload_headers": {
    "Content-Type": "audio/mpeg"
  },
  "s3_key": "413/16000/raw/episode-42.mp3",
  "expires_in": 3600
}

Usage:

curl -X PUT \
  -H "Content-Type: audio/mpeg" \
  --data-binary @episode-42.mp3 \
  "https://barevalue-files.s3.amazonaws.com/..."

Get Presigned Upload URLs (Multi-Track)

POST /api/v1/orders/upload-urls

Generate presigned S3 URLs for multi-track recordings (e.g., separate host and guest tracks). This creates a draft order and returns upload URLs for each file.

Request Body:

Field	Type	Required	Description
`files`	array	Yes	Array of file objects (1-10 files)
`files[].filename`	string	Yes	Original filename
`files[].content_type`	string	Yes	MIME type (audio/mpeg, audio/wav, etc.)
`files[].size_bytes`	integer	Yes	File size in bytes (max 750MB per file)
`files[].role`	string	No	Track role: host, guest, intro, outro, music, other

Request Example:

{
  "files": [
    {
      "filename": "host-track.mp3",
      "content_type": "audio/mpeg",
      "size_bytes": 45000000,
      "role": "host"
    },
    {
      "filename": "guest-track.mp3",
      "content_type": "audio/mpeg",
      "size_bytes": 43000000,
      "role": "guest"
    },
    {
      "filename": "intro.mp3",
      "content_type": "audio/mpeg",
      "size_bytes": 2000000,
      "role": "intro"
    }
  ]
}

Response:

{
  "order_id": 16005,
  "uploads": [
    {
      "filename": "host-track.mp3",
      "role": "host",
      "upload_url": "https://barevalue-files.s3.amazonaws.com/...",
      "upload_method": "PUT",
      "upload_headers": {
        "Content-Type": "audio/mpeg"
      },
      "s3_key": "413/16005/raw/track_0_host-track.mp3",
      "expires_in": 3600
    },
    {
      "filename": "guest-track.mp3",
      "role": "guest",
      "upload_url": "https://barevalue-files.s3.amazonaws.com/...",
      "upload_method": "PUT",
      "upload_headers": {
        "Content-Type": "audio/mpeg"
      },
      "s3_key": "413/16005/raw/track_1_guest-track.mp3",
      "expires_in": 3600
    },
    {
      "filename": "intro.mp3",
      "role": "intro",
      "upload_url": "https://barevalue-files.s3.amazonaws.com/...",
      "upload_method": "PUT",
      "upload_headers": {
        "Content-Type": "audio/mpeg"
      },
      "s3_key": "413/16005/raw/track_2_intro.mp3",
      "expires_in": 3600
    }
  ],
  "expires_in": 3600
}

Workflow:

Call /upload-urls with your file list
Upload each file to its corresponding upload_url using PUT
Call /submit with the order_id from this response

Pre-Flight Validation

POST /api/v1/orders/validate

Validate an audio file before submission. Runs the same pre-checks (speech detection, content classification) that would run during order processing, but without creating an order or charging credits.

Use this to verify files before uploading, especially for automated pipelines.

Request Body:

Field	Type	Required	Description
`file_url`	string	Yes	Public URL to the audio file

Request Example:

{
  "file_url": "https://example.com/podcast/episode-42.mp3"
}

Response (Valid):

{
  "valid": true,
  "duration_minutes": 45.5,
  "checks": {
    "speech_check": {
      "passed": true,
      "has_speech": true
    },
    "content_check": {
      "passed": true,
      "is_spoken_content": true
    }
  }
}

Response (Invalid):

{
  "valid": false,
  "duration_minutes": 45.5,
  "checks": {
    "speech_check": {
      "passed": false,
      "has_speech": false
    },
    "content_check": {
      "passed": false,
      "is_spoken_content": false
    }
  },
  "message": "This appears to be music rather than a podcast or interview."
}

Validation Checks:

Check	What it does	Failure reason
`speech_check`	Verifies audio contains spoken content	Not enough speech detected
`content_check`	Verifies content is podcast/interview format	Content appears to be music or non-speech

Submit Order

POST /api/v1/orders/submit

Submit an AI audio editing order. Charges credits immediately.

Request Body:

Field	Type	Required	Description
`s3_key`	string	Conditional	S3 key from upload-url response (single file)
`order_id`	integer	Conditional	Order ID from upload-urls response (multi-track)
`file_url`	string	Conditional	External URL to audio file
`duration_minutes`	integer	Required for file_url	Audio duration in minutes
`podcast_name`	string	No	Name of the podcast
`episode_name`	string	No	Episode title
`episode_number`	string	No	Episode number
`special_instructions`	string	No	Detailed editing instructions (max 2000 chars)
`comments`	string	No	Legacy alias for special_instructions
`processing_style`	string	No	Processing intensity: `standard`, `minimal`, `aggressive`
`host_names`	array	No	Array of host names (max 5)
`guest_names`	array	No	Array of guest names (max 10)
`is_multitrack`	boolean	No	Set to true for multi-track orders
`idempotency_key`	string	Yes	Unique UUID to prevent duplicate orders

Note: Provide ONE of: s3_key (uploaded single file), order_id (multi-track), or file_url (external URL).

Processing Styles:

Style	Description
`standard`	Balanced editing - removes filler words, long pauses, normalizes audio (default)
`minimal`	Light touch - preserves natural speech patterns, minimal cuts
`aggressive`	Heavy editing - removes all filler, tightens pacing significantly

Request Example (Single File with Full Options):

{
  "s3_key": "413/16000/raw/episode-42.mp3",
  "podcast_name": "Tech Talk",
  "episode_name": "AI in 2026",
  "episode_number": "42",
  "special_instructions": "Please remove the section at 15:30-16:45 where we discuss NDA topics. Also remove any mentions of 'Project Alpha'.",
  "processing_style": "standard",
  "host_names": ["Sarah Chen"],
  "guest_names": ["Dr. James Wilson", "Maria Garcia"],
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
}

Request Example (Multi-Track):

{
  "order_id": 16005,
  "is_multitrack": true,
  "podcast_name": "Tech Talk",
  "episode_name": "AI in 2026",
  "special_instructions": "Host is Sarah, guest is James. Please balance their audio levels.",
  "host_names": ["Sarah Chen"],
  "guest_names": ["Dr. James Wilson"],
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440002"
}

Request Example (External URL):

{
  "file_url": "https://example.com/podcast/episode-42.mp3",
  "duration_minutes": 45,
  "podcast_name": "Tech Talk",
  "episode_name": "AI in 2026",
  "special_instructions": "Remove the intro music, it's copyrighted.",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440001"
}

Response (Immediate):

{
  "order_id": 16001,
  "status": "submitted",
  "credits_used": 3.15,
  "ai_bonus_minutes_used": 0,
  "estimated_completion": "2026-01-05T18:00:00Z"
}

Response (External URL - Queued):

{
  "order_id": 16002,
  "status": "downloading",
  "message": "File download queued. Order will be submitted automatically."
}

File URL Guidelines

When using file_url:

Maximum file size: 750MB
Supported formats: MP3, WAV, M4A, FLAC, AAC
URL must be publicly accessible
HTTPS recommended
Download timeout: 10 minutes

Multi-Track Billing

For multi-track orders, billing is calculated as:

Parallel tracks (host, guest, other): Billed for the longest track only
Sequential tracks (intro, outro, music): Billed in full, added to total

Example: A 45-minute host track, 45-minute guest track, and 2-minute intro = 47 billable minutes.

List Orders

GET /api/v1/orders

List your orders with optional filtering and pagination.

Query Parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Results per page (default: 20, max: 100)
`status`	string	No	Filter by status: `pending`, `processing`, `completed`, `failed`

Response:

{
  "orders": [
    {
      "order_id": 16005,
      "status": "done",
      "podcast_name": "Tech Talk",
      "episode_name": "AI in 2026",
      "episode_number": "42",
      "duration_minutes": 45,
      "submitted_at": "2026-01-20T14:30:00Z",
      "completed_at": "2026-01-20T16:45:00Z"
    },
    {
      "order_id": 16004,
      "status": "submitted",
      "podcast_name": "Tech Talk",
      "episode_name": "Web3 Deep Dive",
      "episode_number": "41",
      "duration_minutes": 52,
      "submitted_at": "2026-01-20T12:00:00Z",
      "completed_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 47,
    "total_pages": 3
  }
}

Check Order Status

GET /api/v1/orders/{order_id}

Get the status and details of an order. For orders in progress, includes real-time progress tracking.

Response Headers (Processing Orders):

Header	Description
`Retry-After`	Recommended seconds until next poll (30)
`X-Barevalue-Progress`	Current progress percentage (0-100)

Response (Processing):

{
  "order_id": 16001,
  "status": "submitted",
  "type": "audio_editing_ai_only",
  "podcast_name": "Tech Talk",
  "episode_name": "AI in 2026",
  "duration_minutes": 45,
  "cost": 3.15,
  "submitted_at": "2026-01-05T14:30:00Z",
  "completed_at": null,
  "progress": {
    "current_step": "enhancing",
    "current_step_display": "Enhancing audio quality",
    "percentage": 45,
    "started_at": "2026-01-05T14:30:00Z"
  },
  "retry_after_seconds": 30
}

Progress Steps:

Step	Display	Description
`pending`	"Waiting to start"	Order queued
`checking`	"Checking your file"	Pre-processing validation
`transcribing`	"Transcribing audio"	Speech-to-text
`analyzing`	"Analyzing content"	Content analysis
`editing`	"Editing audio"	Making edits
`enhancing`	"Enhancing audio quality"	Audio enhancement
`finalizing`	"Finalizing edits"	Completing edits
`transcript`	"Creating transcript"	Final transcript
`quality_check`	"Quality check"	Verifying output
`show_notes`	"Writing show notes"	Generating summary
`clips`	"Extracting highlights"	Creating clips
`complete`	"Complete"	Done

Response (Complete):

{
  "order_id": 16001,
  "status": "done",
  "submitted_at": "2026-01-05T14:30:00Z",
  "completed_at": "2026-01-05T16:45:00Z",
  "podcast_name": "Tech Talk",
  "episode_name": "AI in 2026",
  "duration_minutes": 45,
  "cost": 3.15,
  "download_urls": {
    "audio": "https://barevalue.com/download/16001/audio",
    "transcript": "https://barevalue.com/download/16001/transcript",
    "show_notes": "https://barevalue.com/download/16001/show-notes"
  }
}

Response (Failed):

{
  "order_id": 16003,
  "status": "failed",
  "submitted_at": "2026-01-05T14:30:00Z",
  "completed_at": null,
  "failure": {
    "code": "content_not_recognized",
    "message": "This doesn't appear to be a podcast or interview. We need at least 1 minute of spoken content."
  }
}

Order Statuses:

Status	Description
`draft`	Order created but not submitted
`downloading`	External file being downloaded
`submitted`	Order submitted, in processing queue
`done`	Order complete, files ready for download
`failed`	Order failed (see failure_reason)

Webhooks

Receive real-time notifications when order events occur. Configure webhook endpoints to be notified when orders complete, fail, or are refunded.

Important: Webhooks fire for all your orders, not just orders placed via API. Orders placed through the web interface will also trigger your webhooks. This makes webhooks useful for integrating Barevalue with your own systems (Slack notifications, automation workflows, etc.) regardless of how you submit orders.

Webhook Endpoints

List Webhooks

GET /api/v1/webhooks

Response:

{
  "webhooks": [
    {
      "id": 1,
      "url": "https://your-server.com/webhook",
      "events": ["order.completed", "order.failed"],
      "is_active": true,
      "failure_count": 0,
      "last_triggered_at": "2026-01-05T16:45:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "limit": 5,
  "count": 1
}

Create Webhook

POST /api/v1/webhooks

Request Body:

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive webhook payloads
`events`	array	Yes	Events to subscribe to

Request Example:

{
  "url": "https://your-server.com/webhook",
  "events": ["order.completed", "order.failed"]
}

Response:

{
  "id": 1,
  "url": "https://your-server.com/webhook",
  "events": ["order.completed", "order.failed"],
  "secret": "a1b2c3d4e5f6...",
  "is_active": true,
  "created_at": "2026-01-01T00:00:00Z",
  "message": "Webhook created. Save the secret - it will not be shown again."
}

Important: The secret is only returned once during creation. Store it securely for signature verification.

Update Webhook

PATCH /api/v1/webhooks/{id}

Request Body:

Field	Type	Required	Description
`url`	string	No	New webhook URL
`events`	array	No	Updated event subscriptions
`is_active`	boolean	No	Enable/disable webhook

Delete Webhook

DELETE /api/v1/webhooks/{id}

Rotate Secret

POST /api/v1/webhooks/{id}/rotate-secret

Generates a new signing secret. Use this if your secret is compromised.

Response:

{
  "id": 1,
  "secret": "new_secret_here...",
  "message": "Secret rotated. Save the new secret - it will not be shown again."
}

Webhook Events

Event	Description
`order.completed`	Order finished processing, files ready for download
`order.failed`	Order failed pre-checks or processing (auto-refunded)
`order.refunded`	Order was manually refunded

Webhook Payload

All webhooks are sent as POST requests with JSON body:

{
  "event": "order.completed",
  "timestamp": "2026-01-05T16:45:00Z",
  "data": {
    "order_id": 16001,
    "status": "done",
    "podcast_name": "Tech Talk",
    "episode_name": "AI in 2026",
    "completed_at": "2026-01-05T16:45:00Z",
    "download_urls": {
      "audio": "https://barevalue.com/download/16001/audio",
      "transcript": "https://barevalue.com/download/16001/transcript",
      "show_notes": "https://barevalue.com/download/16001/show-notes"
    }
  }
}

Failure Event:

{
  "event": "order.failed",
  "timestamp": "2026-01-05T14:35:00Z",
  "data": {
    "order_id": 16003,
    "status": "failed",
    "podcast_name": "Tech Talk",
    "episode_name": "Episode 42",
    "failed_at": "2026-01-05T14:35:00Z",
    "failure": {
      "code": "content_not_recognized",
      "message": "This doesn't appear to be a podcast or interview. We need at least 1 minute of spoken content."
    }
  }
}

Webhook Signature Verification

All webhook requests include a signature header for verification:

X-Barevalue-Signature: sha256=abc123...
X-Barevalue-Event: order.completed
X-Barevalue-Webhook-Id: 1
X-Barevalue-Delivery-Attempt: 1

Verification Example (Python):

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler:
signature = request.headers.get('X-Barevalue-Signature')
if not verify_signature(request.data, signature, WEBHOOK_SECRET):
    return Response('Invalid signature', status=401)

Webhook Delivery

Retries: Failed deliveries are retried 3 times with exponential backoff (1 min, 5 min, 15 min)
Timeout: 30 seconds per delivery attempt
Auto-disable: Webhooks are automatically disabled after 10 consecutive failures
Re-enable: Update the webhook with is_active: true to re-enable (resets failure count)

Slack Integration Example

Get notified in Slack when your orders complete:

Create a Slack Incoming Webhook:
- Go to Slack Apps → Create New App → From scratch
- Enable "Incoming Webhooks" and add one to your channel
- Copy the webhook URL (starts with https://hooks.slack.com/services/...)

Register it with Barevalue:

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
    "events": ["order.completed", "order.failed"]
  }' \
  https://barevalue.com/api/v1/webhooks

Done! All your orders (API or web UI) will now post to Slack when they complete or fail.

Note: Slack expects a specific payload format. For custom formatting, use a middleware service like Zapier or a simple Lambda function to transform the webhook payload.

Error Responses

All errors follow this format:

{
  "error": "error_code",
  "message": "Human-readable description"
}

Common Error Codes

Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	API key revoked or insufficient permissions
`validation_error`	422	Request validation failed
`insufficient_credits`	422	Not enough credits for order
`file_too_large`	422	File exceeds 750MB limit
`not_found`	404	Order not found
`rate_limited`	429	Rate limit exceeded
`webhook_limit_exceeded`	422	Maximum webhooks per account reached
`internal_error`	500	Server error

Order Failure Codes

When an order fails, the failure object contains a code and human-readable message:

Code	Description
`content_not_recognized`	Audio doesn't appear to be a podcast (music, silence, insufficient speech)
`language_not_supported`	Content is in an unsupported language (currently: English, Spanish)
`file_too_long`	Audio exceeds maximum duration limit
`audio_quality`	Unable to process audio (unclear, corrupted, etc.)
`processing_failed`	Generic processing error (our team is notified)

Example failure response:

{
  "failure": {
    "code": "content_not_recognized",
    "message": "This doesn't appear to be a podcast or interview. We need at least 1 minute of spoken content."
  }
}

For language errors, an additional detected_language field may be included.

Usage Examples

Complete Workflow (Python)

import requests
import uuid
import time

API_KEY = "bv_sk_your_key_here"
BASE_URL = "https://barevalue.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. Check balance
account = requests.get(f"{BASE_URL}/account", headers=headers).json()
print(f"Available minutes: {account.get('ai_bonus_minutes', 0)}")

# 2. Validate file before submission (optional)
validation = requests.post(
    f"{BASE_URL}/orders/validate",
    headers=headers,
    json={"file_url": "https://example.com/podcast.mp3"}
).json()

if not validation.get('valid'):
    print(f"Validation failed: {validation.get('message')}")
    exit(1)

# 3. Submit order
order_data = {
    "file_url": "https://example.com/podcast.mp3",
    "duration_minutes": validation.get('duration_minutes', 30),
    "podcast_name": "My Podcast",
    "episode_name": "Episode 42",
    "special_instructions": "Remove any mentions of competitor names.",
    "processing_style": "standard",
    "host_names": ["Alex"],
    "guest_names": ["Jordan"],
    "idempotency_key": str(uuid.uuid4())
}

response = requests.post(
    f"{BASE_URL}/orders/submit",
    headers=headers,
    json=order_data
)

if response.status_code == 201:
    order = response.json()
    order_id = order['order_id']
    print(f"Order #{order_id} submitted!")

    # 4. Poll for completion
    while True:
        status = requests.get(
            f"{BASE_URL}/orders/{order_id}",
            headers=headers
        ).json()

        if status['status'] == 'done':
            print(f"Complete! Downloads: {status['download_urls']}")
            break
        elif status['status'] == 'failed':
            print(f"Failed: {status.get('failure_message')}")
            break

        time.sleep(60)  # Check every minute
else:
    print(f"Error: {response.json()['message']}")

Multi-Track Upload (curl)

# 1. Get upload URLs
RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"filename": "host.mp3", "content_type": "audio/mpeg", "size_bytes": 45000000, "role": "host"},
      {"filename": "guest.mp3", "content_type": "audio/mpeg", "size_bytes": 43000000, "role": "guest"}
    ]
  }' \
  https://barevalue.com/api/v1/orders/upload-urls)

ORDER_ID=$(echo $RESPONSE | jq -r '.order_id')

# 2. Upload files (using URLs from response)
HOST_URL=$(echo $RESPONSE | jq -r '.uploads[0].upload_url')
GUEST_URL=$(echo $RESPONSE | jq -r '.uploads[1].upload_url')

curl -X PUT -H "Content-Type: audio/mpeg" --data-binary @host.mp3 "$HOST_URL"
curl -X PUT -H "Content-Type: audio/mpeg" --data-binary @guest.mp3 "$GUEST_URL"

# 3. Submit order
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": '"$ORDER_ID"',
    "is_multitrack": true,
    "podcast_name": "My Podcast",
    "special_instructions": "Host is Alex, guest is Jordan.",
    "idempotency_key": "'$(uuidgen)'"
  }' \
  https://barevalue.com/api/v1/orders/submit

Idempotency

All order submissions require an idempotency_key (UUID format). This prevents duplicate orders if you need to retry a request.

Same idempotency key with same user returns the existing order
Keys are scoped to your user account
We recommend using UUIDs (v4)

Rate Limits

10 requests per minute per API key (conservative beta limit)
Rate limit headers included in responses:
- X-RateLimit-Limit: Maximum requests per window
- X-RateLimit-Remaining: Remaining requests
- Retry-After: Seconds until limit resets (when exceeded)

MCP Integration (Claude Code)

For Claude Code and other MCP-compatible tools, we provide an official MCP server that wraps this API.

Requirement: MCP submissions require a pre-funded account (AI bonus minutes, subscription, or credit balance). Real-time payment is not supported via MCP.

Installation

// Add to ~/.claude/settings.json
{
  "mcpServers": {
    "barevalue": {
      "command": "npx",
      "args": ["-y", "barevalue-mcp"],
      "env": {
        "BAREVALUE_API_KEY": "bv_sk_your_key_here"
      }
    }
  }
}

Available Tools

Tool	Description
`barevalue_account`	Get account balance and subscription status
`barevalue_estimate`	Calculate order cost before submission
`barevalue_upload`	Upload a local audio file
`barevalue_validate`	Pre-check external URL before submission (not needed for uploads)
`barevalue_submit`	Submit uploaded file for processing
`barevalue_submit_url`	Submit using a public URL
`barevalue_status`	Check order status and get downloads
`barevalue_list_orders`	List recent orders
`barevalue_webhooks_list`	List configured webhooks
`barevalue_webhook_create`	Create a new webhook
`barevalue_webhook_update`	Update webhook settings
`barevalue_webhook_delete`	Delete a webhook
`barevalue_webhook_rotate_secret`	Rotate webhook signing secret

Example Usage

In Claude Code, you can say:

"Upload my podcast episode at ~/recordings/ep42.mp3 and submit it to Barevalue for editing"

Claude will:

Check your account balance
Upload the file
Run pre-validation
Submit for AI editing
Return the order ID and estimated completion time

For more details, see the npm package documentation.

Support

For API issues, contact support@barevalue.com or visit the Barevalue Help Center.

Account Management

API v1 Documentation

Barevalue API v1 Documentation

Overview

Authentication

Obtaining an API Key

Key Security

Endpoints

Get Account Information

Estimate Order Minutes

Get Presigned Upload URL (Single File)

Get Presigned Upload URLs (Multi-Track)

Pre-Flight Validation

Submit Order

File URL Guidelines

Multi-Track Billing

List Orders

Check Order Status

Webhooks

Webhook Endpoints

List Webhooks

Create Webhook

Update Webhook

Delete Webhook

Rotate Secret

Webhook Events

Webhook Payload

Webhook Signature Verification

Webhook Delivery

Slack Integration Example

Error Responses

Common Error Codes

Order Failure Codes

Usage Examples

Complete Workflow (Python)

Multi-Track Upload (curl)

Idempotency

Rate Limits

MCP Integration (Claude Code)

Installation

Available Tools

Example Usage

Support