{"openapi":"3.1.0","info":{"title":"Tiny CV Developer API","version":"1.0.0","description":"Create, validate, publish, and export Tiny CV resumes for users and agents.","x-guidance":"Agents can use bearer-token /api/v1 endpoints for project-owned workflows, or no-account paid /api/v1/paid endpoints with x402 or MPP. Use POST /api/v1/resumes/validate with quality_gate: \"publish\" before publish/payment. The headline is not the summary: keep the line after # name under 80 characters and put narrative positioning in ## Summary. For experience-like sections, use *Location, Remote, or website | Dates* on the italic line. Education may use date-only metadata; projects may omit metadata. Do not use inline bullet-dot lists; use separate - bullet lines. Bearer API keys are for durable projects, webhooks, and usage history. x402/MPP is for one-off agent execution with no account or API key. Before publishing or making a paid Agent Finish call, resolve validation errors, show the selected template, final markdown, unverified facts, and next action; ask for approval unless the user explicitly authorized autonomous publishing/payment. Use /api/v1/paid/agent-finish when an agent needs to turn resume markdown or JSON into a claimable hosted Tiny CV plus a queued PDF job. If a human wants to keep editing the markdown, return the editor_claim_url from Agent Finish, from paid create, or from bearer create/publish with return_edit_claim_url=true. Machine-payment calls do not include premium *.tiny.cv namespace ownership, Pro entitlements, or paid webhooks; a human Founder Pass is required for permanent premium URL identity."},"x-discovery":{"ownershipProofs":[]},"x-service-info":{"categories":["developer-tools","media"]},"servers":[{"url":"https://tiny.cv"},{"url":"https://tinycv.app"},{"url":"http://localhost:3000"}],"components":{"securitySchemes":{"bearerAuth":{"scheme":"bearer","type":"http"},"developerApiKey":{"description":"Tiny CV developer API key. Send as `Authorization: Bearer <api_key>`.","in":"header","name":"Authorization","type":"apiKey"},"bootstrapSecret":{"in":"header","name":"x-tinycv-bootstrap-secret","type":"apiKey"},"workerSecret":{"in":"header","name":"x-tinycv-worker-secret","type":"apiKey"}},"schemas":{"ApiError":{"properties":{"error":{"properties":{"code":{"type":"string"},"details":{"type":"object"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"],"type":"object"}},"required":["error"],"type":"object"},"ApiResumeRecord":{"properties":{"client_reference_id":{"type":["string","null"]},"created_at":{"format":"date-time","type":"string"},"editor_claim_url":{"type":"string"},"external_resume_id":{"type":["string","null"]},"input_format":{"enum":["json","markdown"],"type":"string"},"markdown":{"type":"string"},"pdf_url":{"type":["string","null"]},"public_url":{"type":["string","null"]},"published_at":{"type":["string","null"]},"resume_id":{"type":"string"},"status":{"enum":["draft","published"],"type":"string"},"template_key":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["client_reference_id","created_at","external_resume_id","input_format","markdown","pdf_url","public_url","published_at","resume_id","status","template_key","title","updated_at"],"type":"object"},"CreateResumeRequest":{"oneOf":[{"properties":{"client_reference_id":{"type":"string"},"external_resume_id":{"type":"string"},"input_format":{"const":"markdown"},"markdown":{"type":"string"},"return_edit_claim_url":{"type":"boolean"},"style_overrides":{"type":"object"},"template_key":{"type":"string"},"title":{"type":"string"},"webhook_url":{"format":"uri","type":"string"}},"required":["input_format","markdown"],"type":"object"},{"properties":{"client_reference_id":{"type":"string"},"external_resume_id":{"type":"string"},"input_format":{"const":"json"},"resume":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{"contact":{"items":{"additionalProperties":false,"properties":{"href":{"type":"string"},"kind":{"enum":["email","phone","location","url","linkedin","github","x","text"],"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},"type":"array"},"headline":{"type":"string"},"name":{"type":"string"},"sections":{"items":{"oneOf":[{"additionalProperties":false,"properties":{"paragraphs":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"summary","type":"string"}},"required":["type","paragraphs"],"type":"object"},{"additionalProperties":false,"properties":{"entries":{"items":{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"type":"array"},"meta_left":{"type":"string"},"meta_right":{"type":"string"},"paragraphs":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"title_extras":{"items":{"type":"string"},"type":"array"}},"required":["title"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"entries","type":"string"}},"required":["type","title","entries"],"type":"object"},{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"bullets","type":"string"}},"required":["type","title","bullets"],"type":"object"},{"additionalProperties":false,"properties":{"groups":{"items":{"additionalProperties":false,"properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"skills","type":"string"}},"required":["type","groups"],"type":"object"}]},"minItems":1,"type":"array"}},"required":["name","sections"],"type":"object"},"return_edit_claim_url":{"type":"boolean"},"style":{"type":"object"},"template_key":{"type":"string"},"title":{"type":"string"},"webhook_url":{"format":"uri","type":"string"}},"required":["input_format","resume"],"type":"object"}]},"ValidateResumeRequest":{"oneOf":[{"properties":{"input_format":{"const":"markdown"},"markdown":{"type":"string"},"quality_gate":{"enum":["draft","publish"],"type":"string"},"style_overrides":{"type":"object"},"template_key":{"type":"string"}},"required":["input_format","markdown"],"type":"object"},{"properties":{"input_format":{"const":"json"},"quality_gate":{"enum":["draft","publish"],"type":"string"},"resume":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{"contact":{"items":{"additionalProperties":false,"properties":{"href":{"type":"string"},"kind":{"enum":["email","phone","location","url","linkedin","github","x","text"],"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},"type":"array"},"headline":{"type":"string"},"name":{"type":"string"},"sections":{"items":{"oneOf":[{"additionalProperties":false,"properties":{"paragraphs":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"summary","type":"string"}},"required":["type","paragraphs"],"type":"object"},{"additionalProperties":false,"properties":{"entries":{"items":{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"type":"array"},"meta_left":{"type":"string"},"meta_right":{"type":"string"},"paragraphs":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"title_extras":{"items":{"type":"string"},"type":"array"}},"required":["title"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"entries","type":"string"}},"required":["type","title","entries"],"type":"object"},{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"bullets","type":"string"}},"required":["type","title","bullets"],"type":"object"},{"additionalProperties":false,"properties":{"groups":{"items":{"additionalProperties":false,"properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"skills","type":"string"}},"required":["type","groups"],"type":"object"}]},"minItems":1,"type":"array"}},"required":["name","sections"],"type":"object"},"style":{"type":"object"},"template_key":{"type":"string"}},"required":["input_format","resume"],"type":"object"}]},"ValidateResumeResponse":{"properties":{"errors":{"items":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}},"required":["code","message"],"type":"object"},"type":"array"},"inferred_template_key":{"type":["string","null"]},"normalized_markdown":{"type":"string"},"publish_errors":{"items":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}},"required":["code","message"],"type":"object"},"type":"array"},"publish_ready":{"type":"boolean"},"quality_warnings":{"items":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}},"required":["code","message"],"type":"object"},"type":"array"},"valid":{"type":"boolean"},"warnings":{"items":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}},"required":["code","message"],"type":"object"},"type":"array"}},"required":["errors","inferred_template_key","publish_errors","publish_ready","quality_warnings","valid","warnings"],"type":"object"},"PaidCreatePdfJobRequest":{"additionalProperties":false,"properties":{},"type":"object"},"PaidCreateResumeRequest":{"oneOf":[{"additionalProperties":false,"properties":{"client_reference_id":{"type":"string"},"input_format":{"const":"markdown"},"markdown":{"type":"string"},"return_edit_claim_url":{"type":"boolean"},"style_overrides":{"type":"object"},"template_key":{"type":"string"},"title":{"type":"string"}},"required":["input_format","markdown"],"type":"object"},{"additionalProperties":false,"properties":{"client_reference_id":{"type":"string"},"input_format":{"const":"json"},"resume":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{"contact":{"items":{"additionalProperties":false,"properties":{"href":{"type":"string"},"kind":{"enum":["email","phone","location","url","linkedin","github","x","text"],"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},"type":"array"},"headline":{"type":"string"},"name":{"type":"string"},"sections":{"items":{"oneOf":[{"additionalProperties":false,"properties":{"paragraphs":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"summary","type":"string"}},"required":["type","paragraphs"],"type":"object"},{"additionalProperties":false,"properties":{"entries":{"items":{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"type":"array"},"meta_left":{"type":"string"},"meta_right":{"type":"string"},"paragraphs":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"title_extras":{"items":{"type":"string"},"type":"array"}},"required":["title"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"entries","type":"string"}},"required":["type","title","entries"],"type":"object"},{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"bullets","type":"string"}},"required":["type","title","bullets"],"type":"object"},{"additionalProperties":false,"properties":{"groups":{"items":{"additionalProperties":false,"properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"skills","type":"string"}},"required":["type","groups"],"type":"object"}]},"minItems":1,"type":"array"}},"required":["name","sections"],"type":"object"},"return_edit_claim_url":{"type":"boolean"},"style":{"type":"object"},"template_key":{"type":"string"},"title":{"type":"string"}},"required":["input_format","resume"],"type":"object"}]},"PaidCreateResumeResponse":{"properties":{"payment":{"properties":{"benefits":{"items":{"type":"string"},"type":"array"},"charged_amount_usd":{"type":"string"},"premium_url_included":{"const":false},"product":{"enum":["agent_finish","agent_publish","pdf_export"],"type":"string"},"protocols_supported":{"items":{"enum":["x402","mpp"],"type":"string"},"type":"array"}},"required":["benefits","charged_amount_usd","premium_url_included","product","protocols_supported"],"type":"object"},"resume":{"properties":{"client_reference_id":{"type":["string","null"]},"created_at":{"format":"date-time","type":"string"},"editor_claim_url":{"type":"string"},"external_resume_id":{"type":["string","null"]},"input_format":{"enum":["json","markdown"],"type":"string"},"markdown":{"type":"string"},"pdf_url":{"type":["string","null"]},"public_url":{"type":["string","null"]},"published_at":{"type":["string","null"]},"resume_id":{"type":"string"},"status":{"enum":["draft","published"],"type":"string"},"template_key":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["client_reference_id","created_at","external_resume_id","input_format","markdown","pdf_url","public_url","published_at","resume_id","status","template_key","title","updated_at"],"type":"object"}},"required":["payment","resume"],"type":"object"},"PaidAgentFinishResponse":{"properties":{"claim":{"properties":{"editor_claim_url":{"type":["string","null"]},"founder_pass_required_for_premium_url":{"const":true},"premium_url_included":{"const":false}},"required":["editor_claim_url","founder_pass_required_for_premium_url","premium_url_included"],"type":"object"},"payment":{"properties":{"benefits":{"items":{"type":"string"},"type":"array"},"charged_amount_usd":{"type":"string"},"premium_url_included":{"const":false},"product":{"enum":["agent_finish","agent_publish","pdf_export"],"type":"string"},"protocols_supported":{"items":{"enum":["x402","mpp"],"type":"string"},"type":"array"}},"required":["benefits","charged_amount_usd","premium_url_included","product","protocols_supported"],"type":"object"},"pdf_job":{"properties":{"completed_at":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"job_id":{"type":"string"},"pdf_url":{"type":["string","null"]},"requested_at":{"format":"date-time","type":"string"},"resume_id":{"type":"string"},"status":{"enum":["cancelled","completed","failed","processing","queued"],"type":"string"}},"required":["completed_at","error_code","error_message","job_id","pdf_url","requested_at","resume_id","status"],"type":"object"},"resume":{"properties":{"client_reference_id":{"type":["string","null"]},"created_at":{"format":"date-time","type":"string"},"editor_claim_url":{"type":"string"},"external_resume_id":{"type":["string","null"]},"input_format":{"enum":["json","markdown"],"type":"string"},"markdown":{"type":"string"},"pdf_url":{"type":["string","null"]},"public_url":{"type":["string","null"]},"published_at":{"type":["string","null"]},"resume_id":{"type":"string"},"status":{"enum":["draft","published"],"type":"string"},"template_key":{"type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["client_reference_id","created_at","external_resume_id","input_format","markdown","pdf_url","public_url","published_at","resume_id","status","template_key","title","updated_at"],"type":"object"}},"required":["claim","payment","pdf_job","resume"],"type":"object"},"PdfJobResponse":{"properties":{"completed_at":{"type":["string","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"job_id":{"type":"string"},"pdf_url":{"type":["string","null"]},"requested_at":{"format":"date-time","type":"string"},"resume_id":{"type":"string"},"status":{"enum":["cancelled","completed","failed","processing","queued"],"type":"string"}},"required":["completed_at","error_code","error_message","job_id","pdf_url","requested_at","resume_id","status"],"type":"object"},"ResumeJsonInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{"contact":{"items":{"additionalProperties":false,"properties":{"href":{"type":"string"},"kind":{"enum":["email","phone","location","url","linkedin","github","x","text"],"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},"type":"array"},"headline":{"type":"string"},"name":{"type":"string"},"sections":{"items":{"oneOf":[{"additionalProperties":false,"properties":{"paragraphs":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"summary","type":"string"}},"required":["type","paragraphs"],"type":"object"},{"additionalProperties":false,"properties":{"entries":{"items":{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"type":"array"},"meta_left":{"type":"string"},"meta_right":{"type":"string"},"paragraphs":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"title_extras":{"items":{"type":"string"},"type":"array"}},"required":["title"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"entries","type":"string"}},"required":["type","title","entries"],"type":"object"},{"additionalProperties":false,"properties":{"bullets":{"items":{"type":"string"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"bullets","type":"string"}},"required":["type","title","bullets"],"type":"object"},{"additionalProperties":false,"properties":{"groups":{"items":{"additionalProperties":false,"properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"type":"object"},"minItems":1,"type":"array"},"title":{"type":"string"},"type":{"const":"skills","type":"string"}},"required":["type","groups"],"type":"object"}]},"minItems":1,"type":"array"}},"required":["name","sections"],"type":"object"}}},"paths":{"/api/v1/paid/resumes":{"post":{"description":"No-account machine-payment endpoint that creates, publishes, and returns a standard public Tiny CV resume URL. The response includes a claimable edit link by default, but does not reserve a premium *.tiny.cv URL. Invalid publish-ready markdown returns 400 before any 402 payment challenge. Experience-like sections should use *Location, Remote, or website | Dates* on the italic metadata line.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaidCreateResumeRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaidCreateResumeResponse"}}},"description":"Created and published paid resume"},"400":{"description":"Invalid input, missing idempotency key, or invalid publish-ready markdown. Example codes: missing_summary, headline_too_long, inline_bullet_separator, experience_entry_date_in_wrong_slot."},"402":{"description":"Payment required. Retry with x402 PAYMENT-SIGNATURE or MPP Authorization: Payment.","headers":{"Cache-Control":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}},"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited. Retry after the seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Machine payments are disabled/not configured, or browser fit measurement is unavailable. Example code: browser_fit_unavailable."}},"x-payment-info":{"price":{"amount":"0.100000","currency":"USD","mode":"fixed"},"protocols":[{"x402":{}},{"mpp":{"currency":"USD","intent":"charge","method":"tempo"}}]}}},"/api/v1/paid/agent-finish":{"post":{"description":"No-account x402/MPP endpoint for agents that need a finished Tiny CV package in one paid operation: standard hosted URL, claimable edit link, queued PDF job, and payment receipt. Agent Finish always creates a claim link. It does not include premium *.tiny.cv namespace ownership. Invalid publish-ready markdown returns 400 before any 402 payment challenge. Experience-like sections should use *Location, Remote, or website | Dates* on the italic metadata line.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaidCreateResumeRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaidAgentFinishResponse"}}},"description":"Agent Finish package queued"},"400":{"description":"Invalid input, missing idempotency key, or invalid publish-ready markdown. Example codes: missing_summary, headline_too_long, inline_bullet_separator, experience_entry_date_in_wrong_slot."},"402":{"description":"Payment required. Retry with x402 PAYMENT-SIGNATURE or MPP Authorization: Payment.","headers":{"Cache-Control":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}},"WWW-Authenticate":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited. Retry after the seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Machine payments are disabled/not configured, or browser fit measurement is unavailable. Example code: browser_fit_unavailable."}},"x-payment-info":{"price":{"amount":"0.250000","currency":"USD","mode":"fixed"},"protocols":[{"x402":{}},{"mpp":{"currency":"USD","intent":"charge","method":"tempo"}}]}}},"/api/v1/paid/resumes/{resume_id}/pdf-jobs":{"post":{"description":"No-account machine-payment endpoint that queues a PDF job for a paid, published resume.","parameters":[{"in":"path","name":"resume_id","required":true,"schema":{"type":"string"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaidCreatePdfJobRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfJobResponse"}}},"description":"Paid PDF job queued"},"400":{"description":"Invalid input or missing idempotency key"},"402":{"description":"Payment required. Retry with x402 PAYMENT-SIGNATURE or MPP Authorization: Payment.","headers":{"Cache-Control":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}},"WWW-Authenticate":{"schema":{"type":"string"}}}},"404":{"description":"Resume not found or not owned by the machine-payment project"},"409":{"description":"Resume is not published"},"429":{"description":"Rate limited. Retry after the seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Machine payments are disabled or not configured"}},"x-payment-info":{"price":{"amount":"0.250000","currency":"USD","mode":"fixed"},"protocols":[{"x402":{}},{"mpp":{"currency":"USD","intent":"charge","method":"tempo"}}]}}}}}