Amptune

API Documentation

Programmatic access to your account and resources

Overview

The Amptune API provides programmatic access to your account and resources. All API requests use standard HTTP methods and return JSON-formatted responses.

  • Base URL: https://amptune.com/api/v1
  • Authentication: API Key via Bearer token
  • Response Format: JSON
  • Rate Limiting: 100 requests per minute per API key

Getting Started

1. Generate an API Key

  1. Log in to your account
  2. Navigate to Settings → API Keys
  3. Click "Generate New API Key"
  4. Give your key a descriptive name
  5. Copy the key immediately (it will only be shown once)

2. Make Your First Request

curl -H "Authorization: Bearer YOUR_API_KEY" \\
  https://amptune.com/api/v1/user

Authentication

All authenticated API endpoints require a valid API key passed via the Authorization header using the Bearer token scheme.

Header Format

Authorization: Bearer APIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authentication Example

# Valid request with API key
curl -H "Authorization: Bearer API1234..." \\
  https://amptune.com/api/v1/user

# Response
{
  "id": "user_123",
  "email": "[email protected]",
  "username": "johndoe"
}

Public Endpoints

Some endpoints do not require authentication and can be accessed without an API key:

  • GET /api/health - Service health check
  • GET /api/v1/public - Public data endpoint

Endpoints

GET /api/v1/user Auth Required

Get Current User

Returns information about the authenticated user.

Request
curl -H "Authorization: Bearer YOUR_API_KEY" \\
  https://amptune.com/api/v1/user
Response (200 OK)
{
  "id": "user_123",
  "email": "[email protected]",
  "username": "johndoe",
  "created_at": "2024-01-15T10:30:00Z"
}
Errors
  • 401 Unauthorized - Missing or invalid API key
  • 500 Internal Server Error - Server error
GET /api/v1/public Public

Get Public Information

Retrieve public data without authentication.

Request
curl https://amptune.com/api/v1/public
Response (200 OK)
{
  "message": "This is a public endpoint",
  "version": "1.0.0",
  "timestamp": 1705318200000
}
GET /api/health Public

Service Health

Check if the API service is operational.

Request
curl https://amptune.com/api/health
Response (200 OK)
{
  "status": "ok",
  "message": "Server is running",
  "timestamp": 1705318200000
}

Error Handling

Error Response Format

All errors follow a consistent JSON format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

Common HTTP Status Codes

  • 200 OK - Request successful
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Authenticated but insufficient permissions
  • 404 Not Found - Resource does not exist
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Authentication Errors

Missing API Key

{
  "error": {
    "code": "unauthorized",
    "message": "API key required..."
  }
}

Invalid API Key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Code Examples

JavaScript (Fetch API)

// Get current user
async function getCurrentUser(apiKey) {
  const response = await fetch('https://amptune.com/api/v1/user', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return await response.json();
}

// Usage
try {
  const user = await getCurrentUser('APIxxx...');
  console.log('User:', user);
} catch (error) {
  console.error('API Error:', error.message);
}

Python (Requests)

import requests

API_KEY = 'APIxxx...'
BASE_URL = 'https://amptune.com/api/v1'

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

# Get current user
def get_current_user():
    response = requests.get(f'https://amptune.com/user', headers=headers)
    response.raise_for_status()
    return response.json()

# Usage
try:
    user = get_current_user()
    print(f'User: {user}')
except requests.exceptions.HTTPError as e:
    print(f'API Error: {e.response.json()}')

cURL Examples

# Get current user
curl -H "Authorization: Bearer YOUR_API_KEY" \\
  https://amptune.com/api/v1/user

# Get public data (no auth)
curl https://amptune.com/api/v1/public

# Health check
curl https://amptune.com/api/health

Rate Limiting

Current Limits

  • 100 requests per minute per API key
  • 10,000 requests per day per API key

Rate Limit Headers

Each API response includes rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705318260

Handling Rate Limits

When you exceed the rate limit, you'll receive:

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again later.",
    "retry_after": 60
  }
}

Best Practices

Security

  • Keep API keys secret - never commit to version control
  • Use environment variables to store keys
  • Rotate keys regularly
  • Use HTTPS only
  • Revoke compromised keys immediately

Key Management

  • Name keys descriptively
  • One key per application
  • Monitor usage in settings
  • Delete unused keys
  • Maximum 100 active keys per user

Error Handling

  • Check HTTP status codes
  • Parse error responses from JSON
  • Implement retry logic with exponential backoff
  • Log errors properly
  • Handle rate limits gracefully

Performance

  • Cache responses when possible
  • Use pagination effectively
  • Compress requests (gzip)
  • Monitor latency
  • Optimize query parameters
Need help? Visit Settings → API Keys to manage your API keys, or check the complete documentation.