API guide

Rewrite text from your own code, on your account’s plan and daily credits.

API keys

Sign in on Lyrmo, open the account menu, and choose API keys. Name the key after what will use it, then copy it: it’s shown only once, and Lyrmo keeps only a hash of it. An account can have 10 keys, and revoking one stops it working at once.

Requests with a key act as your account: they use its plan’s model, its daily credits, and its custom tones, shared with the site and the desktop app. Keys work for rewriting, your usage, and your tones. They can’t make or revoke keys, manage billing, or sign in: those need the site, and a key gets 403 FORBIDDEN.

Keep keys on your server, in an environment variable or secret store. Never put one in a web page, an app people download, or a repository: anyone with it can use your words. Keys start with ly_ so secret scanners can spot them. If one leaks, revoke it and make another.

A first request

curl https://lyrmo.example/api/v1/rewrites \
  -H "Authorization: Bearer $LYRMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "she go to work", "options": {"tone": "friendly"}}'

{
  "rewrites": {
    "minorGrammarFixes": "She goes to work.",
    "naturalRewording": "She heads to work.",
    "enhancedClarity": "She commutes to work.",
    "optimalVersion": "She makes her way to work."
  },
  "usage": { "used": 8, "limit": 1000, "remaining": 992, "resetsAt": "2026-09-29T00:00:00.000Z" }
}

The same from JavaScript, on a server:

const response = await fetch('https://lyrmo.example/api/v1/rewrites', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.LYRMO_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ text: 'she go to work' }),
});
if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.code}: ${problem.detail}`);
}
const { rewrites, usage } = await response.json();

Use your Lyrmo site’s address in place of https://lyrmo.example. The API is under /api/v1 on the same site.

Requests

Rewriting

text is required: up to 5,000 characters, in any language. The optional options steer the three stronger versions:

• tone: natural (the writer’s own), friendly, casual, formal, confident, empathetic, or persuasive
• length: same, shorter, or longer
• language: auto to keep the text’s own, or a code such as en, es, or de to write in that language
• instruction: up to 500 characters in your own words
• savedInstructions: the ids of up to 10 of your saved instructions, followed along with instruction
• customTone: the id of one of your custom tones, in place of tone. Its rules apply to every version, the minor grammar fixes included.

The interactive reference also describes explanations of each change, which the site shows in its Why view. They need the exact list of changes Lyrmo’s own diff finds between a text and one of its rewrites, so they’re meant for Lyrmo’s own apps.

Credits and limits

• Credits. Each rewrite uses 1 credit per word of its text from your plan’s daily balance, shared with dictation and speech on every Lyrmo client. Words are counted between spaces, and at least one for every 10 characters. A text larger than what’s left gets 402 CREDIT_LIMIT_REACHED, with the day’s usage in the response. Allowances reset at midnight UTC.
• Rate limits. Requests with keys are limited per account, however many keys and servers send them: 10 rewrites a minute and 100 a day, unless your Lyrmo says otherwise. Each response’s RateLimit and RateLimit-Policy headers say where you stand; over the limit, you get 429 RATE_LIMITED and a Retry-After header in seconds.
• Sizes. Request bodies are JSON (Content-Type: application/json), up to 72 kB for rewrites.

Errors

Every error is RFC 9457 problem details (application/problem+json). Branch on its code; detail is written for people, and requestId matches Lyrmo’s logs if you need to ask about a request.

Reference

The interactive reference lists every request and response, generated from the API itself, and can send requests with your key. The OpenAPI 3.1 document behind it is at /api/docs/json, for generating a client.

The text you send is handled as the privacy policy describes: it’s rewritten, not stored.