An API for how a person writes.
Idiolect AI learns how a person writes from their own writing. Use that Writing Profile from your server with the REST API, or from an AI app or agent with MCP.
Write with a Writing Profile.
Create a key in Settings → Developer. Send it in the Authorization header as Bearer idl_sk_…. A key works only with the Writing Profiles of its own account. Keep it on your server.
| Endpoint | What it does |
|---|---|
| GET /api/v1/voice | The Writing Profile and its Voice Card. ?voice=<id> picks one profile. |
| POST /api/v1/voice/create | Build a Writing Profile from samples or short answers. |
| POST /api/v1/draft | Write new text from a brief, with optional instructions and format. |
| POST /api/v1/rewrite | Rewrite text, with optional instructions and target register. |
| POST /api/v1/score | Score text against the Writing Profile. |
| GET /api/v1/voice/habits | The habits of the Writing Profile. ?part= and ?habit= narrow the list. |
| POST /api/v1/voice/habits/{id}/confirm | Mark a habit as right. |
| POST /api/v1/voice/habits/{id}/remove | Remove a habit. |
| POST /api/v1/voice/habits/{id}/restore | Bring back a removed habit. |
| POST /api/v1/voice/rules | Save a rule in the words of the person, with an optional scope. |
| PATCH /api/v1/voice/rules/{id} | Change the wording or scope of a rule. |
| DELETE /api/v1/voice/rules/{id} | Remove a rule. |
| GET /api/v1/questions | Open questions about the Writing Profile. |
| POST /api/v1/questions/{id}/answer | Answer one question. |
curl https://idiolect.app/api/v1/rewrite \
-H "Authorization: Bearer idl_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"text":"Please make this clearer.","instructions":"Make it shorter.","language":"fr"}'
// → { "rewritten": "...", "voice": { "id", "name", "isDefault", "selection" },
// "template": null, "evidence": { ... },
// "writingJobId": "...", "writingJobVersionId": "..." }- Without voice, a request uses the default Writing Profile of the account. Get the ids from GET /api/v1/voice.
- language (optional, on /api/v1/draft and /api/v1/rewrite) is a BCP 47 language tag, such as fr or pt-BR. A language name such as French is also accepted and changed to its tag. A value that names no language returns 400 invalid_language. Omit it to keep the language of the request or the source text.
- text and brief: up to 18,000 characters. instructions: up to 8,000. Score text: up to 8,000.
- Drafts and rewrites use the words of your plan. With no words left, you get 402.
- Limits: 30 writing and scoring calls every 5 minutes, and 10 active keys. Over the limit, you get 429 with a Retry-After header.
- Errors are application/problem+json. The error field holds a stable code, such as invalid_key or no_voice.
Connect an AI app.
Idiolect AI is a remote MCP server over Streamable HTTP with OAuth 2.1. In ChatGPT and Claude, add it from the app directory and sign in. Other apps take the connector URL. An agent gets write, rewrite, refine_writing, record_writing_feedback, view_writing_profile, manage_profile, remove_from_profile, view_account, and keep_guest_account. Cached profile calls remain compatible.
https://idiolect.app/api/mcpDirectory listings: ChatGPT, Claude.
For a client that needs a local process, use the idiolect-mcp npm package (Node.js 18 or newer). It uses an API key, not a browser sign-in.
{
"mcpServers": {
"idiolect": {
"command": "npx",
"args": ["-y", "idiolect-mcp"],
"env": { "IDIOLECT_API_KEY": "idl_sk_your_key_here" }
}
}
}Setup for each app, the input of each tool, and troubleshooting: MCP connector docs.
Score text without an account.
Send writing that the person wrote, and the drafts to check. You get a Voice Match from 0 to 100 for each draft. This endpoint needs no key and stores nothing. Up to 64 samples and 32 drafts, each up to 8,000 characters.
curl -X POST https://idiolect.app/api/score \
-H 'content-type: application/json' \
-d '{
"region": ["writing that the person wrote", "..."],
"candidates": ["the draft to score"]
}'
// → {
// "scores": [{ "text": "...", "voiceMatch": 84, "cosine": 0.61, "scored": true,
// "scoreConfidence": "...", "absoluteScoreReportable": false }],
// "metric": { "name": "voice_match", "scale": "0..100 (relative)", "validated": true, ... }
// }relativeCompare the score with the score of a generic draft. Absolute values change with the type of writing.
Read a public Voice Card.
A shared Voice Card is public by its slug. It holds safe fields only, never the writing samples. You can also paste a Voice Card into any chat or custom GPT.
curl https://idiolect.app/api/voice/your-slug
// → { "slug", "summary", "genericnessScore",
// "toneAxes", "signatureMoves", "taboos", "voiceCard" }Every endpoint needs a voice to read.
Make your own Writing Profile first — it is the fastest way to see what the API returns.
Create my Writing ProfileBuilding this for a team, or at volume? Tell us what you need.