Developers

Authentication

None. The MCP server and the public endpoints need no credentials. Account endpoints (/api/account, /api/cv, sign-in) use a first-party session cookie for write.cv users and are not a public API.

MCP server

A stateless MCP server over streamable HTTP at https://write.cv/mcp (JSON-RPC 2.0, protocol versions 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).
• 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 — initialize, then call a tool:

curl -s https://write.cv/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"my-agent","version":"1.0"}}}'

curl -s https://write.cv/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"list_templates","arguments":{}}}'

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

• /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 abdullah@altaheri.me. Security reports: security.txt.