Developer/API

AI Gateway API

Aktueller Implementierungsstand. Diese API-Oberfläche kann sich kurzfristig ändern.

Vorläufige Doku: Endpunkt-Verträge, Header und Scope-Regeln können sich ändern.

Public-Modus: Verwaltete Chat-Endpunkte sind für die öffentliche API eingestellt. Nutze Lebenslauf-APIs und MCP-Lebenslauf-Tools.

Direkte PAT-API: Verwende dein persönliches API-Token direkt gegen denselben Host wie diese Seite. Produktions-Host: https://cv.doxai.ch

Basis-URL

https://cv.doxai.ch

Authentifizierung

Persönliche API-Tokens werden auf der Kontoseite erstellt und als Bearer-Token gesendet.

Authorization: Bearer <personal_api_token>

Token-Verwaltung öffnen

MCP-Server-URL

Für ChatGPT MCP / Remote-Clients verwende den folgenden streambaren HTTP-Endpunkt.

https://cv.doxai.ch/v1/mcp

Gemeinsame Header

Authorization: Bearer ...
x-request-id ist als Anfrage-Korrelationsheader optional
body.request_id ist für /v1/resume/jobs und resume.create_job erforderlich
x-ai-mode ist optional auf /v1/models, um die Flächen managed|api|mcp zu prüfen (Standard: api)
Öffentliche Managed-Chat-Routen sind eingestellt; x-ai-mode aktiviert sie nicht wieder

Token-Scopes

chat:run
resume:generate
tools:invoke
mcp:connect

Tier-Felder

Antworten enthalten sowohl interne Schlüssel für Logik als auch öffentliche Labels für die Anzeige.

tier = free|credits|subscription
tier_label = free|flex|pro
model.access = all|paid|subscription

`paid` ist hier eine interne Zugriffsklasse für nicht kostenlose Modelle. Sie entspricht Flex- und Pro-Berechtigung, nicht einem öffentlichen Plannamen.

System

GET/healthzpublic

Liveness check.

GET/readyzpublic

Readiness check (Supabase dependency).

GET/versionpublic

Gateway runtime/version info.

Auth-Inspektion

GET/v1/auth/mepublic

Resolve token principal and scopes.

GET/v1/auth/check/chatchat:run

Scope probe.

GET/v1/auth/check/resumeresume:generate

Scope probe.

GET/v1/auth/check/toolstools:invoke

Scope probe.

GET/v1/auth/check/mcpmcp:connect

Scope probe.

Modelle

GET/v1/modelschat:run

List models with per-user allow/deny decisions, protocol/origin metadata, surfaces, tier, and tier_label.

Use header x-ai-mode: managed|api|mcp (default: api) to inspect surface-specific availability.

Chat

POST/v1/chat/completionschat:run

Retired public managed chat route.

Returns 410 managed_chat_removed.

POST/v1/responseschat:run

Retired public managed responses route.

Returns 410 managed_chat_removed.

POST/v1/studio/chatchat:run

Internal studio bridge.

Internal service-only route; not part of the public integration surface.

Abrechnung

GET/v1/billing/statuschat:run

Current tier, tier_label, wallet balance, real-usage flag, and Pro allowance state.

subscription_chat_allowance is null unless tier=subscription.

GET/v1/billing/usagechat:run

Usage report summary plus per-event token, USD, and billed-credit views.

Query params: from, to (ISO), limit.

Lebenslauf-Jobs

POST/v1/resume/jobsresume:generate

Create async resume job.

Requires body.request_id. Canonical item bullets field: bullets. Legacy description_bullets is normalized with warnings. Compute billed (compile_tool): picture=2, original/harvard/business first free then 1.

GET/v1/resume/jobs/:jobIdresume:generate

Get job status.

Poll job.status (not top-level status). Values: queued | running | succeeded | failed | canceled.

GET/v1/resume/jobs/:jobId/pdfresume:generate

Download PDF artifact.

MCP

POST/v1/mcpmcp:connect

Primary MCP JSON-RPC endpoint (streamable HTTP).

Send initialize first, then tools/list and tools/call with MCP-Session-Id.

GET/v1/mcpmcp:connect

Attach SSE stream to an existing MCP session.

Requires MCP-Session-Id header.

DELETE/v1/mcpmcp:connect

Close MCP session.

GET/v1/mcp/ssemcp:connect

Legacy SSE MCP transport (compatibility).

POST/v1/mcp/messagesmcp:connect

Legacy SSE MCP message ingress.

Use query session_id from endpoint event.

GET/v1/mcp/toolsmcp:connect

Convenience REST wrapper to list tools.

POST/v1/mcp/tools/callmcp:connect

Convenience REST wrapper to invoke tool.

Resume-API Schnellstart

RESPONSE=$(curl -sS "https://cv.doxai.ch/v1/resume/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id":"demo-job-001",
    "cv_data": {
  "template": "original",
  "theme_color": "NavyBlue",
  "font_size": "11pt",
  "font_family": "arial",
  "identity": {
    "first_name": "Leif",
    "last_name": "Doxarve",
    "jobtitle": "AI Product Engineer",
    "email": "leif@example.com",
    "mobile": "+41 79 123 45 67",
    "address": "Lausanne, Switzerland",
    "linkedin": "https://linkedin.com/in/leif-doxarve",
    "github": "https://github.com/mieleif",
    "website": "https://doxai.ch"
  },
  "sections_order": ["summary", "experience", "education", "projects", "skills", "languages"],
  "sections": {
    "summary": {
      "type": "secondary",
      "content": "AI product engineer focused on practical automation, LLM integrations, and scalable orchestration."
    },
    "experience": {
      "type": "main",
      "items": [
        {
          "title": "DoxAI",
          "subtitle": "Founder & Product Engineer",
          "location": "Lausanne, CH",
          "start": "2024-06",
          "end": "Present",
          "bullets": [
            "Built AI-assisted CV platform with public API and MCP-compatible tools.",
            "Implemented billing-aware gateway architecture with provider abstraction and failover.",
            "Operated Docker-based deployments with Traefik, GitHub Actions, and Supabase."
          ]
        },
        {
          "title": "Consulting Projects",
          "subtitle": "Software Engineer",
          "location": "Remote",
          "start": "2022-01",
          "end": "2024-05",
          "bullets": [
            "Delivered full-stack web apps with TypeScript, React, and Node.js.",
            "Integrated third-party APIs and automated reporting pipelines."
          ]
        }
      ]
    },
    "education": {
      "type": "main",
      "items": [
        {
          "title": "University Example",
          "subtitle": "BSc in Computer Science",
          "location": "Switzerland",
          "start": "2018-09",
          "end": "2021-07",
          "bullets": [
            "Focus: software engineering, data systems, and applied machine learning."
          ]
        }
      ]
    },
    "projects": {
      "type": "main",
      "items": [
        {
          "title": "CV API Gateway",
          "subtitle": "Public Tools-Only Runtime",
          "start": "2026-02",
          "end": "Present",
          "bullets": [
            "Exposed authenticated resume tooling for agent/CLI consumption.",
            "Added compile-action credit billing and idempotent request handling."
          ]
        }
      ]
    },
    "skills": {
      "type": "secondary",
      "items": [
        {
          "title": "Tech Stack",
          "bullets": [
            "TypeScript",
            "Node.js",
            "Next.js",
            "Fastify",
            "Supabase",
            "Docker",
            "Traefik",
            "GitHub Actions",
            "PostgreSQL"
          ]
        }
      ]
    },
    "languages": {
      "type": "secondary",
      "items": [
        {
          "title": "Languages",
          "bullets": [
            "French (native)",
            "English (professional)"
          ]
        }
      ]
    }
  }
}
  }')

JOB_ID=$(echo "$RESPONSE" | jq -r '.job_id')

curl -sS "https://cv.doxai.ch/v1/resume/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '{job_id: .job.id, status: .job.status, warnings: .warnings}'

Resume-Polling-Antwort

Frage GET /v1/resume/jobs/:jobId ab und lies job.status. Mögliche Werte: queued, running, succeeded, failed, canceled.

{
  "ok": true,
  "request_id": "req_123",
  "warnings": [],
  "job": {
    "id": "f5821b92-9100-44ce-a610-c85c2499fe5b",
    "request_id": "demo-job-001",
    "mode": "managed",
    "status": "running",
    "created_at": "2026-03-17T15:00:00.000Z",
    "updated_at": "2026-03-17T15:00:01.000Z"
  }
}

MCP-Tools

resume.create_job
resume.get_job

curl -sS -D /tmp/mcp_headers.txt "https://cv.doxai.ch/v1/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"cli","version":"0.1.0"}}}'

SESSION_ID=$(grep -i '^MCP-Session-Id:' /tmp/mcp_headers.txt | awk '{print $2}' | tr -d '\r')

curl -X POST "https://cv.doxai.ch/v1/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":"tools-1","method":"tools/list","params":{}}'

Öffentliches cv_data-Beispiel

Kopierbares Start-Payload für /v1/resume/jobs oder MCP resume.create_job. Nutzt kanonische bullets-Arrays für gerenderten PDF-Inhalt. title wird zuerst gerendert, subtitle danach.

{
  "template": "original",
  "theme_color": "NavyBlue",
  "font_size": "11pt",
  "font_family": "arial",
  "identity": {
    "first_name": "Leif",
    "last_name": "Doxarve",
    "jobtitle": "AI Product Engineer",
    "email": "leif@example.com",
    "mobile": "+41 79 123 45 67",
    "address": "Lausanne, Switzerland",
    "linkedin": "https://linkedin.com/in/leif-doxarve",
    "github": "https://github.com/mieleif",
    "website": "https://doxai.ch"
  },
  "sections_order": ["summary", "experience", "education", "projects", "skills", "languages"],
  "sections": {
    "summary": {
      "type": "secondary",
      "content": "AI product engineer focused on practical automation, LLM integrations, and scalable orchestration."
    },
    "experience": {
      "type": "main",
      "items": [
        {
          "title": "DoxAI",
          "subtitle": "Founder & Product Engineer",
          "location": "Lausanne, CH",
          "start": "2024-06",
          "end": "Present",
          "bullets": [
            "Built AI-assisted CV platform with public API and MCP-compatible tools.",
            "Implemented billing-aware gateway architecture with provider abstraction and failover.",
            "Operated Docker-based deployments with Traefik, GitHub Actions, and Supabase."
          ]
        },
        {
          "title": "Consulting Projects",
          "subtitle": "Software Engineer",
          "location": "Remote",
          "start": "2022-01",
          "end": "2024-05",
          "bullets": [
            "Delivered full-stack web apps with TypeScript, React, and Node.js.",
            "Integrated third-party APIs and automated reporting pipelines."
          ]
        }
      ]
    },
    "education": {
      "type": "main",
      "items": [
        {
          "title": "University Example",
          "subtitle": "BSc in Computer Science",
          "location": "Switzerland",
          "start": "2018-09",
          "end": "2021-07",
          "bullets": [
            "Focus: software engineering, data systems, and applied machine learning."
          ]
        }
      ]
    },
    "projects": {
      "type": "main",
      "items": [
        {
          "title": "CV API Gateway",
          "subtitle": "Public Tools-Only Runtime",
          "start": "2026-02",
          "end": "Present",
          "bullets": [
            "Exposed authenticated resume tooling for agent/CLI consumption.",
            "Added compile-action credit billing and idempotent request handling."
          ]
        }
      ]
    },
    "skills": {
      "type": "secondary",
      "items": [
        {
          "title": "Tech Stack",
          "bullets": [
            "TypeScript",
            "Node.js",
            "Next.js",
            "Fastify",
            "Supabase",
            "Docker",
            "Traefik",
            "GitHub Actions",
            "PostgreSQL"
          ]
        }
      ]
    },
    "languages": {
      "type": "secondary",
      "items": [
        {
          "title": "Languages",
          "bullets": [
            "French (native)",
            "English (professional)"
          ]
        }
      ]
    }
  }
}