> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mokaru.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Cover Letter

> Create a cover letter attached to a resume

## Overview

Create a cover letter and link it to a resume. A cover letter cannot exist on its own: `cvId` is **required** and must reference an existing resume the caller owns. If the user has no resumes yet, create one first via `POST /v1/resume`. A resume can have **at most one** cover letter (the `cvId` link is unique). If one already exists, this endpoint returns `409 Conflict` with the existing id - use `PATCH /v1/cover-letter/{id}` to update instead.

<Note>
  **Plus plan only.** This endpoint returns `403 Forbidden` with `{ requiresUpgrade: true }` if the user is on the free plan. The free read/list/delete endpoints stay available so downgraded users can still see and clean up their existing cover letters.
</Note>

<Note>
  **Scope required:** `cover-letter:write` | **Rate limit:** 10 requests/min
</Note>

## Request

```bash theme={null}
POST /v1/cover-letter
```

### Body Parameters

<ParamField body="cvId" type="string" required>
  Resume id this cover letter belongs to. Must be owned by the caller.
</ParamField>

<ParamField body="title" type="string" required>
  Cover letter title (max 200 chars).
</ParamField>

<ParamField body="content" type="string" required>
  Body text. Markdown allowed - the builder renders it.
</ParamField>

<ParamField body="templateId" type="string">
  Optional cover letter template id.
</ParamField>

<ParamField body="isDefault" type="boolean" default="false">
  Mark as the user's default cover letter (unsets any existing default).
</ParamField>

<ParamField body="variables" type="object">
  Template-variable map, e.g. `{ "company": "Acme", "contactPerson": "Jane Doe" }`. Values are strings.
</ParamField>

<ParamField body="showName" type="boolean" default="true">Header: show name.</ParamField>
<ParamField body="showEmail" type="boolean" default="true">Header: show email.</ParamField>
<ParamField body="showPhone" type="boolean" default="true">Header: show phone.</ParamField>
<ParamField body="showAddress" type="boolean" default="true">Header: show address.</ParamField>
<ParamField body="headerAlignment" type="string" default="left">`left | center | right`.</ParamField>
<ParamField body="fontFamily" type="string" default="Inter">Font family.</ParamField>
<ParamField body="fontSize" type="number" default="11">Font size in pt.</ParamField>
<ParamField body="lineSpacing" type="number" default="1.6">Line spacing.</ParamField>

### Example

```bash theme={null}
curl -X POST "https://api.mokaru.ai/v1/cover-letter" \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cvId": "clx1234",
    "title": "Stripe - Backend Engineer",
    "content": "Dear hiring team,\n\nI am applying for ...",
    "variables": { "company": "Stripe", "contactPerson": "Jane Doe" }
  }'
```

## Response

<ResponseField name="success" type="boolean">Whether the cover letter was created.</ResponseField>
<ResponseField name="id" type="string">The new cover letter's unique ID.</ResponseField>

```json theme={null}
{ "success": true, "id": "clx_cl_abc" }
```

### Error: cover letter already exists

```json theme={null}
{
  "error": "Cover letter already exists for this resume",
  "existingId": "clx_cl_existing"
}
```

Status: `409 Conflict`.