write.cvOpen the editor

Developers

write.cv welcomes AI agents and developers. The public tools and endpoints need no API key or sign-up, with open CORS: use the MCP server to author, validate, score and share CVs, or read the public JSON endpoints. With a user's personal access token, agents can also read and fill that user's own saved CV. The machine-readable versions of this page are openapi.json and AGENTS.md.

Authentication

None for the public MCP tools and endpoints. The MCP account tools take a personal access token in Authorization: Bearer wcv_…: a signed-in user creates it in the editor (account menu → Connect AI agent), sees it once, and can revoke it any time. A token can read and edit that account's CV only — no publishing, no account settings. Only its SHA-256 is stored. An unknown or revoked token gets 401 with a WWW-Authenticate: Bearer challenge. Account endpoints (/api/account, /api/cv, /api/tokens, sign-in) use a first-party session cookie and are not a public API.

MCP server

A stateless MCP server over streamable HTTP at https://write.cv/mcp (JSON-RPC 2.0). It speaks the stateless 2026-07-28 protocol (per-request _meta, server/discover) and the earlier initialize handshake (2024-11-05 through 2025-11-25). Server card: /.well-known/mcp/server-card.json.

claude mcp add --transport http write-cv https://write.cv/mcp

Tools:

  • get_site_overview — What write.cv is and how to point a user to it.
  • get_cv_json_schema — The CV JSON shape and authoring rules.
  • validate_cv_json — Lint a CV JSON object and list structural issues before loading it.
  • score_cv — 0–100 ATS score with a category breakdown and prioritised fixes.
  • list_templates — The 7 CV templates (id, name, category, description).
  • list_profile_templates — The 20 public-profile (website) templates with a live preview link and a link that opens the CV-to-website flow with the template preselected.
  • create_cv_share_link — A one-click link that opens the CV already loaded in the builder, plus a read-only preview link. The CV travels in the URL fragment and never reaches a server.

Typical loop: author → validate_cv_json → score_cv → improve → create_cv_share_link.

Example — discover, then call a tool:

# Modern (2026-07-28): discover, then call — every request carries _meta
curl -s https://write.cv/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: server/discover" \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{
       "io.modelcontextprotocol/protocolVersion":"2026-07-28",
       "io.modelcontextprotocol/clientCapabilities":{}}}}'
curl -s https://write.cv/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" -H "Mcp-Name: list_templates" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
       "name":"list_templates","arguments":{},"_meta":{
       "io.modelcontextprotocol/protocolVersion":"2026-07-28",
       "io.modelcontextprotocol/clientCapabilities":{}}}}'

# Legacy clients (2025-11-25 and earlier) use the initialize handshake as before.

Account tools: the user's own CV

With the user's access token, an agent such as Claude Code works on the CV saved in their write.cv account — reads it, fills it in step by step, and checks the score. The user's open editor picks the changes up.

# Claude Code — the token comes from the editor's "Connect AI agent" dialog
claude mcp add --transport http write-cv https://write.cv/mcp   --header "Authorization: Bearer wcv_…"

# Other MCP clients
{ "mcpServers": { "write-cv": { "type": "http", "url": "https://write.cv/mcp",
    "headers": { "Authorization": "Bearer wcv_…" } } } }
  • get_my_cv — The user's saved CV document (every language version + display meta), its version updatedAt, item ids, and the public page URL if published. Photos are omitted.
  • update_my_cv — Granular edits, all-or-nothing: set_personal_info, set_summary, add_item, update_item, remove_item, move_item, set_bullets, set_section_visibility. Returns the new updatedAt, touched ids and the ATS score.
  • save_my_cv — Replace one language version with a complete CV (ids optional, minted when missing); other languages are kept by default.
  • score_my_cv — ATS-score the saved CV with its own template, optionally against a job description.

Workflow: get_my_cv → update_my_cv (or save_my_cv) with base_updated_at set to the latest updatedAt → score_my_cv. Writes use optimistic concurrency: if the user edited in between, nothing is written and the tool returns a conflict error with the current updatedAt — re-read, re-apply, retry. Without a token these tools return an error explaining how to connect, and the public tools keep working. New values follow the validate_cv_json rules; problems already in the user's CV don't block edits. Saves share a per-user budget with the editor (40 per minute); request bodies are capped at 256 KB.

# 1. Read: note updatedAt and the item ids
{"name":"get_my_cv","arguments":{}}

# 2. Edit, naming the version you read (all-or-nothing, ≤ 50 ops)
{"name":"update_my_cv","arguments":{
  "base_updated_at": 1791016966876,
  "operations":[
    {"op":"set_summary","value":"Engineer with 5 years building web platforms."},
    {"op":"add_item","section":"skills","item":{"name":"Go","level":"advanced"}},
    {"op":"set_bullets","section":"experience","id":"zm2choh",
     "bullets":["Led the move to the edge, cutting latency 40%"]}]}}

# 3. Changed in between? → isError + {"error":"conflict","updatedAt":…}:
#    get_my_cv again, re-apply, retry. Otherwise: new updatedAt + ATS score.

Public JSON endpoints

GET/api/reviews — Published user reviews plus the rating aggregate (count, average). Cached for 60 seconds.

{
  "count": 49,
  "avg": 4.84,
  "reviews": [
    { "name": "Hamza", "stars": 5, "comment": "Really simple and effective!",
      "country": "", "date": 1785804739 }
  ]
}

GET/api/stats — Lifetime count of CVs created (exported to PDF). Cached for 5 minutes. Response: {"created": 1216}

GET/, /en, /ar — Send Accept: text/markdown to get a token-efficient Markdown rendition of the page instead of HTML.

curl -H "Accept: text/markdown" https://write.cv/en

Rate limits

200 requests per 60 seconds per IP address, shared across /api/* and /mcp. Every response carries the policy in RateLimit-Policy (IETF draft format) and X-RateLimit-Limit. Over the limit you get 429 Too Many Requests with a Retry-After header — wait that many seconds and retry. Please cache responses; the public endpoints change slowly.

RateLimit-Policy: "default";q=200;w=60
X-RateLimit-Limit: 200

Errors

REST errors are JSON in the RFC 9457 application/problem+json format with the right HTTP status (400, 404, 405, 413, 429, 500). The MCP server returns standard JSON-RPC errors: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params.

HTTP/2 404
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No API endpoint at /api/nope. See https://write.cv/developers"
}

Discovery files

Support

Questions or a bug in the API? Email support@write.cv. Security reports: security.txt.

AboutContactPrivacy PolicyTerms of Use