EchoWriting API Reference

Rewrite text in your own voice - programmatically.

The EchoWriting API gives you direct access to the same rewrite engine, voice presets, and history that powers echowriting.ai. Send raw text in, get text rewritten in your chosen voice out.

• Base URL: https://api.echowriting.ai
• Authentication: Authorization: Bearer ewr_live_...
• Format: All endpoints are POST. All bodies and responses are JSON. UTF-8 throughout.
• API version: v1 (stable).

Quickstart

export EWR_KEY="ewr_live_AbCd1234..."

curl -X POST https://api.echowriting.ai/v1/rewrite \
  -H "Authorization: Bearer $EWR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset_id": "casual_dm",
    "input_text": "We are pleased to inform you that your order has shipped."
  }'

Response:

{
	"id": "08c3a1b2-...",
	"status": "ready",
	"thread_id": "f3a17e09-...",
	"version_no": 1,
	"preset_id": null,
	"preset_name_snapshot": "Casual DM",
	"input_text": "We are pleased to inform you that your order has shipped.",
	"output_text": "good news - your order's on the way",
	"error": null,
	"opts": null,
	"truncated": false,
	"billed": true,
	"source": "api",
	"created_at": "2026-05-03T14:22:31.118Z",
	"updated_at": "2026-05-03T14:22:35.402Z"
}

Authentication

Every request must include:

Authorization: Bearer ewr_live_AbCd...WxYz
Content-Type: application/json

Keys are minted from your account at echowriting.ai. Sign in on a paid plan (Pro or Plus), open API key settings, name your key, and click Create key. The full secret is shown once - copy it immediately. You can rotate it later if you lose it (same id, fresh secret), but you cannot retrieve the original.

Key shape

ewr_live_ + 32 url-safe characters, e.g. ewr_live_AbCd1234EfGh5678IjKl9012MnOp34. 192 bits of cryptographic entropy. Treat it like a password - never commit it to source, never embed it in client-side code.

Authentication errors

Plans, quota, and pricing

API requests share the same weekly rewrite quota as your web account. There is no separate API tier - Pro gets 50 rewrites/week total (web + API combined), Plus gets 110.

Quota resets on your billing-period rollover (Stripe-driven; the date is shown on the web account page). Failed requests are never billed - if the server returns status: "failed" or a 5xx error, your quota is automatically refunded.

What counts as a "rewrite"?

• The first rewrite within a thread (v1) counts.
• The first regenerate within a thread is free (one freebie per thread).
• Subsequent regenerates count.
• Cached idempotent replays (within 24h) do not count - same idempotency_key returns the existing job without re-billing.

Quota exhaustion

When you hit your weekly cap, the API returns:

{
	"error": {
		"code": "quota_exhausted",
		"message": "Rewrite quota exhausted for this billing period",
		"remaining": 0,
		"plan_slug": "pro"
	}
}

Wait for the next period rollover, or upgrade.

Endpoints

Rewrite

The core endpoint. Submit text + a preset_id (a voice), get the rewritten text back.

You can call it two ways:

Both modes share the same request body and produce the same job shape. The async path is also the recovery path for a dropped sync connection - see Recovering a dropped sync call.

POST /v1/rewrite (sync)

Submit a rewrite and wait for it to finish.

Request body:

opts shape

{
	"tone_shift": "more terse",
	"length_target": "~300 words",
	"format_hint": "keep bullet structure"
}

All three fields are optional and independent.

Example request:

curl -X POST https://api.echowriting.ai/v1/rewrite \
  -H "Authorization: Bearer $EWR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset_id": "casual_dm",
    "input_text": "We are pleased to inform you that your order has shipped.",
    "opts": {
      "length_target": "one sentence"
    }
  }'

Response: 200 OK (even when the job ends in status: "failed" - the HTTP layer succeeded; the job state is on the body).

The response also carries X-Echo-Job-Id: <id> in the headers. The server flushes this header before starting the LLM work, so even if your connection drops mid-call, your HTTP client may have already received the recovery id. See Recovering a dropped sync call.

{
	"id": "08c3a1b2-...",
	"status": "ready",
	"thread_id": "f3a17e09-...",
	"version_no": 1,
	"preset_id": null,
	"preset_name_snapshot": "Casual DM",
	"input_text": "We are pleased to inform you that your order has shipped.",
	"output_text": "good news - your order's on the way",
	"error": null,
	"opts": {
		"length_target": "one sentence"
	},
	"truncated": false,
	"billed": true,
	"source": "api",
	"created_at": "2026-05-03T14:22:31.118Z",
	"updated_at": "2026-05-03T14:22:35.402Z"
}

Job shape

This shape is returned by all four rewrite endpoints (sync, async-after-it-finishes, jobs/get, jobs/list).

Errors:

POST /v1/rewrite/jobs (async)

Submit a rewrite and return immediately. Same request body as the sync path.

Response: 202 Accepted

{
	"id": "08c3a1b2-...",
	"status": "pending"
}

Then poll POST /v1/rewrite/jobs/get until status is ready or failed. Recommended polling cadence: every 1.5 - 3 seconds.

Idempotent hits. If your idempotency_key matches an existing job, the response is 200 OK with the full existing job shape (not 202).

Errors: identical to POST /v1/rewrite.

POST /v1/rewrite/jobs/get

Fetch the current state of a job by id.

Request body:

Example request:

curl -X POST https://api.echowriting.ai/v1/rewrite/jobs/get \
  -H "Authorization: Bearer $EWR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "08c3a1b2-..."}'

Response: 200 OK with the job shape.

Errors:

POST /v1/rewrite/jobs/list

Paginated list of your jobs, newest first.

Request body:

Example request:

curl -X POST https://api.echowriting.ai/v1/rewrite/jobs/list \
  -H "Authorization: Bearer $EWR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "ready", "limit": 50}'

Response: 200 OK

{
	"jobs": [
		{ "id": "08c3...", "status": "ready", "...": "..." },
		{ "id": "0b7e...", "status": "ready", "...": "..." }
	],
	"next_cursor": "2026-05-02T10:18:55.000Z"
}

next_cursor is the ISO timestamp to pass as before to fetch the next page. null when no more pages.

Errors:

Threads

Every rewrite belongs to a thread. A thread groups one or more versions (re-runs of the same input). The first rewrite is v1; each regenerate via thread_id is v2, v3, etc. The web app shows threads in a sidebar; the API mirrors that history.

POST /v1/threads/list

Paginated list of your threads, most-recently-active first.

Request body:

Response: 200 OK

{
	"threads": [
		{
			"id": "f3a17e09-...",
			"title": "We are pleased to inform you that your order has shipped.",
			"updated_at": "2026-05-03T14:22:35.402Z"
		}
	],
	"next_cursor": "2026-05-02T10:18:55.000Z"
}

The title is auto-derived from the first version's input (first non-empty line, <=60 chars on a word boundary). Frozen - does not change as you regenerate.

POST /v1/threads/search

Full-text search across your thread history. One row per matching thread.

Request body:

Response: 200 OK

{
	"threads": [
		{
			"thread_id": "f3a17e09-...",
			"title": "We are pleased to inform you that your order has shipped.",
			"preset_name_snapshot": "Casual DM",
			"created_at": "2026-05-03T14:22:31.118Z",
			"updated_at": "2026-05-03T14:22:35.402Z",
			"rank": 0.0987,
			"snippet": "We are pleased to inform you that your <mark>order</mark> has shipped."
		}
	],
	"limit": 30,
	"offset": 0,
	"next_offset": null
}

snippet includes <mark> tags around matched terms. Failed/pending versions are excluded.

POST /v1/threads/get

Fetch a thread plus every version (v1..vN).

Request body:

Response: 200 OK

{
	"id": "f3a17e09-...",
	"title": "We are pleased to inform you that your order has shipped.",
	"free_retry_used": true,
	"created_at": "2026-05-03T14:22:31.118Z",
	"updated_at": "2026-05-03T14:25:18.000Z",
	"versions": [
		{
			"id": "08c3...",
			"version_no": 1,
			"preset_id": null,
			"preset_name_snapshot": "Casual DM",
			"input_text": "We are pleased to inform you that your order has shipped.",
			"output_text": "good news - your order's on the way",
			"opts": null,
			"truncated": false,
			"billed": true,
			"status": "ready",
			"source": "api",
			"error": null,
			"created_at": "2026-05-03T14:22:31.118Z"
		}
	]
}

free_retry_used indicates whether the thread's one-time free regenerate has been consumed.

POST /v1/threads/delete

Hard-delete a thread. All its versions cascade.

Request body:

Response: 200 OK

{ "deleted": true, "id": "f3a17e09-..." }

Deleted threads are unrecoverable. The associated usage_events (billing audit) survive.

Presets

A preset is a voice profile. You can either use one of the read-only global presets (casual_dm, reddit_voice, x_voice, professional_voice) or create your own custom voice from 3-5 writing samples.

Custom preset creation is a paid feature. Free users can only use global presets.

A new custom preset takes 5-30 seconds to build. Submit /v1/presets/create, then poll /v1/presets/get until status: "ready".

POST /v1/presets/list

Returns all presets visible to you: global presets plus your own custom ones.

Request body: {}

Response: 200 OK

{
	"presets": [
		{
			"id": "casual_dm",
			"name": "Casual DM",
			"status": "ready",
			"source": "global",
			"display_order": 1,
			"created_at": "2026-04-01T00:00:00Z",
			"updated_at": "2026-04-01T00:00:00Z"
		},
		{
			"id": "<user-preset-uuid>",
			"name": "My Voice",
			"status": "ready",
			"source": "user",
			"error": null,
			"created_at": "2026-05-01T09:00:00Z",
			"updated_at": "2026-05-01T09:01:13Z"
		}
	]
}

Globals appear first (curated display_order), then user presets newest-first.

POST /v1/presets/get

Fetch a single preset's details.

Request body:

Response: 200 OK

{
	"id": "<preset-uuid>",
	"name": "My Voice",
	"status": "ready",
	"source": "user",
	"style_card_md": "# Voice profile\n\n- ...",
	"error": null,
	"created_at": "2026-05-01T09:00:00Z",
	"updated_at": "2026-05-01T09:01:13Z"
}

style_card_md is the human-readable Markdown summary of the trained voice (only present when status === "ready"). error is non-null when status === "failed".

POST /v1/presets/create

Train a new custom preset from 3-5 writing samples.

Request body:

Response: 202 Accepted

{ "id": "<new-preset-uuid>", "status": "building" }

The build runs asynchronously. Poll /v1/presets/get until status === "ready" (5-30 s typical) or failed.

Errors:

POST /v1/presets/update

Rename a preset, or replace its samples / brief (which triggers a rebuild). Either operation can be done independently.

Request body:

Response:

• Pure rename: 200 OK { "id": "...", "status": "ok" }
• Sample/brief change (triggers rebuild): 202 Accepted { "id": "...", "status": "building" }

Errors:

POST /v1/presets/rebuild

Re-run the build pipeline against the existing samples (e.g. after a model upgrade, or to recover from a failed row).

Request body:

Response: 202 Accepted with { id, status: "building" }.

Errors: as for /v1/presets/update.

POST /v1/presets/delete

Hard-delete a custom preset.

Request body:

Response: 200 OK { "deleted": true, "id": "<uuid>" }.

rewrite_versions.preset_id for past rewrites becomes NULL (history preserved via preset_name_snapshot). Global presets are non-deletable - the API returns 403 global_preset_immutable.

Idempotency

All mutating rewrite endpoints accept an optional idempotency_key body field. If the same key is replayed within 24h, the original job is returned without re-running the LLM, without re-billing, and without inserting a new row.

• Keys must match [A-Za-z0-9_-]{1,128}.
• The key is scoped to your account - no collisions between users.
• Two parallel requests with the same key race-resolve safely: one wins the insert, the other is refunded automatically and returns the winner's job.
• Replays after 24h still return the cached job (the underlying unique index isn't time-bounded), but new replays beyond that window aren't guaranteed to dedupe - a future cleanup may invalidate them.

Recommended pattern for any client retrying on a network error:

const key = crypto.randomUUID();
const submit = () =>
	fetch('https://api.echowriting.ai/v1/rewrite', {
		method: 'POST',
		headers: { Authorization: `Bearer ${EWR_KEY}`, 'Content-Type': 'application/json' },
		body: JSON.stringify({ preset_id, input_text, idempotency_key: key }),
	});

// Retry up to 3 times - same key, no double-billing.
for (let i = 0; i < 3; i++) {
	try {
		return await submit();
	} catch (e) {
		if (i === 2) throw e;
		await sleep(1000 * (i + 1));
	}
}

Rate limits

Limits are per user, shared across all of your API keys.

Every response includes the standard headers:

These headers are exposed via CORS for browser-based SDKs.

When you hit a limit:

{
	"error": {
		"code": "rate_limited",
		"message": "Too many requests"
	}
}

with 429 Too Many Requests. Read the Retry-After header and wait.

Errors

Every error response shares one envelope:

{
	"error": {
		"code": "snake_case_constant",
		"message": "human readable description",
		"...": "extra fields specific to the code"
	}
}

Code reference

Failures inside async jobs

If a job fails inside the LLM pipeline (humanizer down, model timeout, etc.), the HTTP layer still returns 200 OK. The failure is on the job, not the request. Always check status, not the HTTP code:

{
	"id": "08c3...",
	"status": "failed",
	"error": {
		"code": "humanizer_failed",
		"message": "humanizer upstream 503: ..."
	},
	"...": "..."
}

Your weekly quota is automatically refunded for failed jobs. You don't pay for failures.

failed job error codes

Recovering a dropped sync call

The sync endpoint sets X-Echo-Job-Id: <id> in the response headers and flushes them before the LLM work begins. If your connection drops mid-call, your HTTP client may already have the recovery id.

// Pseudo-code
const res = await fetch("https://api.echowriting.ai/v1/rewrite", { ... });
const jobId = res.headers.get("X-Echo-Job-Id");
try {
  return await res.json();
} catch (timeoutOrAbort) {
  // Connection dropped mid-LLM. Use the saved id to recover.
  for (let i = 0; i < 60; i++) {
    await sleep(2000);
    const job = await fetchJob(jobId);
    if (job.status === "ready" || job.status === "failed") return job;
  }
  throw new Error("recovery polling timed out");
}

If your HTTP client doesn't expose response headers for a timed-out request, prefer the async pattern (POST /v1/rewrite/jobs) from the start - you always get the id back in the response body.

Versioning

/v1 is stable. Backwards-compatible changes ship in place:

• New optional fields on requests and responses.
• New endpoints under /v1/.
• New optional headers.

Any breaking change creates /v2/; /v1 remains supported until announced sunset (minimum 12 months of dual-running).

Changelog

2026-05-03 - initial release

• All /v1/rewrite/*, /v1/threads/*, /v1/presets/* endpoints.
• Bearer-token auth via Authorization header.
• Idempotency keys with 24h dedupe window.
• X-Echo-Job-Id recovery header on sync rewrites.