Developers

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.

REST API

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.

EndpointWhat it does
GET /api/v1/voiceThe Writing Profile and its Voice Card. ?voice=<id> picks one profile.
POST /api/v1/voice/createBuild a Writing Profile from samples or short answers.
POST /api/v1/draftWrite new text from a brief, with optional instructions and format.
POST /api/v1/rewriteRewrite text, with optional instructions and target register.
POST /api/v1/scoreScore text against the Writing Profile.
GET /api/v1/voice/habitsThe habits of the Writing Profile. ?part= and ?habit= narrow the list.
POST /api/v1/voice/habits/{id}/confirmMark a habit as right.
POST /api/v1/voice/habits/{id}/removeRemove a habit.
POST /api/v1/voice/habits/{id}/restoreBring back a removed habit.
POST /api/v1/voice/rulesSave 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/questionsOpen questions about the Writing Profile.
POST /api/v1/questions/{id}/answerAnswer one question.
POST https://idiolect.app/api/v1/rewrite
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.
MCP

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.

Connector URL
https://idiolect.app/api/mcp

Directory 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.

MCP client configuration
{
  "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 API

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.

POST https://idiolect.app/api/score
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.

Voice Card

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.

GET https://idiolect.app/api/voice/
curl https://idiolect.app/api/voice/your-slug

// → { "slug", "summary", "genericnessScore",
//     "toneAxes", "signatureMoves", "taboos", "voiceCard" }
Start here

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 Profile

Building this for a team, or at volume? Tell us what you need.

Idiolect AI for developers - API and MCP | Idiolect AI