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/mcpTools:
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/enRate 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: 200Errors
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
- /openapi.json — OpenAPI 3.1 description
- /.well-known/api-catalog — API catalog (RFC 9727)
- /AGENTS.md — Agent guide
- /llms.txt — Short LLM overview
- /llms-full.txt — Expanded LLM context + CV JSON schema
- /.well-known/agent-card.json — A2A agent card
- /.well-known/agent-skills/index.json — Agent skills index
- /sitemap.xml — Sitemap
Support
Questions or a bug in the API? Email support@write.cv. Security reports: security.txt.