API de administración

Endpoints autenticados que editan el contenido del sitio mediante commits de git validados.

Todos los endpoints de administración necesitan un agent service token: Authorization: Bearer jgx_agt_… (la CLI lee la variable de entorno JENKSGUO_ADMIN_TOKEN). Jenks crea tokens en la consola en https://admin.jenksguo.xyz/admin → Access después de iniciar sesión con Google (Cloudflare Access); cada token tiene nombre, alcance (content, media, publish; todos los tokens pueden leer), caducidad y se puede revocar. Escribir en la rama main también requiere publish. Cada escritura y cada intento rechazado van al registro de auditoría. Ver Give an AI agent access. Las escrituras se validan con el mismo esquema que la build y luego se confirman en GitHub. El CI traduce las entradas modificadas a todos los idiomas, recompila y despliega: main → jenksguo.pages.dev y jenksguo.xyz, dev → dev.jenksguo.xyz.

Método	Ruta	Herramienta
GET · POST	`/api/admin/tokens`	— (solo personas: listar o crear agent tokens; SSO)
DELETE	`/api/admin/tokens/{id}`	— (solo personas: revocar; SSO)
POST	`/api/admin/login` · `/api/admin/logout`	— (solo desarrollo local)
GET	`/api/admin/whoami`	`admin_whoami`
GET	`/api/admin/audit`	`admin_audit_log`
GET	`/api/admin/schema`	`admin_schema`
GET	`/api/admin/files`	`admin_list_files`
GET	`/api/admin/file`	`admin_read_file`
POST	`/api/admin/validate`	`admin_validate`
PUT	`/api/admin/file`	`admin_write_file`
DELETE	`/api/admin/file`	`admin_delete_file`
POST	`/api/admin/changes`	`admin_commit_changes`
POST	`/api/admin/ai-edit`	`admin_ai_edit`
GET	`/api/admin/translation`	`admin_read_translation`
PUT	`/api/admin/translation`	`admin_write_translation`
GET	`/api/admin/copy`	`admin_read_copy`
PUT	`/api/admin/copy`	`admin_write_copy`
GET	`/api/admin/deploys`	`admin_deploy_status`
POST	`/api/admin/promote`	`admin_promote`
POST	`/api/admin/cv`	`admin_publish_cv`
GET	`/api/admin/media`	`admin_list_media`
POST	`/api/admin/media`	`admin_upload_media`
PATCH	`/api/admin/media`	`admin_update_media`
DELETE	`/api/admin/media`	`admin_delete_media`

Errores: 401 unauthorized · unknown_token · token_expired · token_revoked, 403 missing_scope (con needs[]) · sso_required · forbidden_path (solo se pueden escribir archivos de contenido), 422 invalid con errors[], 409/502 github_error, 503 github_not_configured.

`admin_whoami` — ¿Quién soy?

Comprueba tu credencial: quién eres (correo de SSO o nombre del agent token), tus alcances, cuándo caduca tu token y si la publicación (GitHub) está configurada.

MCP: admin_whoami en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/whoami (agent token)
Alcance: read
CLI: jenks admin whoami

Sin argumentos.

curl -s "https://jenksguo.pages.dev/api/admin/whoami" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_audit_log` — Registro de auditoría

Acciones administrativas recientes, primero las más nuevas: quién (correo de SSO o agent token), qué, qué archivos, rama, host y resultado. Un agent token solo ve sus propias acciones.

MCP: admin_audit_log en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/audit?limit=&token= (agent token)
Alcance: read
CLI: jenks admin audit [--limit 50]

Argumento	Tipo	Requerido	Notas
`limit`	integer	no
`token`	string	no	Solo este id de agent token (solo personas)

curl -s "https://jenksguo.pages.dev/api/admin/audit" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_schema` — Esquema de contenido

El modelo de contenido: campos y reglas de las entradas, etiquetas, lentes, tipos, rutas escribibles, documentos y convenciones de edición. Léelo antes de escribir.

MCP: admin_schema en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/schema (agent token)
Alcance: read
CLI: jenks admin schema

Sin argumentos.

curl -s "https://jenksguo.pages.dev/api/admin/schema" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_list_files` — Listar archivos de contenido

Lista archivos de contenido editables en una rama (ruta, tamaño, sha), opcionalmente dentro de una carpeta como content/corpus/experiences.

MCP: admin_list_files en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/files?dir=&branch= (agent token)
Alcance: read
CLI: jenks admin ls [dir]

Argumento	Tipo	Requerido	Notas
`dir`	string	no	p. ej. content/corpus/projects (por defecto: todo el contenido)
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s "https://jenksguo.pages.dev/api/admin/files" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_read_file` — Leer un archivo de contenido

Lee la fuente Markdown/JSON sin procesar de un archivo de contenido (con su sha). Pasa path, o slug para una entrada, lens o skill.

MCP: admin_read_file en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/file?path=&slug=&branch= (agent token)
Alcance: read
CLI: jenks admin get <slug|path>

Argumento	Tipo	Requerido	Notas
`path`	string	no
`slug`	string	no
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s "https://jenksguo.pages.dev/api/admin/file" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_validate` — Validar un cambio

Valida el contenido de un archivo contra el esquema de contenido sin hacer commit. Devuelve una lista de problemas (vacía = válido).

MCP: admin_validate en https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/validate (agent token)
Alcance: read
CLI: jenks admin validate <path> <file>

Argumento	Tipo	Requerido	Notas
`path`	string	sí
`content`	string	sí

curl -s -X POST https://jenksguo.pages.dev/api/admin/validate \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>"}'

`admin_write_file` — Crear o actualizar un archivo de contenido

Valida y hace commit de un archivo de contenido (crear o reemplazar). La publicación es automática: el CI retraduce las entradas modificadas a todos los idiomas, recompila y despliega (main → jenksguo.pages.dev y jenksguo.xyz, dev → dev.jenksguo.xyz) en pocos minutos.

MCP: admin_write_file en https://jenksguo.pages.dev/mcp/admin
REST: PUT /api/admin/file (agent token)
Alcance: content (+ publish para la rama main)
CLI: jenks admin put <path> <file> -m <message>

Argumento	Tipo	Requerido	Notas
`path`	string	sí
`content`	string	sí
`message`	string	sí	Mensaje de commit
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s -X PUT https://jenksguo.pages.dev/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>","message":"<message>"}'

`admin_delete_file` — Eliminar un archivo de contenido

Elimina un archivo de contenido (p. ej. quitar una entrada) con un mensaje de commit. El historial de Git lo mantiene recuperable.

MCP: admin_delete_file en https://jenksguo.pages.dev/mcp/admin
REST: DELETE /api/admin/file?path=&message=&branch= (agent token)
Alcance: content (+ publish para la rama main)
CLI: jenks admin rm <path> -m <message>

Argumento	Tipo	Requerido	Notas
`path`	string	sí
`message`	string	sí
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s -X DELETE https://jenksguo.pages.dev/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","message":"<message>"}'

`admin_commit_changes` — Hacer commit de varios archivos a la vez

Valida y hace commit de varios cambios de archivos como UN solo commit. Cada cambio es {path, content} o {path, delete: true}.

MCP: admin_commit_changes en https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/changes (agent token)
Alcance: content (+ publish para la rama main)
CLI: jenks admin commit <changes.json> -m <message>

Argumento	Tipo	Requerido	Notas
`changes`	array	sí
`message`	string	sí
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s -X POST https://jenksguo.pages.dev/api/admin/changes \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"changes":"<changes>","message":"<message>"}'

`admin_ai_edit` — Redactar una edición con IA

Pídele al modelo del sitio que reescriba un archivo de contenido a partir de una instrucción en inglés sencillo. Devuelve el contenido propuesto, un diff y problemas de validación. NO hace commit — revisa y luego llama a admin_write_file.

MCP: admin_ai_edit en https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/ai-edit (agent token)
Alcance: content
CLI: jenks admin ai-edit <slug|path> "<instruction>" [--apply]

Argumento	Tipo	Requerido	Notas
`path`	string	no
`slug`	string	no
`instruction`	string	sí
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).
`content`	string	no	Texto de archivo no guardado opcional desde el que redactar (por defecto: el archivo guardado).

curl -s -X POST https://jenksguo.pages.dev/api/admin/ai-edit \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"instruction":"<instruction>"}'

`admin_read_translation` — Leer una traducción

Un archivo de contenido en otro idioma: los campos fuente en inglés, la traducción actual y su estado (actual, desactualizada, editada a mano, faltante). Funciona para entries, lenses, CVs, arguments, páginas de punto de vista, credentials, talks y la documentación. Idiomas: zh, zh-hant, ja, fr, es, eo.

MCP: admin_read_translation en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/translation?path=&slug=&locale=&branch= (agent token)
Alcance: read
CLI: jenks admin tr get <slug|path> <locale>

Argumento	Tipo	Requerido	Notas
`path`	string	no
`slug`	string	no
`locale`	`zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	sí
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s "https://jenksguo.pages.dev/api/admin/translation" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_write_translation` — Editar una traducción

Escribe el texto de un archivo de contenido en otro idioma (zh, zh-hant, ja, fr, es, eo), por ejemplo un mejor resumen en chino. Indica solo los campos a cambiar; primero lee admin_read_translation para los nombres de campo. Markdown debe mantener los encabezados en inglés, los bloques de código y los enlaces. La edición se conserva hasta que cambie el inglés; entonces ese idioma se vuelve a traducir automáticamente. El inglés es la fuente: cámbialo con admin_write_file.

MCP: admin_write_translation en https://jenksguo.pages.dev/mcp/admin
REST: PUT /api/admin/translation (agent token)
Alcance: content (+ publish para la rama main)
CLI: jenks admin tr put <slug|path> <locale> <fields.json> -m <message>

Argumento	Tipo	Requerido	Notas
`path`	string	no
`slug`	string	no
`locale`	`zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	sí
`fields`	object	sí	p. ej. {"summary": "…", "body": "## …"}
`message`	string	no	Mensaje de commit
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s -X PUT https://jenksguo.pages.dev/api/admin/translation \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"locale":"<locale>","fields":"<fields>"}'

`admin_read_copy` — Leer los textos de la interfaz

Los textos de la interfaz del sitio en un idioma — menús, títulos de página, las introducciones de una línea, el titular del hero, botones, descripciones SEO — como clave → texto, con el inglés (y el chino para zh-hant) al lado. Filtra con un prefijo, p. ej. hero o career.

MCP: admin_read_copy en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/copy?locale=&prefix=&branch= (agent token)
Alcance: read
CLI: jenks admin copy get <locale> [prefix]

Argumento	Tipo	Requerido	Notas
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	sí
`prefix`	string	no
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s "https://jenksguo.pages.dev/api/admin/copy" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_write_copy` — Editar los textos de la interfaz

Cambia textos de la interfaz en un idioma: values es clave → texto ("" elimina tu edición). en y zh son las fuentes escritas a mano: un cambio en inglés se traduce automáticamente a ja, fr, es y eo — también establece zh. Una edición en otro idioma se conserva hasta que cambie su texto fuente. Mantén los {placeholders} exactamente.

MCP: admin_write_copy en https://jenksguo.pages.dev/mcp/admin
REST: PUT /api/admin/copy (agent token)
Alcance: content (+ publish para la rama main)
CLI: jenks admin copy set <locale> <key> "<text>" -m <message>

Argumento	Tipo	Requerido	Notas
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	sí
`values`	object	sí	p. ej. {"hero.sub": "…"}
`message`	string	no
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s -X PUT https://jenksguo.pages.dev/api/admin/copy \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"locale":"<locale>","values":"<values>"}'

`admin_deploy_status` — Estado de los despliegues

Ejecuciones recientes de CI (traducción → build → deploy) con estado, rama, commit y enlaces.

MCP: admin_deploy_status en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/deploys?branch= (agent token)
Alcance: read
CLI: jenks admin deploys

Argumento	Tipo	Requerido	Notas
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s "https://jenksguo.pages.dev/api/admin/deploys" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_promote` — Promocionar dev a producción

Fusiona la rama dev en main, publicando todo lo previsualizado en dev.jenksguo.xyz en el sitio en vivo (jenksguo.pages.dev y jenksguo.xyz).

MCP: admin_promote en https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/promote (agent token)
Alcance: publish
CLI: jenks admin promote

Argumento	Tipo	Requerido	Notas
`message`	string	no

curl -s -X POST https://jenksguo.pages.dev/api/admin/promote \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{}'

`admin_publish_cv` — Publicar una nueva versión del CV

Sube un nuevo PDF para un CV (ai, web3 o un nuevo slug) y conviértelo en la versión actual en un solo paso: el PDF va a la biblioteca de medios, la versión anterior pasa al historial del CV (sigue siendo descargable) y se hace commit del cambio (el CI lo publica). Imagen de vista previa y nuevo título/resumen opcionales. La URL estable /cv/.pdf servirá entonces el nuevo archivo.

MCP: admin_publish_cv en https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/cv (agent token)
Alcance: content + media (+ publish para la rama main)
CLI: jenks admin cv publish <slug> <file.pdf> --cv-version 2026.10 [--preview /media/…]

Argumento	Tipo	Requerido	Notas
`slug`	string	sí	ai, web3 o un nuevo id en kebab-case
`version`	string	sí	p. ej. 2026.10
`filename`	string	no
`data`	string	no	Bytes del PDF, base64
`url`	string	no	Alternativa a data: URL https del PDF
`preview`	string	no	Opcional: una imagen ya subida /media/… de la página 1
`title`	string	no
`summary`	string	no
`message`	string	no	Mensaje de commit
`branch`	`main` · `dev`	no	main publica el sitio en vivo (jenksguo.pages.dev y su espejo jenksguo.xyz); dev hace preview en dev.jenksguo.xyz (por defecto main).

curl -s -X POST https://jenksguo.pages.dev/api/admin/cv \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"slug":"<slug>","version":"<version>"}'

`admin_list_media` — Listar medios

Lista imágenes, videos y PDFs subidos (los más nuevos primero): url, tipo, tamaño, dimensiones, texto alternativo, Markdown listo para pegar y qué entradas usan cada archivo.

MCP: admin_list_media en https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/media?prefix=&cursor=&limit= (agent token)
Alcance: read
CLI: jenks admin media ls [prefix]

Argumento	Tipo	Requerido	Notas
`prefix`	string	no	Prefijo de clave como 2026/10
`cursor`	string	no
`limit`	integer	no

curl -s "https://jenksguo.pages.dev/api/admin/media" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_upload_media` — Subir medios

Almacena una imagen (webp, jpg, png, gif, avif, svg), video (mp4, webm) o PDF, de hasta 25 MB, en Cloudflare R2 y obtén su URL pública /media/… y Markdown. Envía data en base64 con un filename, o una url https pública para importar. Los archivos son públicos por URL de inmediato; reféncialos desde el contenido con admin_write_file. El endpoint REST también acepta multipart/form-data (campo file).

MCP: admin_upload_media en https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/media (agent token)
Alcance: media
CLI: jenks admin media upload <file|https-url> [--alt "…"]

Argumento	Tipo	Requerido	Notas
`filename`	string	no	Nombre original del archivo; se convierte en la parte legible de la URL.
`data`	string	no	Bytes del archivo, base64 (se permite un prefijo data: URL).
`url`	string	no	Alternativa a data: una URL https que el servidor descargará.
`alt`	string	no	Texto alternativo: qué muestra la imagen, para lectores de pantalla y el bot.
`width`	integer	no
`height`	integer	no

curl -s -X POST https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{}'

`admin_update_media` — Actualizar el texto alternativo

Cambia el texto alternativo almacenado de un archivo subido (el alt por defecto cuando se inserta en el contenido).

MCP: admin_update_media en https://jenksguo.pages.dev/mcp/admin
REST: PATCH /api/admin/media (agent token)
Alcance: media
CLI: jenks admin media alt <key> "<alt text>"

Argumento	Tipo	Requerido	Notas
`key`	string	sí	Clave o URL del medio, p. ej. 2026/10/xero-talk-1a2b3c4d5e.webp
`alt`	string	sí

curl -s -X PATCH https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"key":"<key>","alt":"<alt>"}'

`admin_delete_media` — Eliminar medios

Elimina permanentemente un archivo subido. Se rechaza mientras contenido publicado aún lo use, a menos que force sea true. No recuperable — a diferencia de los archivos de contenido, no hay historial de git.

MCP: admin_delete_media en https://jenksguo.pages.dev/mcp/admin
REST: DELETE /api/admin/media?key=&force= (agent token)
Alcance: media
CLI: jenks admin media rm <key> [--force]

Argumento	Tipo	Requerido	Notas
`key`	string	sí
`force`	boolean	no

curl -s -X DELETE https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"key":"<key>"}'

.mdEsta página está traducida con ayuda de IA; los títulos oficiales permanecen en inglés.

API de administración

admin_whoami — ¿Quién soy?

admin_audit_log — Registro de auditoría

admin_schema — Esquema de contenido

admin_list_files — Listar archivos de contenido

admin_read_file — Leer un archivo de contenido

admin_validate — Validar un cambio

admin_write_file — Crear o actualizar un archivo de contenido

admin_delete_file — Eliminar un archivo de contenido

admin_commit_changes — Hacer commit de varios archivos a la vez

admin_ai_edit — Redactar una edición con IA

admin_read_translation — Leer una traducción

admin_write_translation — Editar una traducción

admin_read_copy — Leer los textos de la interfaz

admin_write_copy — Editar los textos de la interfaz

admin_deploy_status — Estado de los despliegues

admin_promote — Promocionar dev a producción

admin_publish_cv — Publicar una nueva versión del CV

admin_list_media — Listar medios

admin_upload_media — Subir medios

admin_update_media — Actualizar el texto alternativo

admin_delete_media — Eliminar medios