Typemark Documentation

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

  1. Abre tu cuenta

    Haz clic en tu nombre en la parte inferior de la barra lateral del panel y después en Account.

  2. Asigna un nombre al token

    En API tokens, dale al token un nombre que indique dónde se usa, como GitHub Actions.

  3. 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.

  4. 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étodoRutaDevuelve
GET/userEl usuario del token, su plan y el propio token
GET/projectsTodos 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/projectsCrea un proyecto. Lo usa typemark create.
GET/projects/{slug}/deploymentsPublicaciones recientes, de la más nueva a la más antigua
GET/projects/{slug}/deployments/{id}Una publicación
GET/projects/{slug}/filesTodos los archivos del proyecto, con su id de blob de Git y el commit del que proceden
GET/projects/{slug}/archiveLos archivos del proyecto como .tar.gz. Pasa sha para un commit específico.
POST/projects/{slug}/pushModifica, añade o elimina archivos en un solo commit y luego publica. Lo usa typemark push.
POST/migrate/mintlifyConvierte un docs.json o mint.json de Mintlify en typemark.json. Lo usa typemark migrate.
POST/migrate/gitbook, /migrate/readmeConvierte un espacio de GitBook o un proyecto de ReadMe en páginas de Typemark y typemark.json. Lo usa typemark migrate.
POST/openapi/pagesLas 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/tokenRevoca 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}.

EstadoCódigoSignificado
403project_limitTu plan no admite otro proyecto. El error añade upgrade_url.
403unconfirmedConfirma primero tu dirección de correo electrónico
422slug_takenOtro proyecto ya usa ese slug
422invalidEl 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.
rolestring

Tu rol en el proyecto: owner, editor o viewer. Consulta Miembros del equipo.

lockedboolean

true cuando el proyecto es de solo lectura porque el plan del propietario no lo cubre. Consulta Facturación.

repo_modestring

managed cuando Typemark aloja el repositorio, connected cuando se sincroniza con GitHub. github_repo se establece en los proyectos conectados.

deploy_modestring

auto o manual. Consulta Publicación.

deploy_statusstring

La última compilación: pending, building, live o failed.

site_statusstring

live cuando los lectores pueden ver el sitio, offline cuando está oculto.

urlstring

Dónde encuentran los lectores el sitio: tu dominio personalizado una vez verificado; si no, https://{slug}.typemark.dev.

has_unpublished_changesboolean

En 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"
    }
  ]
}
statusstring

pending, 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."
  }
}
EstadoCódigoSignificado
400bad_requestFalta un parámetro obligatorio
401unauthorizedEl token falta, es incorrecto, está revocado o ha expirado
403forbiddenTu rol en el proyecto no permite esto, por ejemplo, un viewer que hace push
403plan_limitEl plan del propietario del proyecto no incluye esto. El error añade feature y upgrade_url.
403project_limitAl crear un proyecto: tu plan no admite otro. El error añade upgrade_url.
403unconfirmedAl crear un proyecto: confirma primero tu dirección de correo electrónico
404not_foundEl proyecto o la publicación no existen, o no eres miembro del proyecto
409conflictUn push cambia archivos que también cambiaron en Typemark desde base_sha. El error los enumera en conflicts.
409stale_baseUn push se basa en un commit que Typemark no tiene. Vuelve a descargar el proyecto y luego haz push.
409connected_repoEl proyecto se sincroniza con GitHub, así que los push van a GitHub en su lugar
409busyOtro cambio en el proyecto se está guardando. Inténtalo de nuevo en un momento.
413too_largeUn 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.
422slug_taken, invalidAl crear un proyecto: el slug ya está en uso, o el nombre o el slug no son válidos (field indica cuál)
422invalid_specUna especificación OpenAPI que no se puede analizar. El mensaje indica dónde está el problema.
422invalid_pathUn 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/
422not_mintlify, not_gitbook, not_readmeAl migrar: los archivos no parecen una configuración de Mintlify, un espacio de GitBook o un proyecto de ReadMe
426cli_outdatedLa 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.
429Demasiadas solicitudes. Espera el número de segundos indicado en el encabezado Retry-After.
503git_errorNo 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.