API Reference

Overview

The Tonalysis API analyses the tone and subtext of any text. It runs a 4-layer engine — phrase patterns, delta analysis, Q&A gap detection, and structural signals — then synthesises a JSON response with scores, decoded statements, and an executive summary.

POSThttps://api.tonalysis.ai/v1/analyse

Authentication

Pass your API key as a Bearer token in the Authorization header.

Authorization: Bearer tly_live_abc123...

Get your key from the dashboard. Test keys use the tly_test_ prefix and are limited to Layer 1 only.

Request

Send a JSON body with the following fields:

Field	Type	Required	Description
`text`	string	✓	The text to analyse. Max chars depends on tier (test: 50,000; hobby/pro: 150,000).
`category`	string	✓	One of the built-in category keys, or `“custom”` with `customConfig`.
`priorText`	string		Previous version of the text. Enables Layer 2 delta analysis (Hobby/Pro only).
`qaContext`	string		The Q&A section of a document (e.g. analyst questions on an earnings call). Improves Layer 3 gap detection.
`customConfig`	object		Custom category configuration. See Categories.

{
  "text": "We remain comfortable with guidance for the full year...",
  "category": "earnings_call",
  "priorText": "We are confident in our outlook...",
  "qaContext": "Analyst: Can you clarify the margin guidance?\nMgmt: We see continued progress..."
}

Response

A successful response returns HTTP 200 with the following shape:

{
  "data": {
    "category": "earnings_call",
    "overallTone": "cautious",
    "scores": [
      { "axis": "confidence",    "score": 4, "rationale": "..." },
      { "axis": "hedging",       "score": 7, "rationale": "..." },
      { "axis": "transparency",  "score": 5, "rationale": "..." },
      { "axis": "engagement",    "score": 6, "rationale": "..." },
      { "axis": "authenticity",  "score": 5, "rationale": "..." }
    ],
    "decodedStatements": [
      {
        "original":     "We remain comfortable with guidance",
        "decoded":      "Confidence is not strong — expect revision",
        "significance": "high"
      }
    ],
    "avoidedTopics":    ["cash conversion", "EMEA margin decline"],
    "keyFindings":      ["Hedging language increased 40% vs prior quarter"],
    "executiveSummary": "Management tone is guarded...",
    "layerData": {
      "phrases":    [...],
      "deltas":     [...],
      "gaps":       [...],
      "structural": [...]
    }
  },
  "meta": {
    "tier":      "Hobby",
    "used":      12,
    "limit":     500,
    "remaining": 488,
    "durationMs": 4200
  }
}

Fields

Field	Type	Description
`overallTone`	string	One of: `confident`, `cautious`, `defensive`, `evasive`, `neutral`
`scores`	array	5 axis scores 0–10. Axes: `confidence`, `hedging`, `transparency`, `engagement`, `authenticity`
`decodedStatements`	array	Specific phrases decoded: `{ original, decoded, significance }`
`avoidedTopics`	string[]	Topics expected but not addressed
`keyFindings`	string[]	Headline observations for quick scanning
`executiveSummary`	string	1–2 sentence synthesis
`layerData.phrases`	array	Layer 1: phrase patterns with decoded meaning
`layerData.deltas`	array	Layer 2: language shifts vs `priorText` (empty if no priorText)
`layerData.gaps`	array	Layer 3: Q&A gaps — questions asked but not answered
`layerData.structural`	array	Layer 4: structural signals (topic order, density, qualifiers)

Key	Use case
`earnings_call`	Earnings call transcripts, management commentary
`investor_presentation`	Investor decks, capital markets day materials
`performance_review`	Employee performance reviews, feedback documents
`exit_interview`	Exit interview transcripts
`contract_negotiation`	Contract drafts, term sheets, negotiation emails
`sales_call`	Sales call transcripts, demos, discovery calls
`general`	Universal fallback for any text type

Tier Restrictions

Tier	Monthly limit	Layers	Synthesis	Delta (Layer 2)
Test	10	Layer 1 only	No	No
Hobby	500	All 4	Yes	Yes
Pro	1,000	All 4	Yes	Yes
Custom	Negotiated	All 4	Yes	Yes

On the Test tier, overallTone, scores, decodedStatements, and executiveSummary are not returned. The response includes a _notice field explaining the upgrade path.

Error Codes

HTTP	Error code	Meaning
401	`MISSING_API_KEY`	No Bearer token provided
401	`INVALID_API_KEY`	Key not found or revoked
400	`MISSING_TEXT`	`text` field is required
400	`MISSING_CATEGORY`	`category` field is required
400	`INVALID_CATEGORY`	Category key not recognised
400	`INPUT_TOO_LARGE`	Text exceeds tier character limit
429	`QUOTA_EXCEEDED`	Monthly call limit reached
500	`ANALYSIS_FAILED`	Internal error during analysis