Step 1: Send the User to TONE3000

Build the authorization URL with prompt=select_tone. You can optionally restrict the catalog by gear type or format so users only see tones relevant to your product. See Authentication for PKCE generation details.

// PKCE generation: see Authentication section
const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://your-app.com/callback',
  response_type: 'code',
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
  state,
  prompt: 'select_tone',
  // gears: 'amp-cab',          // optional: amp-cab, amp, cab, pedal, outboard, space, experimental
  // gears: 'amp_amp-cab',      // optional: multiple values separated by _
  // format: 'nam',             // optional: nam, aida-x, aa-snapshot, proteus, ir
  // architecture: '2',         // optional: 1 | 2 | 'custom'. Omit for legacy A1 + Custom.
  // menubar: 'true',           // optional: show navigation bar with back/forward/refresh/close
  // preview: 'true',           // optional: audition players in the flow (demo-only playback)
  // login_hint: 'user@example.com', // optional: pre-fill sign-in email (see Authentication)
});

window.location.href = `https://www.tone3000.com/api/v1/oauth/authorize?${params}`;

Step 2: The User Browses and Selects

TONE3000 handles sign-in, browsing, and selection. The user sees the full public catalog and their own private tones, filtered by any gear or format constraints you specified. Once they tap a tone, TONE3000 redirects them back to your app.

Step 3: Handle the Callback

TONE3000 redirects to your redirect_uri with a code, state, and the tone_id the user selected. Verify state before proceeding.

If the menubar is enabled and the user clicks the close button, the redirect will include canceled=true instead of a tone_id. If the user had already signed in, a code is still included and can be exchanged for tokens. If the user closed before signing in, no code is present.

const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const state = params.get('state');
const toneId = params.get('tone_id');
const canceled = params.get('canceled') === 'true';

if (state !== sessionStorage.getItem('t3k_state')) {
  throw new Error('State mismatch. Possible CSRF attack.');
}

if (canceled) {
  // User exited without selecting a tone.
  // If code is present, you can still exchange it for tokens.
  // If code is absent, the user closed before signing in.
  return;
}

Step 4: Exchange the Code and Fetch the Tone

Exchange the authorization code for an access token (see Token Exchange), then use the tone_id from the callback to fetch tone metadata and model download URLs.

// Token exchange: see Authentication section
const { access_token } = await exchangeCode(code);

// Fetch tone metadata
const tone = await fetch(`https://www.tone3000.com/api/v1/tones/${toneId}`, {
  headers: { Authorization: `Bearer ${access_token}` },
}).then(r => r.json());

// Fetch models, each has a model_url for downloading
const { data: models } = await fetch(
  `https://www.tone3000.com/api/v1/models?tone_id=${toneId}`,
  { headers: { Authorization: `Bearer ${access_token}` } },
).then(r => r.json());

Step 1: Send the User to TONE3000

Build the authorization URL with prompt=load_tone and the tone_id you want to load. Optionally pass gears and format to filter the replacement browse view if the tone is inaccessible. See Authentication for PKCE generation details.

// PKCE generation: see Authentication section
const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://your-app.com/callback',
  response_type: 'code',
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
  state,
  prompt: 'load_tone',
  tone_id: '42',
  // gears: 'amp',       // optional: filter replacement browse by gear type
  // format: 'nam',     // optional: filter replacement browse by format
  // architecture: '2', // optional: 1 | 2 | 'custom' (replacement browse). Omit for legacy A1 + Custom.
  // menubar: 'true',   // optional: show navigation bar with back/forward/refresh/close
  // login_hint: 'user@example.com', // optional: pre-fill sign-in email (see Authentication)
});

window.location.href = `https://www.tone3000.com/api/v1/oauth/authorize?${params}`;

Step 2: TONE3000 Verifies Access

After sign-in, TONE3000 checks whether the user can access the requested tone: public tones, tones they own, and tones they've favorited all proceed immediately. If the tone is private or deleted, TONE3000 shows a friendly error page with the option to browse the catalog and pick a replacement. Any gears or format filters you passed are applied to that replacement browse view.

Step 3: Handle the Callback

TONE3000 redirects to your redirect_uri with a code, state, and the resolved tone_id. Always verify state before proceeding. Note that tone_id may differ from your original request if the user selected a replacement.

If the menubar is enabled and the user clicks the close button, the redirect will include canceled=true instead of a tone_id. If the user had already signed in, a code is still included and can be exchanged for tokens. If the user closed before signing in, no code is present.

const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const state = params.get('state');
const toneId = params.get('tone_id');  // may differ from your original request
const canceled = params.get('canceled') === 'true';

if (state !== sessionStorage.getItem('t3k_state')) {
  throw new Error('State mismatch. Possible CSRF attack.');
}

if (canceled) {
  // User exited without loading a tone.
  // If code is present, you can still exchange it for tokens.
  // If code is absent, the user closed before signing in.
  return;
}

Step 4: Exchange the Code and Fetch the Tone

Exchange the authorization code for an access token (see Token Exchange), then use the tone_id from the callback to fetch tone metadata and model download URLs.

// Token exchange: see Authentication section
const { access_token } = await exchangeCode(code);

// Fetch tone metadata
const tone = await fetch(`https://www.tone3000.com/api/v1/tones/${toneId}`, {
  headers: { Authorization: `Bearer ${access_token}` },
}).then(r => r.json());

// Fetch models, each has a model_url for downloading
const { data: models } = await fetch(
  `https://www.tone3000.com/api/v1/models?tone_id=${toneId}`,
  { headers: { Authorization: `Bearer ${access_token}` } },
).then(r => r.json());

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

const tones = await response.json();

• Response type: PaginatedResponse<Tones[]>
• Query parameters:

  Name	Type	Description
  page	number	Page number for pagination (default: 1, optional)
  page_size	number	Number of items per page (default: 10, max: 100, optional)
  gear	Gear	Optional. Gear type to filter by, e.g. amp-cab. When omitted, returns tones of all gear types. A single value

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

const tones = await response.json();

• Response type: PaginatedResponse<Tones[]>
• Query parameters:

  Name	Type	Description
  page	number	Page number for pagination (default: 1, optional)
  page_size	number	Number of items per page (default: 10, max: 100, optional)
  gear	Gear	Optional. Gear type to filter by, e.g. amp-cab. When omitted, returns tones of all gear types. A single value

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

const tones = await response.json();

• Response type: PaginatedResponse<Tones[]>
• Query parameters:

  Name	Type	Description
  page	number	Page number for pagination (default: 1, optional)
  page_size	number	Number of items per page (default: 10, max: 100, optional)
  gear	Gear	Optional. Gear type to filter by, e.g. amp-cab. When omitted, returns tones of all gear types. A single value

// architecture is optional: 1 | 2 | 'custom'. Omit for legacy A1 + Custom.
const response = await fetch(`https://www.tone3000.com/api/v1/tones/${toneId}?architecture=${architecture}`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const tone = await response.json();

• Response type: Tone
• To get download URLs for a tone's models, use the List Models endpoint.
• Path parameters:

  Name	Type	Description
  id	number	ID of the tone to retrieve

• Query parameters:

  Name	Type	Description
  architecture	Architecture	Filter the tone's models_count by architecture. Accepts 1 (A1), 2 (A2), or custom. Omitting returns A1 + Custom (legacy default; excludes A2). Per-architecture breakdown columns (a1_models_count, a2_models_count,custom_models_count) are always returned so you can compute your own visible count. Applies to NAM tones only; ignored for other formats. Use the List Models endpoint with the same parameter to fetch the matching model objects. (optional)

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

const favorite = await response.json();

• Response type: Favorite (status 200)
• Path parameters:

  Name	Type	Description
  id	number	ID of the tone to favorite

await fetch(`https://www.tone3000.com/api/v1/tones/${toneId}/favorite`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

• Returns 204 No Content with no response body.
• Path parameters:

  Name	Type	Description
  id	number	ID of the tone to unfavorite

const response = await fetch(`https://www.tone3000.com/api/v1/tones/search?query=${query}&page=${page}&page_size=${pageSize}&sort=${sort}&gears=${gears}&sizes=${sizes}&tags=${tags}&makes=${makes}&creators=${creators}&format=${format}&architecture=${architecture}`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const tones = await response.json();

• Response type: PaginatedResponse<Tones[]>
• Query parameters:

  Name	Type	Description
  query	string	Search query term (optional, default: empty string)
  page	number	Page number for pagination (default: 1, optional)
  page_size	number	Number of items per page (default: 10, max: 25, optional)
  sort	TonesSort	Sort order (default: 'best-match' if query provided, 'trending' otherwise)
  gears	Gear[]	Filter by gear type. Underscore-separated for multiple values (e.g. amp_amp-cab_pedal). full-rig and ir are deprecated alias values; see Deprecated Fields (optional)
  sizes	Size[]	Filter by model sizes. Underscore-separated for multiple values (e.g. standard_lite_feather) (optional)
  tags	string[]	Filter by tag name, matched exactly against the values in a tone's tags array. Underscore-separated for multiple values (e.g. clean_high-gain). Multiple values are OR'd: a tone matches if it carries any of them (optional)
  makes	string[]	Filter by make and model name, matched exactly against the values in a tone's makes array. Underscore-separated for multiple values (e.g. Fender Twin Reverb_1965 Vox AC30). Multiple values are OR'd (optional)
  creators	string[]	Filter by creator, matched exactly against a tone's user.username. Comma-separated for multiple values (e.g. tone3000,amalgamaudio), not underscore-separated, because usernames may themselves contain _ and -. Multiple values are OR'd (optional)
  format	Format	Restrict results to a single tone format (e.g. nam, ir). platform is a deprecated alias; see Deprecated Fields (optional; omit for all formats)
  architecture	Architecture	Filter results by model architecture. Accepts 1 (A1), 2 (A2), or custom. Omitting returns tones with A1 or Custom models (legacy default; excludes A2-only tones). (optional)
  calibrated	boolean	Restrict results to tones that have at least one calibrated model. Pass true to enable (optional; default returns all)

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

// Or filter by gear: /api/v1/tones/trending?gear=${gear}
const { data: tones } = await response.json();

• Response type: { data: Tones[] }
• Only public tones with at least one downloadable model, an image, and a description are included.
• Query parameters:

  Name	Type	Description
  gear	Gear	Optional. Gear type to filter the trending feed, e.g. amp-cab. When omitted, returns the top 10 trending tones across all gear types. A single value

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

const { data: tones } = await response.json();

• Response type: { data: Tones[] }
• Covers nam and ir tones. Only public tones with at least one downloadable model, an image, and a description are included.
• No query parameters.

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

const { url, expires_at, filename } = await response.json();

// url is a temporary link to the zip archive, no auth header needed
const zip = await fetch(url);

• Response fields:

  Name	Type	Description
  url	string	Temporary download URL for the zip archive. Requires no authentication and expires one hour after being issued. Request it when the user initiates a download rather than storing it.
  expires_at	string	ISO 8601 timestamp at which url stops working
  filename	string	Suggested filename for the archive, derived from the tone title (e.g. My Tone.zip)

• The archive contains every model in the tone, named after the model (deduplicated with a numeric suffix where needed). These are the same files and names as downloading the tone on tone3000.com.
• For tones with format nam, the archive contains A2 files only. Other formats include all of the tone's models.
• Archives are cached server-side and rebuilt automatically when the tone's models change, so the first request after a change may take a few seconds while subsequent requests are fast.
• Returns 400 if the tone has no downloadable models.
• Path parameters:

  Name	Type	Description
  id	number	ID of the tone to download

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

const model = await response.json();

• Response type: Model
• The model_url field is a pre-built download URL. Pass your access token as a Bearer token when fetching it.
• Path parameters:

  Name	Type	Description
  id	number	ID of the model to retrieve

// architecture is optional: 1 | 2 | 'custom'. Omit for legacy A1 + Custom.
const response = await fetch(`https://www.tone3000.com/api/v1/models?tone_id=${toneId}&page=${page}&page_size=${pageSize}&architecture=${architecture}`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const models = await response.json();

• Response type: PaginatedResponse<Model[]>
• Query parameters:

  Name	Type	Description
  tone_id	number	ID of the tone to get models for
  page	number	Page number for pagination (default: 1, optional)
  page_size	number	Number of items per page (default: 10, max: 300, optional)
  architecture	Architecture	Filter by model architecture. Accepts 1 (A1), 2 (A2), or custom. Omitting the parameter returns A1 + Custom (legacy default; excludes A2).

The model_url field can be used to download the model. It is only valid for tones that are accessible by the current authenticated user.

// Download model in browser
const downloadModel = async (modelUrl: string) => {
  const response = await fetch(modelUrl, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  if (!response.ok) {
    throw new Error('Failed to download model');
  }
  
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = modelUrl.split('/').pop() || 'model';
  document.body.appendChild(a);
  a.click();
  window.URL.revokeObjectURL(url);
  document.body.removeChild(a);
};

// Usage
await downloadModel(model.model_url);