# 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.xyz`. JSON unless noted; `GET /api/v1/brief` returns Markdown (send `Accept: application/json` for `{ markdown }`). Machine-readable: [OpenAPI](https://jenksguo.xyz/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 (worldview).. |
| 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). |
| POST | `/api/transcribe` | — | Voice fallback: transcribe base64 audio. |
| GET | `/api/health` | — | Liveness and configuration. |
| 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.xyz/mcp`
- **REST:** `GET /api/v1/brief`
- **CLI:** `jenks brief`

_No arguments._

```bash
curl -s "https://jenksguo.xyz/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.xyz/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.xyz/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.xyz/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.xyz/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.xyz/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.xyz/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.xyz/mcp`
- **REST:** `GET /api/v1/search?q=`
- **CLI:** `jenks search "<query>"`

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

```bash
curl -s "https://jenksguo.xyz/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 (worldview).

- **MCP:** `get_document` on `https://jenksguo.xyz/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.xyz/api/v1/documents/credentials"
```

## `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.xyz/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.xyz/api/v1/ask \
  -H 'content-type: application/json' \
  -d '{"question":"Is Jenks a fit for a Head of AI role?"}'
```