# Tiny CV

> Agent-friendly docs for the Tiny CV developer platform.

## Core Docs

- [Documentation](https://tiny.cv/documentation): human-first overview with live playground.
- [OpenAPI 3.1](https://tiny.cv/api/v1/openapi.json): machine-readable API schema.
- [Markdown guide](https://tiny.cv/api/v1/spec/markdown): canonical Tiny CV markdown format.
- [JSON schema](https://tiny.cv/api/v1/spec/json-schema): structured resume input.
- [MCP endpoint](https://tiny.cv/api/v1/mcp): remote MCP JSON-RPC endpoint.

## Agent Resources

- [llms-full.txt](https://tiny.cv/llms-full.txt): single-file Tiny CV docs bundle.
- [Templates](https://tiny.cv/api/v1/templates): list built-in templates.
- [MCP tools + resources](https://tiny.cv/api/v1/mcp): tools, prompts, and resources for agents.

## Endpoint Reference

### Bootstrap a project (protected)

- Method: POST
- Path: https://tiny.cv/api/v1/projects/bootstrap
- Auth: bootstrap-secret
- Idempotent: false

Protected bootstrap flow for managed or internal provisioning. The public documentation experience is the easiest way to create your first project and API key.

```bash
curl -X POST http://localhost:3000/api/v1/projects/bootstrap \
  -H "x-tinycv-bootstrap-secret: $TINYCV_PLATFORM_BOOTSTRAP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "api_key_label": "Production Agent Key",
  "name": "Acme Recruiting Agent",
  "slug": "acme-agent"
}'
```

### List templates

- Method: GET
- Path: https://tiny.cv/api/v1/templates
- Auth: none
- Idempotent: false

List the built-in Tiny CV starter templates.

```bash
curl -X GET http://localhost:3000/api/v1/templates
```

### Fetch a single template

- Method: GET
- Path: https://tiny.cv/api/v1/templates/{key}
- Auth: none
- Idempotent: false

Fetch one template and its starter markdown.

```bash
curl -X GET http://localhost:3000/api/v1/templates/designer
```

### Get markdown guide

- Method: GET
- Path: https://tiny.cv/api/v1/spec/markdown
- Auth: none
- Idempotent: false

Fetch the canonical markdown guide for Tiny CV resumes.

```bash
curl -X GET http://localhost:3000/api/v1/spec/markdown
```

### Get JSON schema

- Method: GET
- Path: https://tiny.cv/api/v1/spec/json-schema
- Auth: none
- Idempotent: false

Fetch JSON Schema for structured resume input.

```bash
curl -X GET http://localhost:3000/api/v1/spec/json-schema
```

### Validate input

- Method: POST
- Path: https://tiny.cv/api/v1/resumes/validate
- Auth: bearer
- Idempotent: false

Validate markdown or JSON input without persisting anything. Best used before draft creation.

```bash
curl -X POST http://localhost:3000/api/v1/resumes/validate \
  -H "Authorization: Bearer $TINYCV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_format": "json",
  "resume": {
    "contact": [
      {
        "kind": "email",
        "value": "maya@example.com"
      }
    ],
    "headline": "Product Designer",
    "name": "Maya Chen",
    "sections": [
      {
        "paragraphs": [
          "Designer with strong systems and product instincts."
        ],
        "type": "summary"
      }
    ]
  },
  "style": {
    "accentTone": "plum",
    "stylePreset": "creative"
  },
  "template_key": "designer"
}'
```

### Create a draft

- Method: POST
- Path: https://tiny.cv/api/v1/resumes
- Auth: bearer
- Idempotent: true

Create a Tiny CV draft from markdown or JSON. Returns the canonical markdown that Tiny CV stored. Send Idempotency-Key so retries do not create duplicates.

```bash
curl -X POST http://localhost:3000/api/v1/resumes \
  -H "Authorization: Bearer $TINYCV_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "input_format": "markdown",
  "markdown": "# Alex Morgan\nFounder & Product Engineer\nSan Francisco, CA | [alex@example.com](mailto:alex@example.com)\n\n## Summary\nProduct-minded builder.\n",
  "return_edit_claim_url": true,
  "template_key": "founder",
  "title": "Alex Morgan Resume",
  "webhook_url": "https://example.com/tinycv/webhooks"
}'
```

### Get a resume

- Method: GET
- Path: https://tiny.cv/api/v1/resumes/{resume_id}
- Auth: bearer
- Idempotent: false

Read the current state of one draft or published resume.

```bash
curl -X GET http://localhost:3000/api/v1/resumes/res_123 \
  -H "Authorization: Bearer $TINYCV_API_KEY"
```

### Update a draft

- Method: PATCH
- Path: https://tiny.cv/api/v1/resumes/{resume_id}
- Auth: bearer
- Idempotent: true

Update an existing draft using the same input contract as draft creation.

```bash
curl -X PATCH http://localhost:3000/api/v1/resumes/res_123 \
  -H "Authorization: Bearer $TINYCV_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "input_format": "json",
  "resume": {
    "headline": "Founder & Product Engineer",
    "name": "Alex Morgan",
    "sections": [
      {
        "paragraphs": [
          "Founder who ships products and owns the narrative."
        ],
        "type": "summary"
      }
    ]
  },
  "style": {
    "density": "compact"
  }
}'
```

### Publish a resume

- Method: POST
- Path: https://tiny.cv/api/v1/resumes/{resume_id}/publish
- Auth: bearer
- Idempotent: true

Publish the current draft snapshot and get the public URL. Send Idempotency-Key so retries return the same publish result.

```bash
curl -X POST http://localhost:3000/api/v1/resumes/res_123/publish \
  -H "Authorization: Bearer $TINYCV_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "return_edit_claim_url": true,
  "webhook_url": "https://example.com/tinycv/webhooks"
}'
```

### Queue a PDF job

- Method: POST
- Path: https://tiny.cv/api/v1/resumes/{resume_id}/pdf-jobs
- Auth: bearer
- Idempotent: true

Queue durable PDF generation for a published resume. Returns a pollable job immediately; webhooks are delivered from the worker outbox.

```bash
curl -X POST http://localhost:3000/api/v1/resumes/res_123/pdf-jobs \
  -H "Authorization: Bearer $TINYCV_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "webhook_url": "https://example.com/tinycv/webhooks"
}'
```

### Get PDF job status

- Method: GET
- Path: https://tiny.cv/api/v1/pdf-jobs/{job_id}
- Auth: bearer
- Idempotent: false

Check PDF generation status and get a signed PDF URL once the artifact is ready.

```bash
curl -X GET http://localhost:3000/api/v1/pdf-jobs/job_123 \
  -H "Authorization: Bearer $TINYCV_API_KEY"
```

### Consume an edit claim

- Method: POST
- Path: https://tiny.cv/api/v1/edit-claims/{claim_id}/consume
- Auth: none
- Idempotent: false

Consume a one-time edit claim and attach the resume into the current Tiny CV workspace.

```bash
curl -X POST http://localhost:3000/api/v1/edit-claims/claim_123/consume \
  -H "Content-Type: application/json" \
  -d '{
  "token": "tcv_claim_xxxxxxxxxxxxxxxxx"
}'
```

### Call the MCP server

- Method: POST
- Path: https://tiny.cv/api/v1/mcp
- Auth: bearer
- Idempotent: false

Remote MCP endpoint for agent tools, resources, and prompts over JSON-RPC. Mutating tools use JSON-RPC ids as idempotency keys when no Idempotency-Key header is present.

```bash
curl -X POST http://localhost:3000/api/v1/mcp \
  -H "Authorization: Bearer $TINYCV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {}
}'
```

## Tiny CV Markdown Guide

# Tiny CV Markdown Guide

Tiny CV resumes are plain markdown with optional YAML frontmatter.

## File shape

```md
---
stylePreset: editorial
accentTone: forest
density: standard
headerAlignment: left
contactStyle: compact
pageMargin: 1
showHeaderDivider: false
showSectionDivider: true
pageSize: letter
---

# Alex Morgan
Founder & Product Engineer
San Francisco, CA | [alex@example.com](mailto:alex@example.com) | [linkedin.com/in/alexmorgan](https://linkedin.com/in/alexmorgan)

## Summary
Product-minded builder with experience across product, engineering, and go-to-market.

## Experience
### Founder | Meridian Labs
*Remote | 2023 - Present*
- Built the first product surface and shipped the company to revenue.

## Skills
Languages: TypeScript, Python, SQL
Frameworks: React, Next.js, Node.js
```

## Rules

- The first `#` heading is the candidate name.
- The next non-empty line is treated as the headline unless it looks like contact info.
- Contact info can be plain text or markdown links and is usually separated with `|`.
- Top-level sections use `##`.
- Resume entries inside sections use `###`.
- Entry metadata goes on the next italic line, usually in the form `*Location | Dates*`.
- Bullets use `-` or `*`.
- A `Skills` section should use `Label: value` rows.

## Frontmatter options

- `stylePreset`: classic | minimal | editorial | executive | technical | creative
- `accentTone`: forest | slate | navy | plum | claret
- `density`: comfortable | standard | compact
- `headerAlignment`: left | center
- `contactStyle`: classic | compact | web-icons
- `pageMargin`: number, typically 0.65 to 1.0
- `showHeaderDivider`: boolean
- `showSectionDivider`: boolean
- `pageSize`: letter | legal

## Entry pattern

```md
### Role | Company
*Remote | 2022 - Present*
- Outcome-focused bullet
- Another bullet
```

## Summary / paragraph pattern

```md
## Summary
One or more paragraphs can appear here.

Each blank line becomes a new paragraph.
```

## Skills pattern

```md
## Skills
Languages: TypeScript, Python, SQL
Frameworks: React, Next.js, Node.js
Platforms: Vercel, AWS, Postgres
```


## Tiny CV Agent Cookbook

# Tiny CV Agent Cookbook

## Happy path

1. Choose a template.
2. Fetch the markdown guide or JSON schema.
3. Validate the payload.
4. Create a draft.
5. Publish the draft.
6. Request a PDF if needed.

## Recommended workflow

- Use markdown if your agent already produces polished text.
- Use JSON if your agent starts from structured profile data.
- Send an `Idempotency-Key` on create, update, publish, and PDF job requests.
- Keep the public URL as the default output for end users.
- Only request an edit claim URL when the user should continue editing in Tiny CV.
- If a request returns `429`, wait for the `Retry-After` header before retrying.

## Example: JSON to published resume

1. `GET /api/v1/spec/json-schema`
2. `POST /api/v1/resumes/validate`
3. `POST /api/v1/resumes`
4. `POST /api/v1/resumes/:resume_id/publish`
5. `POST /api/v1/resumes/:resume_id/pdf-jobs`
6. `GET /api/v1/pdf-jobs/:job_id`