Documentation

Everything you need to integrate the Tone API into your app or workflow.

On this page

Quickstart

1. Create an account and purchase a credit pack from the dashboard.

2. Copy your API key from the dashboard. It starts with tone_.

3. Make your first request:

curl
curl -X POST https://toneapi.bracherai.com/analyze \
  -H "Authorization: Bearer tone_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "I need this done by tomorrow, no excuses."}'
python
import requests

response = requests.post(
    "https://toneapi.bracherai.com/analyze",
    headers={"Authorization": "Bearer tone_YOUR_KEY"},
    json={"text": "I need this done by tomorrow, no excuses."}
)

print(response.json())
# {
#   "rudeness": 0.6,
#   "assertiveness": 0.85,
#   "confidence": 0.8,
#   "urgency": 0.9,
#   "vagueness": 0.1,
#   "summary": "The text is highly urgent and assertive..."
# }
javascript
const response = await fetch("https://toneapi.bracherai.com/analyze", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tone_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "I need this done by tomorrow, no excuses." }),
});

const data = await response.json();
console.log(data);

Authentication

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

header
Authorization: Bearer tone_YOUR_KEY

You can get your API key by creating an account and purchasing a credit pack. API calls cost 1–3 credits depending on the endpoint.

Your key is shown once in the dashboard after purchase. You can reveal it again anytime from the dashboard.

API Endpoints

Base URL: https://toneapi.bracherai.com

POST/analyze

Analyze the tone characteristics of text. Returns scores for rudeness, assertiveness, confidence, urgency, and vagueness.

Request body

{
  "text": "Your text here (max 10,000 characters)"
}

Response

{
  "rudeness": 0.1,
  "assertiveness": 0.7,
  "confidence": 0.8,
  "urgency": 0.3,
  "vagueness": 0.2,
  "summary": "The text is confident and assertive with low rudeness..."
}

Scores range from 0.0 to 1.0. The summary explains scores >= 0.4.

POST/detect-emotion

Detect the primary emotion and individual emotion scores in text.

Request body

{
  "text": "Your text here (max 10,000 characters)"
}

Response

{
  "primary_emotion": "joy",
  "emotions": {
    "joy": 0.85,
    "anger": 0.02,
    "sadness": 0.01,
    "fear": 0.01,
    "surprise": 0.05,
    "disgust": 0.01,
    "neutral": 0.05
  },
  "summary": "The text expresses strong joy..."
}

Primary emotion is one of: joy, anger, sadness, fear, surprise, disgust, neutral.

POST/rewrite

Rewrite text in a professional tone, or specify a custom target tone. Costs 2 credits.

Request body

{
  "text": "Your text here (max 10,000 characters)",
  "target_tone": "empathetic"  // optional
}

Response

{
  "rewritten_text": "The professionally rewritten text..."
}

Costs 2 credits. Without target_tone, rewrites to be formal and professional. Examples: empathetic, casual, assertive, friendly.

POST/reply

Generate a contextual reply to a message using a specific role and tone. Perfect for customer support, sales, HR, and more. Costs 3 credits.

Request body

{
  "message": "Message to reply to (max 10,000 characters)",
  "role": "support",      // support, sales, hr, executive, community
  "tone": "empathetic",   // professional, empathetic, friendly, assertive, casual
  "context": "Order #12345, delayed 2 weeks"  // optional
}

Response

{
  "reply": "I completely understand your frustration, and I sincerely apologize for the delay with your order #12345...",
  "role": "support",
  "tone": "empathetic"
}

Costs 3 credits. Roles: support (helpful, solution-focused), sales (persuasive, value-focused), hr (formal, policy-aware), executive (concise, authoritative), community (casual, friendly).

POST/compare

Compare the tone of two texts side by side. Returns individual tone scores for each text plus the differences. Costs 3 credits.

Request body

{
  "text_a": "First text to compare (max 10,000 characters)",
  "text_b": "Second text to compare (max 10,000 characters)"
}

Response

{
  "text_a": {
    "rudeness": 0.1,
    "assertiveness": 0.7,
    "confidence": 0.8,
    "urgency": 0.3,
    "vagueness": 0.2
  },
  "text_b": {
    "rudeness": 0.6,
    "assertiveness": 0.4,
    "confidence": 0.5,
    "urgency": 0.8,
    "vagueness": 0.1
  },
  "differences": {
    "rudeness": -0.5,
    "assertiveness": 0.3,
    "confidence": 0.3,
    "urgency": -0.5,
    "vagueness": 0.1
  },
  "summary": "Text A is more confident and assertive while Text B is more urgent and rude..."
}

Costs 3 credits. Differences are calculated as (Text A - Text B). Positive = Text A scores higher.

POST/audience

Build an audience profile from text and a detected emotion. Returns structured guidance for adapting responses. Pairs with /detect-emotion and /adapt.

Request body

{
  "text": "Original message (max 10,000 characters)",
  "emotion": "frustrated"  // from /detect-emotion primary_emotion
}

Response

{
  "emotional_state": "frustrated and feeling ignored",
  "communication_needs": ["empathy", "validation", "clear next steps"],
  "tone_guidance": "warm but direct, acknowledge the problem before offering solutions",
  "avoid": ["dismissive language", "corporate jargon", "deflection"]
}

Costs 1 credit. Output can be passed directly as the audience field in /adapt.

POST/adapt

Adapt text for a specific audience. Accepts a simple string (e.g. "frustrated customer") or a structured audience profile from /audience. Costs 2 credits.

Request body

// Simple string audience:
{
  "text": "Your text to adapt (max 10,000 characters)",
  "audience": "frustrated customer"
}

// Structured audience (from /audience):
{
  "text": "Your text to adapt (max 10,000 characters)",
  "audience": {
    "emotional_state": "frustrated and feeling ignored",
    "communication_needs": ["empathy", "validation", "clear next steps"],
    "tone_guidance": "warm but direct, acknowledge the problem before offering solutions",
    "avoid": ["dismissive language", "corporate jargon"]
  }
}

Response

{
  "adapted_text": "The adapted text tailored for the audience...",
  "adjustments_made": [
    "Added empathy statement at the opening",
    "Replaced corporate jargon with plain language",
    "Added clear next steps at the end"
  ]
}

Costs 2 credits. Built-in presets: frustrated customer, angry customer, anxious customer, happy customer, c-suite executive, new hire.

GET/keys/me

Check your API key status, remaining credits, and recent usage. Free — does not cost a credit.

Response

{
  "prefix": "tone_abc123...",
  "status": "active",
  "credits": 450,
  "total_calls": 50,
  "created_at": "2025-01-15T12:00:00Z",
  "email": "[email protected]",
  "usage_logs": [
    {
      "id": 1,
      "endpoint": "/analyze",
      "timestamp": "2025-01-15T14:30:00Z",
      "response_status": 200
    }
  ]
}

Returns up to 50 most recent usage logs.

n8n Integration

We have an official n8n community node. Install it in your n8n instance to use Tone API directly in your workflows.

Installation

Option 1: In n8n, go to Settings → Community Nodes → Install and enter:

package name
n8n-nodes-toneapi

Option 2: If you're self-hosting n8n with Docker:

shell
docker exec -it n8n sh -c "cd /home/node/.n8n/nodes && npm install n8n-nodes-toneapi"
docker restart n8n

Setup

1. Add the Tone API node to your workflow.

2. Create credentials: paste your API key (the one starting with tone_).

3. Choose an operation: Analyze Tone, Detect Emotion, Rewrite, Reply, Compare Tone, Build Audience, Adapt Text, or Get Key Info.

4. Pass text from previous nodes using expressions, e.g. {{ $json.message }}.

Error Codes

CodeMeaning
401Invalid or missing API key
402Out of credits — top up from the dashboard
422Invalid request body or text exceeds 10,000 characters
429Rate limit exceeded — slow down
500Internal server error

Rate Limits

The API allows 60 requests per minute per API key. If you exceed this, you'll receive a 429 response.

Each call to /analyze, /detect-emotion, and /audience costs 1 credit. /rewrite and /adapt cost 2 credits. /compare and /reply cost 3 credits. The /keys/me endpoint is free.

Ready to get started?

Create an account and get your API key in under a minute.

Create account