Developer/API

AI Gateway API

Current implementation snapshot. This surface is evolving and may change.

Provisional docs: endpoint contracts, headers, and scope rules can change.

Public Mode: Managed chat endpoints are retired for public API use. Use resume APIs and MCP resume tools.

Direct PAT API: Use your personal API token directly against the same host as this page. Production host: https://cv.doxai.ch

Base URL

https://cv.doxai.ch

Authentication

Personal API tokens are created from the account page and sent as Bearer tokens.

Authorization: Bearer <personal_api_token>

Open account token manager

MCP Server URL

For ChatGPT MCP / remote clients, use the streamable HTTP endpoint below.

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

Common Headers

Authorization: Bearer ...
x-request-id optional request correlation header
body.request_id required for /v1/resume/jobs and resume.create_job
x-ai-mode optional on /v1/models to inspect managed|api|mcp surfaces (default: api)
Public managed chat routes are retired; x-ai-mode does not re-enable them

Token Scopes

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

Tier Fields

Responses expose both internal billing keys for logic and public labels for display.

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

`paid` is an internal access class for non-free models. It maps to Flex and Pro eligibility, not a public plan name.

System

GET/healthzpublic

Liveness check.

GET/readyzpublic

Readiness check (Supabase dependency).

GET/versionpublic

Gateway runtime/version info.

Auth Introspection

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.

Models

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.

Billing

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.

Resume 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 Quickstart

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 Poll Response

Poll GET /v1/resume/jobs/:jobId and read job.status. Possible values: 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":{}}'

Public cv_data Example

Copy-paste starter payload for /v1/resume/jobs or MCP resume.create_job. Uses canonical bullets arrays for rendered PDF content. title renders first; subtitle renders second.

{
  "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)"
          ]
        }
      ]
    }
  }
}