{"openapi":"3.1.0","servers":[{"url":"https://bragfile.dev","description":"bragfile API"}],"info":{"title":"bragfile API","version":"0.1.0","description":"git for your career. Achievements are commits, resumes are build artifacts, LLMs are the compiler — bragfile is the repo. This API is designed for GenAI agents (ChatGPT Actions, Claude via MCP, anything that speaks HTTP): store and retrieve achievements in extreme chronological detail, rank them against a target role, pull curated templates with built-in LLM guidance, and render the final artifact. Agents: send an X-Agent header so provenance lands in the ledger. Pricing: free plan holds 5 achievements; pro ($3.99/month) is unlimited — a 402 from POST /v1/achievements includes the upgradeUrl to hand to the human. MCP clients: the same tools are served over streamable HTTP at /mcp (Bearer auth)."},"tags":[{"name":"achievements","description":"The career ledger"},{"name":"tailor","description":"Ranked retrieval against a target role"},{"name":"templates","description":"Curated templates with LLM guidance"},{"name":"resumes","description":"Build artifacts"},{"name":"users","description":"Onboarding and identity"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your bragfile API key (brag_...)"}},"schemas":{},"parameters":{}},"paths":{"/v1/users":{"post":{"tags":["users"],"summary":"Create a user (onboarding). Returns the API key exactly once.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","minLength":2},"displayName":{"type":"string","minLength":1},"headline":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"links":{"type":"array","items":{"type":"string"}}},"required":["handle","displayName"]}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"headline":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"links":{"type":"array","items":{"type":"string"}},"plan":{"type":"string","enum":["free","pro"],"description":"free = 5 achievements; pro = unlimited"},"apiKey":{"type":"string"}},"required":["id","handle","displayName","headline","email","location","links","plan","apiKey"]}}}},"409":{"description":"handle taken","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/me":{"get":{"tags":["users"],"summary":"Who am I (includes plan + ledger usage)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"headline":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"links":{"type":"array","items":{"type":"string"}},"plan":{"type":"string","enum":["free","pro"],"description":"free = 5 achievements; pro = unlimited"},"usage":{"type":"object","properties":{"achievements":{"type":"number"},"limit":{"type":"number","nullable":true}},"required":["achievements","limit"]}},"required":["id","handle","displayName","headline","email","location","links","plan","usage"]}}}}}},"patch":{"tags":["users"],"summary":"Update profile. If the account was created one-click from an AI, set the real name here before compiling resumes.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1},"headline":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"links":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"headline":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"links":{"type":"array","items":{"type":"string"}},"plan":{"type":"string","enum":["free","pro"],"description":"free = 5 achievements; pro = unlimited"}},"required":["id","handle","displayName","headline","email","location","links","plan"]}}}}}}},"/v1/achievements":{"post":{"tags":["achievements"],"summary":"Log an achievement (a commit to the career ledger). Free plan holds 5; pro ($3.99/month) is unlimited.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"}},"required":["title","occurredOn","action","result"]}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"},"id":{"type":"string"},"userId":{"type":"string"},"source":{"type":"string","description":"Who logged it: \"human\", \"mcp:<client>\", or \"api:<agent>\""},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["title","occurredOn","action","result","id","userId","source","createdAt","updatedAt"]}}}},"402":{"description":"free ledger full — send the human the upgradeUrl","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"upgradeUrl":{"type":"string"},"guidance":{"type":"string"}},"required":["error","upgradeUrl","guidance"]}}}}}},"get":{"tags":["achievements"],"summary":"List/search achievements","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"skill","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tag","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"order","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"},"id":{"type":"string"},"userId":{"type":"string"},"source":{"type":"string","description":"Who logged it: \"human\", \"mcp:<client>\", or \"api:<agent>\""},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["title","occurredOn","action","result","id","userId","source","createdAt","updatedAt"]}}}}}}}},"/v1/achievements/timeline":{"get":{"tags":["achievements"],"summary":"Chronological timeline grouped by month","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"achievements":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"},"id":{"type":"string"},"userId":{"type":"string"},"source":{"type":"string","description":"Who logged it: \"human\", \"mcp:<client>\", or \"api:<agent>\""},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["title","occurredOn","action","result","id","userId","source","createdAt","updatedAt"]}}},"required":["period","achievements"]}}}}}}}},"/v1/achievements/{id}":{"get":{"tags":["achievements"],"summary":"Get one achievement","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"},"id":{"type":"string"},"userId":{"type":"string"},"source":{"type":"string","description":"Who logged it: \"human\", \"mcp:<client>\", or \"api:<agent>\""},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["title","occurredOn","action","result","id","userId","source","createdAt","updatedAt"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"patch":{"tags":["achievements"],"summary":"Update an achievement","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"},"id":{"type":"string"},"userId":{"type":"string"},"source":{"type":"string","description":"Who logged it: \"human\", \"mcp:<client>\", or \"api:<agent>\""},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["title","occurredOn","action","result","id","userId","source","createdAt","updatedAt"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"tags":["achievements"],"summary":"Delete an achievement","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/tailor":{"post":{"tags":["tailor"],"summary":"Rank the ledger against a target role. Retrieval + gap analysis; you do the writing.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetRole":{"type":"string","minLength":2,"description":"The role being applied for, e.g. \"Staff Platform Engineer\""},"jobDescription":{"type":"string","description":"Paste the job ad for much better ranking"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":12}},"required":["targetRole"]}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ranked":{"type":"array","items":{"type":"object","properties":{"achievement":{"type":"object","properties":{"title":{"type":"string","minLength":3,"description":"One-line headline of the win, written like a commit message"},"occurredOn":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it happened. YYYY-MM-DD or YYYY-MM"},"org":{"type":"string","description":"Company / team / community where it happened"},"role":{"type":"string","description":"Role held at the time"},"situation":{"type":"string","description":"Context: what was broken, at stake, or ambiguous"},"action":{"type":"string","minLength":1,"description":"What the person actually did — specific, first-person-verifiable"},"result":{"type":"string","minLength":1,"description":"What changed because of it — outcome, not activity"},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["label","value"]},"default":[],"description":"Quantified impact, e.g. {label: \"p95 latency\", value: \"-38%\"}"},"skills":{"type":"array","items":{"type":"string"},"default":[],"description":"Skills exercised, lowercase, e.g. [\"typescript\", \"incident response\"]"},"tags":{"type":"array","items":{"type":"string"},"default":[],"description":"Freeform tags, e.g. [\"leadership\", \"0-to-1\"]"},"links":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Evidence: PRs, launch posts, dashboards, press"},"id":{"type":"string"},"userId":{"type":"string"},"source":{"type":"string","description":"Who logged it: \"human\", \"mcp:<client>\", or \"api:<agent>\""},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["title","occurredOn","action","result","id","userId","source","createdAt","updatedAt"]},"score":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["achievement","score","reasons"]}},"gaps":{"type":"array","items":{"type":"string"}},"guidance":{"type":"string"}},"required":["ranked","gaps","guidance"]}}}}}}},"/v1/templates":{"get":{"tags":["templates"],"summary":"Curated resume templates, each with llmGuidance for the AI doing the writing","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"vibe":{"type":"string"},"bestFor":{"type":"string"},"llmGuidance":{"type":"string","description":"Global instructions for the LLM using this template"},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["header","summary","highlights","experience","skills","projects","education","custom"]},"guidance":{"type":"string","description":"Instructions for the LLM filling this section"},"maxItems":{"type":"number"}},"required":["id","title","kind","guidance"]}}},"required":["slug","name","vibe","bestFor","llmGuidance","sections"]}}}}}}}},"/v1/templates/{slug}":{"get":{"tags":["templates"],"summary":"Get one template","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"vibe":{"type":"string"},"bestFor":{"type":"string"},"llmGuidance":{"type":"string","description":"Global instructions for the LLM using this template"},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["header","summary","highlights","experience","skills","projects","education","custom"]},"guidance":{"type":"string","description":"Instructions for the LLM filling this section"},"maxItems":{"type":"number"}},"required":["id","title","kind","guidance"]}}},"required":["slug","name","vibe","bestFor","llmGuidance","sections"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/resumes":{"post":{"tags":["resumes"],"summary":"Create a resume draft: template skeleton auto-filled with tailored achievements","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetRole":{"type":"string","minLength":2},"targetCompany":{"type":"string"},"jobDescription":{"type":"string"},"templateSlug":{"type":"string"},"achievementIds":{"type":"array","items":{"type":"string"}}},"required":["targetRole","templateSlug"]}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"targetRole":{"type":"string"},"targetCompany":{"type":"string","nullable":true},"jobDescription":{"type":"string","nullable":true},"templateSlug":{"type":"string"},"content":{"type":"object","properties":{"header":{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"links":{"type":"array","items":{"type":"string"},"default":[]}},"required":["name"]},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["header","summary","highlights","experience","skills","projects","education","custom"]},"body":{"type":"string","description":"Prose body for summary-like sections"},"items":{"type":"array","items":{"type":"object","properties":{"achievementId":{"type":"string","nullable":true,"description":"Ledger provenance; null for hand-written items"},"heading":{"type":"string","description":"e.g. \"Senior Engineer — Acme (2023–2025)\" for experience groups"},"bullet":{"type":"string","description":"The tailored line as it should appear on the resume"}},"required":["achievementId","bullet"]},"default":[]}},"required":["id","title","kind"]}}},"required":["header","sections"]},"status":{"type":"string","enum":["draft","final"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","userId","targetRole","targetCompany","jobDescription","templateSlug","content","status","createdAt","updatedAt"]}}}},"400":{"description":"bad template","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"get":{"tags":["resumes"],"summary":"List resumes","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"targetRole":{"type":"string"},"targetCompany":{"type":"string","nullable":true},"jobDescription":{"type":"string","nullable":true},"templateSlug":{"type":"string"},"content":{"type":"object","properties":{"header":{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"links":{"type":"array","items":{"type":"string"},"default":[]}},"required":["name"]},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["header","summary","highlights","experience","skills","projects","education","custom"]},"body":{"type":"string","description":"Prose body for summary-like sections"},"items":{"type":"array","items":{"type":"object","properties":{"achievementId":{"type":"string","nullable":true,"description":"Ledger provenance; null for hand-written items"},"heading":{"type":"string","description":"e.g. \"Senior Engineer — Acme (2023–2025)\" for experience groups"},"bullet":{"type":"string","description":"The tailored line as it should appear on the resume"}},"required":["achievementId","bullet"]},"default":[]}},"required":["id","title","kind"]}}},"required":["header","sections"]},"status":{"type":"string","enum":["draft","final"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","userId","targetRole","targetCompany","jobDescription","templateSlug","content","status","createdAt","updatedAt"]}}}}}}}},"/v1/resumes/{id}":{"get":{"tags":["resumes"],"summary":"Get one resume (structured content, with achievement provenance)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"targetRole":{"type":"string"},"targetCompany":{"type":"string","nullable":true},"jobDescription":{"type":"string","nullable":true},"templateSlug":{"type":"string"},"content":{"type":"object","properties":{"header":{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"links":{"type":"array","items":{"type":"string"},"default":[]}},"required":["name"]},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["header","summary","highlights","experience","skills","projects","education","custom"]},"body":{"type":"string","description":"Prose body for summary-like sections"},"items":{"type":"array","items":{"type":"object","properties":{"achievementId":{"type":"string","nullable":true,"description":"Ledger provenance; null for hand-written items"},"heading":{"type":"string","description":"e.g. \"Senior Engineer — Acme (2023–2025)\" for experience groups"},"bullet":{"type":"string","description":"The tailored line as it should appear on the resume"}},"required":["achievementId","bullet"]},"default":[]}},"required":["id","title","kind"]}}},"required":["header","sections"]},"status":{"type":"string","enum":["draft","final"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","userId","targetRole","targetCompany","jobDescription","templateSlug","content","status","createdAt","updatedAt"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"patch":{"tags":["resumes"],"summary":"Update resume content/status — this is how the LLM writes its tailored bullets back","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"object","properties":{"header":{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"links":{"type":"array","items":{"type":"string"},"default":[]}},"required":["name"]},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["header","summary","highlights","experience","skills","projects","education","custom"]},"body":{"type":"string","description":"Prose body for summary-like sections"},"items":{"type":"array","items":{"type":"object","properties":{"achievementId":{"type":"string","nullable":true,"description":"Ledger provenance; null for hand-written items"},"heading":{"type":"string","description":"e.g. \"Senior Engineer — Acme (2023–2025)\" for experience groups"},"bullet":{"type":"string","description":"The tailored line as it should appear on the resume"}},"required":["achievementId","bullet"]},"default":[]}},"required":["id","title","kind"]}}},"required":["header","sections"]},"status":{"type":"string","enum":["draft","final"]},"targetRole":{"type":"string"},"targetCompany":{"type":"string"}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"targetRole":{"type":"string"},"targetCompany":{"type":"string","nullable":true},"jobDescription":{"type":"string","nullable":true},"templateSlug":{"type":"string"},"content":{"type":"object","properties":{"header":{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"links":{"type":"array","items":{"type":"string"},"default":[]}},"required":["name"]},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["header","summary","highlights","experience","skills","projects","education","custom"]},"body":{"type":"string","description":"Prose body for summary-like sections"},"items":{"type":"array","items":{"type":"object","properties":{"achievementId":{"type":"string","nullable":true,"description":"Ledger provenance; null for hand-written items"},"heading":{"type":"string","description":"e.g. \"Senior Engineer — Acme (2023–2025)\" for experience groups"},"bullet":{"type":"string","description":"The tailored line as it should appear on the resume"}},"required":["achievementId","bullet"]},"default":[]}},"required":["id","title","kind"]}}},"required":["header","sections"]},"status":{"type":"string","enum":["draft","final"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","userId","targetRole","targetCompany","jobDescription","templateSlug","content","status","createdAt","updatedAt"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"tags":["resumes"],"summary":"Delete a resume","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/resumes/{id}/render":{"get":{"tags":["resumes"],"summary":"Render the build artifact (markdown or print-ready html)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"rendered resume","content":{"text/plain":{"schema":{"type":"string"}},"text/html":{"schema":{"type":"string"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}