API de Typemark
Crea un token de API y trabaja con tus proyectos y publicaciones desde scripts y CI.
Actualizado el 19 nov 20266 min de lectura
La API de Typemark permite a los scripts y a CI leer tus proyectos y sus publicaciones, por ejemplo para esperar a que una publicación termine antes de que salga una versión. Está disponible en todos los planes.
Para descargar, editar y publicar documentación desde la terminal o CI, usa la CLI de Typemark. Está construida sobre esta API y se encarga de la sincronización y de los conflictos por ti.
Crear un token de API
Abre tu cuenta
Haz clic en tu nombre en la parte inferior de la barra lateral del panel y después en Account.
Asigna un nombre al token
En API tokens, dale al token un nombre que indique dónde se usa, como
GitHub Actions.Elige cuándo expira
Elige 30 días, 90 días, un año o nunca. Cuando un token expira, las solicitudes que lo usan dejan de funcionar.
Cópialo
Haz clic en Create token y copia el token. Empieza por
tmk_.
Un token actúa en tu nombre. Puede leer todos los proyectos que posees o de los que eres miembro, con tu rol en cada uno. No lo incluyas en el código ni en nada público.
Revocar un token
En la página Account, haz clic en Revoke junto al token. Todo lo que lo use dejará de funcionar de inmediato. La lista muestra cuándo se usó cada token por última vez, para que detectes los que ya no necesita nadie.
Hacer una solicitud
Envía el token en el encabezado Authorization. Todos los endpoints están bajo https://typemark.dev/api/v1.
curl https://typemark.dev/api/v1/user \
-H "Authorization: Bearer $TYPEMARK_TOKEN"
{
"user": {
"id": "6945f00a-3d8a-4609-8dd8-eb4c1aa3fbab",
"name": "Ada Lovelace",
"email": "[email protected]",
"plan": "pro",
"trialing": false
},
"token": {
"name": "GitHub Actions",
"hint": "tmk_…Z4Fr",
"created_at": "2026-11-16T10:12:00Z",
"last_used_at": "2026-11-16T10:14:00Z",
"expires_at": "2027-02-14T10:12:00Z"
}
}
plan es free, pro o business. business es el plan Enterprise: la API conserva el nombre anterior del plan para que los scripts que lo comprueban sigan funcionando.
Endpoints
| Método | Ruta | Devuelve |
|---|---|---|
GET | /user | El usuario del token, su plan y el propio token |
GET | /projects | Todos los proyectos que posees o de los que eres miembro |
GET | /projects/{slug} | Un proyecto, con su número de páginas y la última publicación |
POST | /projects | Crea un proyecto. Lo usa typemark create. |
GET | /projects/{slug}/deployments | Publicaciones recientes, de la más nueva a la más antigua |
GET | /projects/{slug}/deployments/{id} | Una publicación |
GET | /projects/{slug}/files | Todos los archivos del proyecto, con su id de blob de Git y el commit del que proceden |
GET | /projects/{slug}/archive | Los archivos del proyecto como .tar.gz. Pasa sha para un commit específico. |
POST | /projects/{slug}/push | Modifica, añade o elimina archivos en un solo commit y luego publica. Lo usa typemark push. |
POST | /migrate/mintlify | Convierte un docs.json o mint.json de Mintlify en typemark.json. Lo usa typemark migrate. |
POST | /migrate/gitbook, /migrate/readme | Convierte un espacio de GitBook o un proyecto de ReadMe en páginas de Typemark y typemark.json. Lo usa typemark migrate. |
POST | /openapi/pages | Las páginas que Typemark genera a partir de una especificación OpenAPI: envía source (su ruta en typemark.json), content (su texto) y group. Lo usa typemark dev. No se guarda nada. |
DELETE | /token | Revoca el token que envió la solicitud |
Proyectos
curl https://typemark.dev/api/v1/projects/acme-docs \
-H "Authorization: Bearer $TYPEMARK_TOKEN"
{
"project": {
"id": "c1111111-1111-1111-1111-111111111111",
"name": "Acme Docs",
"slug": "acme-docs",
"role": "owner",
"locked": false,
"repo_mode": "connected",
"github_repo": "acme/docs",
"deploy_mode": "auto",
"deploy_status": "live",
"site_status": "live",
"url": "https://docs.acme.com",
"editor_url": "https://typemark.dev/projects/acme-docs/editor",
"last_deployed_at": "2026-11-16T09:58:41Z",
"last_deploy_commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
"updated_at": "2026-11-16T09:58:41Z",
"pages_count": 24,
"has_unpublished_changes": false,
"last_deployment": {
"id": "8d0c2f4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
"status": "success",
"commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
"commit_message": "docs: update quickstart.mdx",
"commit_author": "Ada Lovelace",
"pages_changed": 1,
"build_duration_ms": 1840,
"error_message": null,
"created_at": "2026-11-16T09:58:39Z",
"completed_at": "2026-11-16T09:58:41Z"
}
}
}
GET /projects devuelve los mismos campos para cada proyecto, sin pages_count, has_unpublished_changes y last_deployment.
Crear un proyecto
curl https://typemark.dev/api/v1/projects \
-H "Authorization: Bearer $TYPEMARK_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme Docs", "slug": "acme-docs" }'
Crea un proyecto del que eres propietario, igual que New project en el panel: un typemark.json y algunas páginas iniciales, con el sitio fuera de línea hasta que lo publiques. slug es opcional; si no lo indicas, se genera a partir del nombre. La respuesta es 201 con el proyecto, con la misma forma que GET /projects/{slug}.
| Estado | Código | Significado |
|---|---|---|
403 | project_limit | Tu plan no admite otro proyecto. El error añade upgrade_url. |
403 | unconfirmed | Confirma primero tu dirección de correo electrónico |
422 | slug_taken | Otro proyecto ya usa ese slug |
422 | invalid | El nombre está vacío, o el slug no contiene solo letras minúsculas, números y guiones, o no se puede usar. El error añade field. |
rolestringTu rol en el proyecto: owner, editor o viewer. Consulta Miembros del equipo.
lockedbooleantrue cuando el proyecto es de solo lectura porque el plan del propietario no lo cubre. Consulta Facturación.
repo_modestringmanaged cuando Typemark aloja el repositorio, connected cuando se sincroniza con GitHub. github_repo se establece en los proyectos conectados.
deploy_modestringauto o manual. Consulta Publicación.
deploy_statusstringLa última compilación: pending, building, live o failed.
site_statusstringlive cuando los lectores pueden ver el sitio, offline cuando está oculto.
urlstringDónde encuentran los lectores el sitio: tu dominio personalizado una vez verificado; si no, https://{slug}.typemark.dev.
has_unpublished_changesbooleanEn el modo de publicación manual, true cuando hay cambios que aún no se han publicado.
Publicaciones
Cada publicación del sitio es un despliegue. Pasa limit para elegir cuántos recibes: 20 por defecto, hasta 100.
curl "https://typemark.dev/api/v1/projects/acme-docs/deployments?limit=1" \
-H "Authorization: Bearer $TYPEMARK_TOKEN"
{
"deployments": [
{
"id": "8d0c2f4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
"status": "success",
"commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
"commit_message": "docs: update quickstart.mdx",
"commit_author": "Ada Lovelace",
"pages_changed": 1,
"build_duration_ms": 1840,
"error_message": null,
"created_at": "2026-11-16T09:58:39Z",
"completed_at": "2026-11-16T09:58:41Z"
}
]
}
statusstringpending, building, success o failed. Cuando es failed, error_message indica el motivo.
Ejemplo: esperar una publicación en CI
Después de subir cambios de documentación a GitHub, espera hasta que Typemark los haya publicado:
#!/usr/bin/env bash
set -euo pipefail
API="https://typemark.dev/api/v1/projects/acme-docs/deployments?limit=1"
for attempt in $(seq 1 30); do
latest=$(curl -fsS "$API" -H "Authorization: Bearer $TYPEMARK_TOKEN")
status=$(echo "$latest" | jq -r '.deployments[0].status')
sha=$(echo "$latest" | jq -r '.deployments[0].commit_sha')
if [ "$sha" = "$GITHUB_SHA" ] && [ "$status" = "success" ]; then
echo "Published $sha"
exit 0
fi
if [ "$sha" = "$GITHUB_SHA" ] && [ "$status" = "failed" ]; then
echo "$latest" | jq -r '.deployments[0].error_message'
exit 1
fi
sleep 5
done
echo "Timed out waiting for Typemark to publish $GITHUB_SHA"
exit 1
Errores
Los errores se devuelven como JSON con un código que puedes comprobar y un mensaje que puedes mostrar:
{
"error": {
"code": "not_found",
"message": "Not found."
}
}
| Estado | Código | Significado |
|---|---|---|
400 | bad_request | Falta un parámetro obligatorio |
401 | unauthorized | El token falta, es incorrecto, está revocado o ha expirado |
403 | forbidden | Tu rol en el proyecto no permite esto, por ejemplo, un viewer que hace push |
403 | plan_limit | El plan del propietario del proyecto no incluye esto. El error añade feature y upgrade_url. |
403 | project_limit | Al crear un proyecto: tu plan no admite otro. El error añade upgrade_url. |
403 | unconfirmed | Al crear un proyecto: confirma primero tu dirección de correo electrónico |
404 | not_found | El proyecto o la publicación no existen, o no eres miembro del proyecto |
409 | conflict | Un push cambia archivos que también cambiaron en Typemark desde base_sha. El error los enumera en conflicts. |
409 | stale_base | Un push se basa en un commit que Typemark no tiene. Vuelve a descargar el proyecto y luego haz push. |
409 | connected_repo | El proyecto se sincroniza con GitHub, así que los push van a GitHub en su lugar |
409 | busy | Otro cambio en el proyecto se está guardando. Inténtalo de nuevo en un momento. |
413 | too_large | Un push supera los límites: 500 archivos, 10 MB por archivo, 50 MB por push, 100 MB por proyecto. Una especificación OpenAPI de más de 10 MB. |
422 | slug_taken, invalid | Al crear un proyecto: el slug ya está en uso, o el nombre o el slug no son válidos (field indica cuál) |
422 | invalid_spec | Una especificación OpenAPI que no se puede analizar. El mensaje indica dónde está el problema. |
422 | invalid_path | Un push indica una ruta que Typemark no escribirá: vacía, que empieza por /, con una barra invertida, con . o .., o dentro de .git/ o .typemark/ |
422 | not_mintlify, not_gitbook, not_readme | Al migrar: los archivos no parecen una configuración de Mintlify, un espacio de GitBook o un proyecto de ReadMe |
426 | cli_outdated | La CLI de Typemark es demasiado antigua para la API. El hint indica cómo actualizarla. Solo las solicitudes que indican una versión de la CLI lo reciben. |
429 | Demasiadas solicitudes. Espera el número de segundos indicado en el encabezado Retry-After. | |
503 | git_error | No se pudo leer o escribir el repositorio del proyecto. Inténtalo de nuevo en un momento. |
Límites
Cada dirección IP puede hacer 300 solicitudes a la API por minuto, incluidos hasta 30 push, 30 descargas de archivos y 30 especificaciones OpenAPI.