# REST API

> Public read endpoints under /api/v1 and the other HTTP endpoints, generated from the same spec as the MCP tools.

Base URL: `https://jenksguo.pages.dev`. JSON unless noted; `GET /api/v1/brief` returns Markdown (send `Accept: application/json` for `{ markdown }`). Machine-readable: [OpenAPI](https://jenksguo.pages.dev/openapi.json).

## Endpoints

| Method | Path | Tool | What it does |
| --- | --- | --- | --- |
| GET | `/api/v1/brief` | `get_brief` | A one-page Markdown brief about Jenks Guo: positioning, current role, career arc, strengths, languages, contact, and how to explore further. |
| GET | `/api/v1/entries` | `list_experience` | List Jenks's experiences, projects, community roles and education (newest first), optionally filtered by industry tag, role lens or kind. |
| GET | `/api/v1/entries/{slug}` | `get_entry` | Full long-form write-up of one experience, project, community role or education entry by slug: overview, what Jenks did, achievements, why it matters to employers, key results, skills, proof links.. |
| GET | `/api/v1/lenses` | `list_lenses` | The role lenses employers can view Jenks through (Head of AI, solution architect, developer advocate, digital marketer, hospitality…) with a pitch, honest gaps and evidence counts.. |
| GET | `/api/v1/search` | `search_jenks` | Keyword search across every entry and document. |
| GET | `/api/v1/documents/{name}` | `get_document` | One of Jenks's reference documents: profile (core profile), credentials (education, certifications), capabilities (capability → evidence map), talks (talks, podcasts, writing), thinking (point of view: seven views, each explained in plain words with examples, plus further beliefs).. |
| GET | `/api/v1/cv` | `list_cvs` | Jenks's downloadable CV (PDF) — the AI Lead CV — with version, date, a stable PDF url, a download url, a preview image and earlier versions. |
| GET | `/api/v1/cv/{slug}` | `get_cv` | One CV by slug: title, summary, version, the stable PDF url (always the current version, e.g. |
| GET | `/api/v1/arguments` | `list_arguments` | The arguments for Jenks by capability — AI transformation, agentic systems, leadership, enterprise integration, DevRel, Web3 partnerships and cross-project technical program leadership — each with its claim, qualifier and strength.. |
| GET | `/api/v1/arguments/{slug}` | `get_argument` | One argument by slug: the formal argument (premises → conclusion), evidence with numbers (entry slugs), market statistics with sources, honest limits, fair objections with answers, fallacious attacks (formal and informal) with replies, and when the argument does not apply. |
| POST | `/api/v1/ask` | `ask_jenks` | Ask the Ask Jenks assistant a natural-language question (role fit, consulting scoping, AI transformation advice, STAR stories, governance…). |
| POST | `/api/chat` | — | Streaming chat used by the website widget (plain-text stream; `events: true` interleaves \u001e status lines; `voice: true` asks for a short spoken reply). |
| POST | `/api/transcribe` | — | Voice fallback: transcribe base64 audio. |
| POST | `/api/speak` | — | Read text aloud for the widget's voice mode: { text, locale } → audio (English: Deepgram Aura-2 'theia', an Australian female voice; other languages: an OpenRouter audio model). |
| GET | `/api/health` | — | Liveness and configuration. |
| GET | `/cv/{slug}.pdf` | — | The current version of a CV as a PDF (stable link; ?download=1 downloads it). /cv/{slug}/{version}.pdf serves a specific version. |
| GET | `/media/{key}` | — | Uploaded images, videos and PDFs (R2). Immutable urls; supports Range and If-None-Match. |
| GET|POST | `/mcp` | — | Remote MCP server (Streamable HTTP, JSON-RPC 2.0). GET returns a discovery document. |

## Errors and limits

- `400 bad_request`, `404 not_found`, `429 rate_limited` (ask: 20/min/IP), `503` when a model key is not configured.
- GET endpoints send `Access-Control-Allow-Origin: *`; POST endpoints are for server-side agents.

## `get_brief` — Get Jenks's brief

A one-page Markdown brief about Jenks Guo: positioning, current role, career arc, strengths, languages, contact, and how to explore further. Start here.

- **MCP:** `get_brief` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/brief`
- **CLI:** `jenks brief`

_No arguments._

```bash
curl -s "https://jenksguo.pages.dev/api/v1/brief"
```

## `list_experience` — List experience

List Jenks's experiences, projects, community roles and education (newest first), optionally filtered by industry tag, role lens or kind. Returns short forms: title, organisation, period, summary, key result, page URL.

- **MCP:** `list_experience` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/entries?tag=&lens=&kind=&locale=`
- **CLI:** `jenks list [--tag it] [--lens solution-architect] [--kind project]`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `tag` | `it` · `engineering` · `ai` · `devrel` · `web3` · `business` · `marketing` · `consulting` · `hospitality` · `community` · `creative` | no |  |
| `lens` | `head-of-ai` · `ai-transformation-consultant` · `engineering-manager` · `solution-architect` · `system-integrator` · `support-engineer` · `ict-specialist` · `developer-advocate` · `developer-evangelist` · `digital-marketer` · `hospitality` | no |  |
| `kind` | `experience` · `education` · `community` · `project` | no |  |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/entries"
```

## `get_entry` — Get one entry

Full long-form write-up of one experience, project, community role or education entry by slug: overview, what Jenks did, achievements, why it matters to employers, key results, skills, proof links.

- **MCP:** `get_entry` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/entries/{slug}?locale=`
- **CLI:** `jenks get <slug>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `slug` | string | yes | Entry slug, e.g. xero-developer-evangelist |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/entries/xero-developer-evangelist"
```

## `list_lenses` — List role lenses

The role lenses employers can view Jenks through (Head of AI, solution architect, developer advocate, digital marketer, hospitality…) with a pitch, honest gaps and evidence counts.

- **MCP:** `list_lenses` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/lenses?locale=`
- **CLI:** `jenks lenses`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/lenses"
```

## `search_jenks` — Search the corpus

Keyword search across every entry and document. Returns the best-matching passages with their slugs.

- **MCP:** `search_jenks` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/search?q=`
- **CLI:** `jenks search "<query>"`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `query` | string | yes |  |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/search"
```

## `get_document` — Get a document

One of Jenks's reference documents: profile (core profile), credentials (education, certifications), capabilities (capability → evidence map), talks (talks, podcasts, writing), thinking (point of view: seven views, each explained in plain words with examples, plus further beliefs).

- **MCP:** `get_document` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/documents/{name}?locale=`
- **CLI:** `jenks doc <name>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | `profile` · `credentials` · `capabilities` · `talks` · `thinking` | yes |  |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/documents/credentials"
```

## `list_cvs` — List Jenks's CVs

Jenks's downloadable CV (PDF) — the AI Lead CV — with version, date, a stable PDF url, a download url, a preview image and earlier versions. For questions about his Web3 experience, get_cv with slug web3 returns the AI and Web3 CV (not listed here).

- **MCP:** `list_cvs` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/cv?locale=`
- **CLI:** `jenks cv`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/cv"
```

## `get_cv` — Get one CV

One CV by slug: title, summary, version, the stable PDF url (always the current version, e.g. https://jenksguo.pages.dev/cv/ai.pdf), the download url and all versions. Use ai for the AI Lead CV; use web3 for the AI and Web3 CV when someone asks about his Web3 experience.

- **MCP:** `get_cv` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/cv/{slug}?locale=`
- **CLI:** `jenks cv <slug> [--download] [-o file.pdf]`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `slug` | string | yes | ai (the AI Lead CV) or web3 (the AI and Web3 CV, for Web3 questions) |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/cv/xero-developer-evangelist"
```

## `list_arguments` — List the case for Jenks

The arguments for Jenks by capability — AI transformation, agentic systems, leadership, enterprise integration, DevRel, Web3 partnerships and cross-project technical program leadership — each with its claim, qualifier and strength.

- **MCP:** `list_arguments` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/arguments?locale=`
- **CLI:** `jenks argue`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/arguments"
```

## `get_argument` — Get one argument, with objections

One argument by slug: the formal argument (premises → conclusion), evidence with numbers (entry slugs), market statistics with sources, honest limits, fair objections with answers, fallacious attacks (formal and informal) with replies, and when the argument does not apply. Use it to test Jenks's fit, not only to promote it.

- **MCP:** `get_argument` on `https://jenksguo.pages.dev/mcp`
- **REST:** `GET /api/v1/arguments/{slug}?locale=`
- **CLI:** `jenks argue <slug>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `slug` | string | yes | ai-transformation, agentic-systems, leadership, enterprise-integration, devrel, web3-partnerships or technical-program-leadership |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.pages.dev/api/v1/arguments/xero-developer-evangelist"
```

## `ask_jenks` — Ask Jenks's assistant

Ask the Ask Jenks assistant a natural-language question (role fit, consulting scoping, AI transformation advice, STAR stories, governance…). It runs its own tools over the corpus and answers in the requested language. Rate-limited.

- **MCP:** `ask_jenks` on `https://jenksguo.pages.dev/mcp`
- **REST:** `POST /api/v1/ask`
- **CLI:** `jenks ask "<question>"`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `question` | string | yes |  |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |
| `history` | array | no | Optional earlier turns. |

```bash
curl -s -X POST https://jenksguo.pages.dev/api/v1/ask \
  -H 'content-type: application/json' \
  -d '{"question":"Is Jenks a fit for a Head of AI role?"}'
```