Track Anatomy API

Overview

The Track Anatomy API creates analyses from an audio file or a public YouTube link and returns the same report shown on the website. All responses are JSON. The base URL is https://trackanatomy.com/api/v1.

Create and manage keys on the API keys page. Send a key in the Authorization header:

Authorization: Bearer ta_live_...

Keys need an active credit plan. A key is shown once when it is created, can be revoked at any time and carries its own request, concurrency and daily-spend limits. Never put a key in a query string.

Credits work as they do on the website. An upload costs 10 credits and a link analysis costs 15. Each analysis includes one lyrics set; further sets for the same analysis cost 3 credits. The account daily limit of 120 credits applies across the website and the API.

An analysis response includes lyrics.includedLeft and lyrics.extraPrice. A lyrics response includes credits.included; together they show whether a set is included and what another set will cost.

Quick start

1. Create an API key on the API keys page and keep the full key in a server-side secret store.
2. Create an analysis with a file or a public link.
3. Poll the analysis by id until status is succeeded or failed.
4. Read report from the completed analysis, or use a signed webhook instead of polling.

Create from a file

curl -X POST https://trackanatomy.com/api/v1/analyses \
  -H "Authorization: Bearer $TRACK_ANATOMY_KEY" \
  -H "Idempotency-Key: upload-2026-10-30-001" \
  -F "file=@track.mp3" \
  -F "webhook_url=https://example.com/hooks/track-anatomy"

Create from a link

curl -X POST https://trackanatomy.com/api/v1/analyses \
  -H "Authorization: Bearer $TRACK_ANATOMY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"link":"https://www.youtube.com/watch?v=abcdefghijk"}'

Poll

curl https://trackanatomy.com/api/v1/analyses/an_example \
  -H "Authorization: Bearer $TRACK_ANATOMY_KEY"

A new job answers 202. Poll no more often than every few seconds. A cached link report can answer 200 with the report already complete. Poll until status is succeeded or failed; then read report or error.

Endpoints

Create an analysis

POST /analyses

Send either multipart/form-data with a file field, or JSON with a link field. Public YouTube videos are accepted. The first 10 minutes of a link are used.

API keys can add webhook_url. It must be an HTTPS URL on port 443, without credentials. Private, loopback, link-local, multicast and carrier-grade NAT addresses cannot be targets.

Add Idempotency-Key to make retries safe. A fresh job answers 202. A cached link report can answer 200 with the report already included.

Read an analysis

GET /analyses/{id}

The response is an Analysis object. While a job is queued or running, report is null. When it completes, report is a report object. On failure, error carries a stable code and a plain message.

List analyses

GET /analyses?limit=20&cursor=...&type=upload&q=...

limit is 1 to 100. type is upload or link. q searches the caller's analyses. Follow nextCursor until it is null.

Delete an analysis

DELETE /analyses/{id}

Deletes a finished analysis and its lyrics sets from history. It returns 204. A queued or running analysis cannot be deleted.

Create lyrics

POST /analyses/{id}/lyrics

The JSON body can contain genre, theme, language, style and, for API keys, webhook_url. Each string is optional and trimmed before use. The job answers 202; poll GET /lyrics/{id} or wait for a webhook.

Read lyrics

GET /lyrics/{id} returns a Lyrics object. GET /analyses/{id}/lyrics returns { "data": [...] } with every completed set for that analysis, newest first.

Read the account

GET /account returns the key owner's email, active plan, next plan, available credits, usage today and free-test count. API-key usage consumes the same account credits and obeys the account daily limit.

Objects

Analysis

An AnalysisSummary has the same base fields plus title, tempo and key. List responses use this smaller shape.

Lyrics

Account

Report

Every report has schema: "ta.report.v1".

certainty is one of:

Webhooks

An API key can attach webhook_url when it creates an analysis or lyrics set. Track Anatomy sends a signed POST request after the job succeeds or fails.

The body is the same object returned by the matching GET endpoint, plus an event field. Read the job status before reading report or lyrics; a failed job includes error.

Every request has these headers:

The signed content is <timestamp>.<raw body> using the webhook secret shown when the key was created. Compare the signature in constant time and reject timestamps outside five minutes.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, signatureHeader, secret) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signatureHeader ?? '');
  if (!match) return false;

  const timestamp = Number(match[1]);
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest();
  const received = Buffer.from(match[2], 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Answer with any 2xx status within 10 seconds. Redirects are not followed and count as failures. Failed requests retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After the sixth failed attempt the delivery stops.

The URL must use HTTPS on port 443 and must not contain credentials. A hostname that resolves to a private, loopback, link-local, carrier-grade NAT or multicast address is refused: nothing is sent and the delivery is not retried.

Errors

Every error has the same JSON shape:

{
  "error": {
    "code": "validation_error",
    "message": "Some details are missing or not valid."
  }
}

A 429 response includes Retry-After in seconds. Do not retry other 4xx responses without changing the request.

Limits and idempotency

Each API key has three limits:

• Requests per minute. A 429 response includes Retry-After.
• Concurrent queued and running jobs.
• An optional daily credit spend limit set by the customer.

The account daily limit of 120 credits also applies. Uploads and links use the same credit balance as the website, and all limits reset on UTC boundaries.

Send Idempotency-Key on every create request that may be retried. A key is stored for 24 hours.

For multipart uploads, the file content and field values are compared. Keep request field values identical when retrying. Do not reuse a key for a different analysis or lyrics request.

Changelog

v1 - initial release

• File and public-link analyses
• Reports, lyrics and account usage
• Signed webhooks with retries
• Per-key request, concurrency and daily-spend limits
• Idempotent create requests