# Vitex — Career as Code

> Vitex is a hosted service that compiles a tailored, ATS-optimized resume PDF
> and cover letter from a job description plus your background. Your career facts
> are the source code; each resume is a build artifact compiled on demand for a
> specific job. The whole product is reachable over an HTTP API with an API key —
> so a person's AI assistant (Claude, ChatGPT, Cursor, or any agent) can drive it
> end to end, with no browser, cookie, 2FA, or CAPTCHA.

## For AI agents (start here)

**The API is the UI.** Everything the web app does, an agent can do over HTTP
with a Bearer API key. If you are an assistant helping someone build or tailor a
resume, drive Vitex directly rather than sending them to a form.

- [Agent skill / runnable playbook](https://www.vitex.org.nz/skill.md): copy-paste
  curl walkthrough that takes any agent from "mint a key" to "download the PDF".
- [OpenAPI 3.1 specification](https://www.vitex.org.nz/openapi.yaml): machine-readable
  contract for the public v1 API and the profiles endpoints.
- [Full v1 API reference](https://github.com/ChanMeng666/easy-resume/blob/master/docs/api/v1.md):
  prose reference for generation, refinement, profiles, threads, and the applications tracker.
- **CLI & MCP:** `vitex-cli` (bin `vitex`, `npm i -g vitex-cli`) is a thin client over
  this API — a token-cheap CLI for terminals/coding agents, plus `vitex mcp` (a stdio
  MCP server via `npx -y vitex-cli mcp`) for Claude Desktop, Claude Code, and Cursor.
  See [cli/README.md](https://github.com/ChanMeng666/easy-resume/blob/master/cli/README.md).
- **Hosted MCP (for AI assistants):** a browser-OAuth remote MCP server at
  `https://www.vitex.org.nz/api/mcp` exposes the same capabilities as MCP tools — the
  consumer channel complement to the CLI. Non-technical users connect it inside ChatGPT
  or Claude with a sign-in (no API key to paste). Setup guides:
  [ChatGPT](https://github.com/ChanMeng666/easy-resume/blob/master/docs/connectors/chatgpt.md),
  [Claude](https://github.com/ChanMeng666/easy-resume/blob/master/docs/connectors/claude.md).

## What Vitex does

Vitex turns a "career as code" workflow into a hosted service:

- **Your candidate profile is the repository.** Enter your background once; reuse
  it across every job description.
- **Each tailored resume PDF is a build artifact**, compiled on demand for one
  job description via the Typst typesetting engine (compiles in well under a
  second, locally on the server — no external typesetting or third-party service).
- **The refine version chain is commit history.** Every refinement is a new
  version linked to its parent; the parent is never mutated.
- **The generation pipeline is CI.** An 8-step pipeline parses the JD and
  background, analyzes the skill match, tailors the resume, scores ATS coverage,
  writes a cover letter, renders Typst, and compiles the PDF.
- **Billing is outcome-based.** You pay only for a successful build: 1 credit per
  successfully compiled PDF. Failed jobs cost nothing. Refinements and edits are
  free. New accounts start with 3 free credits.
- **Zero lock-in.** Every result includes the downloadable Typst (`.typ`) source —
  the equivalent of `git clone` for your resume.

## Core agent API (Bearer API key)

Async job model: create a job, poll it, fetch the PDF.

- `POST /api/v1/resumes` — create a generation job from `jobDescription` +
  `background` (or a saved `profile_id`). Returns `202` with a job handle.
- `GET /api/v1/resumes/{id}` — poll job status (`queued|running|succeeded|failed`).
- `GET /api/v1/resumes/{id}/pdf` — download the compiled PDF once succeeded.
- `POST /api/v1/resumes/{id}/refine` — refine a succeeded resume with
  natural-language feedback (free; optional `scope` of `resume|cover_letter|both`).

## Candidate profiles (enter once, reuse across JDs)

- `GET /api/profiles` — list your saved backgrounds.
- `POST /api/profiles` — create one from raw text (parsed server-side; free).
- `GET /api/profiles/{id}` — fetch one with its parsed data.
- `PUT /api/profiles/{id}` — update label / raw background (re-parses on change).
- `DELETE /api/profiles/{id}` — delete.

## Public career endpoints (LinkedIn is for humans; a Vitex endpoint is for AIs)

A profile can be opt-in **published** to a stable public URL that serves an
allowlist projection of the candidate's parsed background — never their email,
phone, or photo. The same career facts are available as a human page and as
machine JSON/Markdown, so an AI agent can read a candidate's career directly.

- `POST /api/profiles/{id}/publish` — publish (owner only) → `{ slug, url, publishedAt }`.
- `DELETE /api/profiles/{id}/publish` — unpublish; the slug is kept so republishing
  restores the same URL.
- `GET /p/{slug}` — human-readable HTML profile page (indexable).
- `GET /p/{slug}/json` — the projection as JSON (unauthenticated, cached 5 min).
- `GET /p/{slug}/md` — the projection as `text/markdown` (unauthenticated, cached 5 min).

## Additional agent-usable surfaces

Both accept the same Bearer API key. They live under `/api/*` rather than
`/api/v1/*`; see the transport note in the v1 reference.

- `GET|POST /api/applications` and `GET|PATCH|DELETE /api/applications/{id}` —
  a job-application tracker (statuses `draft|applied|interview|offer|rejected`),
  optionally linked to the generation job that produced the resume. Free.
- `GET|POST /api/threads` and `POST /api/threads/{id}/messages` — a conversational
  edit agent (SSE tool loop) for iterative, working-state edits to a generated
  resume and cover letter. Free. For simple "change this resume with words",
  prefer the stateless `POST /api/v1/resumes/{id}/refine` primitive.

## Authentication

- Send `Authorization: Bearer vitex_<prefix>_<secret>` on every request.
- A person mints a key once while signed in to the web app (`POST /api/keys` is
  cookie-session only); the raw token is shown once and only its SHA-256 hash is
  stored. Keys are self-managed via `GET /api/keys` and `DELETE /api/keys?id=<id>`.

## Error handling

Every error (HTTP response or a `failed` job) shares one machine-readable
envelope, so an agent never parses prose:

```json
{ "error": { "code": "PIPELINE_COMPILATION_FAILED", "message": "...", "retriable": false, "step": "compile", "requestId": "req_...", "details": {} } }
```

`retriable` tells an agent whether a blind retry may help. Rate limits return
`429` with `Retry-After` / `X-RateLimit-*` headers.

## The web app (for humans)

- Homepage: paste a job description + your background, generate a resume.
- My Resumes: history of every generation, with re-open, PDF/cover-letter
  download, refine, and delete.
- Dashboard: credits, subscription tier, and transaction history.
- Pricing: credit packs and subscription tiers.

## Links & resources

- Live app: https://www.vitex.org.nz/
- GitHub repository: https://github.com/ChanMeng666/easy-resume
- v1 API reference: https://github.com/ChanMeng666/easy-resume/blob/master/docs/api/v1.md
- Agent skill: https://www.vitex.org.nz/skill.md
- OpenAPI spec: https://www.vitex.org.nz/openapi.yaml
- License: MIT