Introduction

Welcome to the TONE3000 API. This RESTful API provides programmatic access to TONE3000 accounts, tones and models. To use the API, you or your users will need to authenticate via their TONE3000 account.

Note: This is version 1 of our API. Endpoints and data structures may change as we improve the platform.

Quick Start

  1. Authenticate users through our OAuth-style flow
  2. Use access tokens to make requests to https://www.tone3000.com/api/v1/
  3. Query user profile, created tones, favorited tones, and model data

Rate Limit

100 requests per minute by default. For production applications please email support@tone3000.com.

Support & Feedback

Questions, issues, or feedback? Contact support@tone3000.com - we'd love to hear from you.

Authentication

Initial Setup

1. Redirect users to the TONE3000 authentication page

Start the authentication flow by redirecting users to the TONE3000 authentication page. Make sure to encode your application's URL as the redirect parameter.

import { APP_URL } from '@/config/constants';


const redirectUrl = encodeURIComponent(APP_URL);
window.location.href = `https://www.tone3000.com/api/v1/auth?redirectUrl=${redirectUrl}`;

2. Exchange API Key for Session Tokens

After successful authentication, TONE3000 will redirect back to your application's redirectUrl with an api_key parameter. You'll need to exchange this API key for session tokens. The response will include access and refresh tokens, along with expiration information.

// Get API key from URL search params
const urlParams = new URLSearchParams(window.location.search);
const apiKey = urlParams.get('api_key');


const response = await fetch('https://www.tone3000.com/api/v1/auth/session', {
  method: 'POST',
  body: JSON.stringify({ api_key: apiKey })
});


const data = await response.json();

Session Management

1. Store Session Tokens

After exchanging the API key, you'll receive an access token and refresh token. Store these tokens securely in your application (e.g., in localStorage for web apps). Also store the expiration time to enable proactive token refresh.

// Store tokens and expiration
localStorage.setItem('tone3000_access_token', data.access_token);
localStorage.setItem('tone3000_refresh_token', data.refresh_token);
localStorage.setItem('tone3000_expires_at', String(Date.now() + (data.expires_in * 1000)));

2. Making Authenticated Requests

Include the access token in the Authorization header for all API requests. The token should be prefixed with "Bearer ". Before making a request, check if the token is about to expire and refresh it if needed.

// Check if token needs refresh
const expiresAt = parseInt(localStorage.getItem('tone3000_expires_at') || '0');
if (Date.now() > expiresAt) {
  await refreshTokens();
}


const response = await fetch(url, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

3. Token Refresh Flow

When an API request returns 401 (Unauthorized) or when proactively refreshing, use the refresh token to get a new access token. The response will include new tokens and expiration information.

// Refresh the access token
const refreshResponse = await fetch('https://www.tone3000.com/api/v1/auth/session/refresh', {
  method: 'POST',
  body: JSON.stringify({
    refresh_token: refreshToken,
    access_token: accessToken
  })
});


const newTokens = await refreshResponse.json();


// Store the new tokens and expiration
localStorage.setItem('tone3000_access_token', newTokens.access_token);
localStorage.setItem('tone3000_refresh_token', newTokens.refresh_token);
localStorage.setItem('tone3000_expires_at', String(Date.now() + (newTokens.expires_in * 1000)));

4. Handling Refresh Failure

If token refresh fails (e.g., refresh token is expired), clear the stored tokens and redirect the user back to the authentication page to restart the authentication flow.

// Clear stored tokens
localStorage.removeItem('tone3000_access_token');
localStorage.removeItem('tone3000_refresh_token');
localStorage.removeItem('tone3000_expires_at');


// Redirect back to auth page to restart authentication
const redirectUrl = encodeURIComponent(window.location.href);
window.location.href = `https://www.tone3000.com/api/v1/auth?redirectUrl=${redirectUrl}`;

User

Get information about the currently authenticated user.

const response = await fetch('https://www.tone3000.com/api/v1/user', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});


const user = await response.json();

Tones

Created Tones

Get a list of tones created by the currently authenticated user.

const response = await fetch(`https://www.tone3000.com/api/v1/tones/created?page=${page}&pageSize=${pageSize}`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});


const tones = await response.json();
  • Response type: PaginatedResponse<Tones[]>
  • Query parameters:
    NameTypeDescription
    pagenumberPage number for pagination (default: 1, optional)
    pageSizenumberNumber of items per page (default: 10, max: 100, optional)

Favorited Tones

Get a list of tones favorited by the currently authenticated user.

const response = await fetch(`https://www.tone3000.com/api/v1/tones/favorited?page=${page}&pageSize=${pageSize}`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});


const tones = await response.json();
  • Response type: PaginatedResponse<Tones[]>
  • Query parameters:
    NameTypeDescription
    pagenumberPage number for pagination (default: 1, optional)
    pageSizenumberNumber of items per page (default: 10, max: 100, optional)

Models

Get a list of models for a specific tone accessible by the current authenticated user.

const response = await fetch(`https://www.tone3000.com/api/v1/models?toneId=${toneId}&page=${page}&pageSize=${pageSize}`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});


const models = await response.json();
  • Response type: PaginatedResponse<Model[]>
  • Query parameters:
    NameTypeDescription
    toneIdnumberID of the tone to get models for
    pagenumberPage number for pagination (default: 1, optional)
    pageSizenumberNumber of items per page (default: 10, max: 100, optional)

Enums

Gear

enum Gear {
  Amp = 'amp',
  FullRig = 'full-rig',
  Pedal = 'pedal',
  Outboard = 'outboard',
  Ir = 'ir'
}

Platforms

enum Platform {
  Nam = 'nam',
  Ir = 'ir',
  AidaX = 'aida-x',
  AaSnapshot = 'aa-snapshot',
  Proteus = 'proteus'
}

Licenses

enum License {
  T3k = 't3k',
  CcBy = 'cc-by',
  CcBySa = 'cc-by-sa',
  CcByNc = 'cc-by-nc',
  CcByNcSa = 'cc-by-nc-sa',
  CcByNd = 'cc-by-nd',
  CcByNcNd = 'cc-by-nc-nd',
  Cco = 'cco'
}

Sizes

enum Size {
  Standard = 'standard',
  Lite = 'lite',
  Feather = 'feather',
  Nano = 'nano',
  Custom = 'custom'
}

Types

Session

The response type for both session creation and refresh endpoints.

interface Session {
  access_token: string;
  refresh_token: string;
  expires_in: number;  // seconds until token expires
  token_type: 'bearer';
}

EmbeddedUser

interface EmbeddedUser {
  id: string;
  username: string;
  avatar_url: string | null;
  url: string;
}

User

interface User extends EmbeddedUser {
  bio: string | null;
  links: string[] | null;
  created_at: string;
  updated_at: string;
}

Make

interface Make {
  id: number;
  name: string;
}

Tag

interface Tag {
  id: number;
  name: string;
}

Paginated Response

interface PaginatedResponse<T> {
  data: T[];
  page: number;
  pageSize: number;
  total: number;
  totalPages: number;
}

Tone

interface Tone {
  id: number;
  user_id: string;
  user: EmbeddedUser;
  created_at: string;
  updated_at: string;
  title: string;
  description: string | null;
  gear: Gear;
  images: string[] | null;
  is_public: boolean | null;
  links: string[] | null;
  platform: Platform;
  license: License;
  sizes: Size[];
  makes: Make[];
  tags: Tag[];
  models_count: number;
  downloads_count: number;
  favorites_count: number;
  url: string;
}

Model

interface Model {
  id: number;
  created_at: string;
  updated_at: string;
  user_id: string;
  model_url: string;
  name: string;
  size: Size;
  tone_id: number;
}

Example

For a complete end-to-end example of how to use the TONE3000 API in a React application, check out our example repository. This repository demonstrates:

  • User authentication and session management
  • Fetching and displaying user data
  • Working with tones and models
  • Handling API responses and errors
  • Token refresh flow implementation

The example app uses the t3kFetch utility to handle authentication and token management automatically.

// Example: Fetching user data
const response = await t3kFetch('https://www.tone3000.com/api/v1/user');
const userData = await response.json();