# ClarCV API

Public HTTP API for [ClarCV](https://clarcv.com), a CV improvement service.

Base URL: `https://clarcv.com`

Machine-readable catalog: [/.well-known/api-catalog](https://clarcv.com/.well-known/api-catalog) (RFC 9727 Linkset).

Agent capability catalog (ARD / AI Catalog): [/.well-known/ai-catalog.json](https://clarcv.com/.well-known/ai-catalog.json).

Auth for agents: [/auth.md](https://clarcv.com/auth.md). OAuth AS metadata: [/.well-known/oauth-authorization-server](https://clarcv.com/.well-known/oauth-authorization-server). Protected resource: [/.well-known/oauth-protected-resource](https://clarcv.com/.well-known/oauth-protected-resource).

Read-only MCP (templates + health, no CV files): `POST https://clarcv.com/api/mcp/` — card at [/.well-known/mcp/server-card.json](https://clarcv.com/.well-known/mcp/server-card.json). There is no A2A agent.

## Public endpoints (no authentication)

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health/` | Process + database health. `200` with `{"status":"ok","database":"up"}` when healthy; `503` when the database is down. |
| `GET` | `/api/cvs/templates/` | List HTML CV templates (id, name, category, thumbnail). Guests may browse; applying a template requires auth. |
| `GET` | `/api/auth/google/config/` | Whether Google Sign-In is configured (`client_id` present or not). |

## Authentication

Most `/api/` routes require a JWT from [Djoser](https://djoser.readthedocs.io/) + SimpleJWT.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/auth/users/` | Register (email + password). New accounts need email activation unless they use Google. |
| `POST` | `/api/auth/jwt/create/` | Login. Body: `{"email","password"}`. Returns `access` and `refresh`. |
| `POST` | `/api/auth/jwt/refresh/` | Refresh access token. |
| `POST` | `/api/auth/google/` | Sign in with a Google Identity Services ID token. |

Send the access token as `Authorization: Bearer <access>`.

## Authenticated CV endpoints

These mutate or return user CV data. They are not for anonymous crawlers.

| Method | Path | Description |
|--------|------|-------------|
| `GET` / `POST` | `/api/cvs/` | List or create saved CVs. |
| `POST` | `/api/cvs/upload/` | Upload a CV file. |
| `POST` | `/api/cvs/analyze/` | Analyse extracted CV text. |
| `POST` | `/api/cvs/analyze-pdf/` | Analyse an uploaded PDF. |
| `POST` | `/api/cvs/apply-template/` | Fill an HTML template and preview or download PDF. |
| `POST` | `/api/cvs/localize-content/` | Rewrite structured CV JSON into Spanish or English. Free: 1 try; Pro unlimited. |
| `POST` | `/api/cvs/generate-improved-cv/` | Generate an improved CV document. |
| `POST` | `/api/cvs/generate-improved-cv/` | Generate an improved CV document. |
| `POST` | `/api/cvs/customize-template/` | AI template customisation. |
| `GET` | `/api/cvs/subscription/` | Current plan. |
| `POST` | `/api/cvs/create-checkout-session/` | Stripe Checkout for Pro. |

Plan limits apply (Free vs Pro). Rate limiting applies to expensive endpoints.

## Status

`GET /health/` is the service status resource (`rel="status"`).