Cv Builder

CV Builder — Create CVs via API

Create a CV with a permanent URL at talent.de. The user chooses their personal URL slug and template design via a review page. CVs are permanent — URLs never expire.

Agent Guidelines

HITL is required. You MUST include either "prefer_hitl": true (human review) or "skip_hitl": true (direct creation). Omitting both returns a 400 error. If a human is present, ALWAYS use "prefer_hitl": true — this lets the user choose their URL slug, pick a template, review the data, and approve before publishing. Use "skip_hitl": true only for automated pipelines with no human in the loop.

Data principle: Only use data the requestor has explicitly provided or approved in this conversation. Do not extract personal information from unrelated system contexts or other sessions.

Before sending: Present a brief summary to the requestor — name, title, email — and ask "Send it? Or should I change anything?"

Claim token: Treat like a password. Share only with the requestor — anyone with the token can claim CV ownership. Never share with third parties.

User Communication

What to say at each step

Quick Start

1. Collect: name, title, email (minimum 4 fields)
2. POST /api/agent/cv-simple with "prefer_hitl": true and the data
3. Present the review_url to the user (they pick slug, template, review data)
4. Poll poll_url for completion, continue through steps
5. After final approval: present the live CV URL and claim token

Example (with HITL — recommended)

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "prefer_hitl": true,
  "cv_data": {
    "firstName": "Alex",
    "lastName": "Johnson",
    "title": "Software Engineer",
    "email": "alex@example.com"
  }
}

Response (202 — human review required):

{
  "status": "human_input_required",
  "message": "Please confirm: is this CV for you?",
  "hitl": {
    "case_id": "review_a7f3b2c8d9e1f0g4",
    "review_url": "https://www.talent.de/en/hitl/review/review_a7f3b2c8d9e1f0g4?token=abc123...",
    "poll_url": "https://www.talent.de/api/hitl/cases/review_a7f3b2c8d9e1f0g4/status",
    "type": "confirmation",
    "inline_actions": ["confirm", "cancel"],
    "timeout": "24h"
  }
}

Present the review URL to the user:

I've prepared your CV. Please review and make your choices here: Review your CV You'll pick your personal URL slug, template design, and approve the final result.

Then poll poll_url until completed, and continue through steps with hitl_continue_case_id. After all steps (confirmation, data review, slug selection, template selection, approval), the final POST returns 201 with the live URL.

Full HITL protocol with all steps, inline submit, edit cycles, and escalation: reference/hitl.md

HITL Multi-Step Flow

The user goes through up to 5 review steps. The agent loops: present review URL, poll, continue.

Step 1: Confirmation  →  "For whom is this CV?"
Step 2: Data Review   →  "Are these details correct?"
Step 3: Slug          →  Human picks personal URL slug (e.g. pro, dev, 007)
Step 4: Template      →  Human picks template design
Step 5: Approval      →  Human reviews final CV draft

Each step returns 202. After the user decides, continue:

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "prefer_hitl": true,
  "hitl_continue_case_id": "review_a7f3b2c8d9e1f0g4",
  "cv_data": { ... }
}

Steps are skipped when you already provide the value:

• Include slug → slug selection step is skipped
• Include template_id → template selection step is skipped
• Include both → only confirmation, data review, and approval remain

After the final approval step, submit with hitl_approved_case_id to publish:

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "hitl_approved_case_id": "review_final_case_id"
}

Response (201):

{
  "success": true,
  "url": "https://www.talent.de/dev/alex-johnson",
  "cv_id": "cv_abc123",
  "claim_token": "claim_xyz789",
  "template_id": "007"
}

Present the result:

Your CV is live: talent.de/dev/alex-johnson

To claim ownership, visit: talent.de/claim/claim_xyz789 Keep this token safe — it never expires.

Direct Creation (No Human Present)

For fully automated pipelines, batch operations, or when the user explicitly says "just create it" — set "skip_hitl": true:

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "skip_hitl": true,
  "cv_data": {
    "firstName": "Alex",
    "lastName": "Johnson",
    "title": "Software Engineer",
    "email": "alex@example.com"
  }
}

Response (201):

{
  "success": true,
  "url": "https://www.talent.de/pro/alex-johnson",
  "cv_id": "cv_abc123",
  "claim_token": "claim_xyz789",
  "template_id": "018",
  "hitl_skipped": true,
  "auto_fixes": []
}

In direct mode, the server auto-assigns slug (pro by default) and template (018 Amber Horizon). The user has no choice. Use this only when no human needs to review.

You MUST choose one: "prefer_hitl": true or "skip_hitl": true. Omitting both returns a 400 error.

All fields beyond the 4 required ones are optional. Omit what you don't have — don't send empty arrays.