Typemark Documentation

Typemark API

Erstelle ein API-Token und arbeite mit deinen Projekten und Veröffentlichungen aus Skripten und CI.

Aktualisiert am 19. Nov. 20265 Min. Lesezeit

Mit der Typemark API können Skripte und CI deine Projekte und ihre Veröffentlichungen auslesen, zum Beispiel um auf den Abschluss einer Veröffentlichung zu warten, bevor ein Release rausgeht. Sie ist in jedem Tarif enthalten.

Um Dokumentation vom Terminal oder aus CI herunterzuladen, zu bearbeiten und zu veröffentlichen, nutze die Typemark CLI. Sie basiert auf dieser API und übernimmt die Synchronisierung und Konfliktbehandlung für dich.

API-Token erstellen

  1. Konto öffnen

    Klicke unten in der Seitenleiste des Dashboards auf deinen Namen und dann auf Konto.

  2. Token benennen

    Gib unter API-Tokens dem Token einen Namen, der angibt, wo er verwendet wird, zum Beispiel GitHub Actions.

  3. Ablauf festlegen

    Wähle 30 Tage, 90 Tage, ein Jahr oder nie. Wenn ein Token abläuft, funktionieren Anfragen damit nicht mehr.

  4. Kopieren

    Klicke auf Token erstellen und kopiere das Token. Es beginnt mit tmk_.

Ein Token handelt in deinem Namen. Es kann jedes Projekt lesen, dessen Eigentümer du bist oder dessen Mitglied du bist, mit deiner Rolle in jedem Projekt. Halte es aus Code und allem Öffentlichen heraus.

Token widerrufen

Klicke auf der Seite Konto neben dem Token auf Widerrufen. Alles, was es verwendet, funktioniert sofort nicht mehr. Die Liste zeigt, wann jedes Token zuletzt verwendet wurde, sodass du erkennen kannst, welche nicht mehr gebraucht werden.

Anfrage senden

Sende das Token im Header Authorization. Alle Endpunkte liegen unter 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 ist free, pro oder business. business ist der Enterprise-Tarif: Die API behält den früheren Namen des Tarifs bei, damit Skripte, die ihn prüfen, weiterhin funktionieren.

Endpunkte

MethodePfadLiefert
GET/userDen Benutzer des Tokens, seinen Tarif und das Token selbst
GET/projectsAlle Projekte, deren Eigentümer du bist oder deren Mitglied du bist
GET/projects/{slug}Ein Projekt mit seiner Seitenanzahl und der letzten Veröffentlichung
POST/projectsErstellt ein Projekt. Wird von typemark create verwendet.
GET/projects/{slug}/deploymentsLetzte Veröffentlichungen, neueste zuerst
GET/projects/{slug}/deployments/{id}Eine Veröffentlichung
GET/projects/{slug}/filesAlle Dateien des Projekts mit ihrer Git-Blob-ID und dem Commit, aus dem sie stammen
GET/projects/{slug}/archiveDie Dateien des Projekts als .tar.gz. Übergib sha für einen bestimmten Commit.
POST/projects/{slug}/pushÄndert, ergänzt oder löscht Dateien als einen Commit und veröffentlicht dann. Wird von typemark push verwendet.
POST/migrate/mintlifyKonvertiert eine Mintlify-docs.json oder mint.json in typemark.json. Wird von typemark migrate verwendet.
POST/migrate/gitbook, /migrate/readmeKonvertiert einen GitBook-Space oder ein ReadMe-Projekt in Typemark-Seiten und typemark.json. Wird von typemark migrate verwendet.
POST/openapi/pagesDie Seiten, die Typemark aus einer OpenAPI-Spezifikation erzeugt: Sende source (ihr Pfad in typemark.json), content (ihr Text) und group. Wird von typemark dev verwendet. Es wird nichts gespeichert.
DELETE/tokenWiderruft das Token, das die Anfrage gesendet hat

Projekte

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 liefert für jedes Projekt dieselben Felder, jedoch ohne pages_count, has_unpublished_changes und last_deployment.

Projekt erstellen

curl https://typemark.dev/api/v1/projects \
  -H "Authorization: Bearer $TYPEMARK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Docs", "slug": "acme-docs" }'

Erstellt ein Projekt, dessen Eigentümer du bist, genauso wie Neues Projekt im Dashboard: eine typemark.json und ein paar Startseiten, wobei die Seite bis zur Veröffentlichung offline bleibt. slug ist optional; ohne ihn wird er aus dem Namen erzeugt. Die Antwort ist 201 mit dem Projekt in derselben Form wie GET /projects/{slug}.

StatusCodeBedeutung
403project_limitDein Tarif hat keinen Platz für ein weiteres Projekt. Der Fehler enthält upgrade_url.
403unconfirmedBestätige zuerst deine E-Mail-Adresse
422slug_takenEin anderes Projekt hat diesen Slug
422invalidDer Name ist leer, oder der Slug besteht nicht nur aus Kleinbuchstaben, Ziffern und Bindestrichen oder ist nicht verwendbar. Der Fehler enthält field.
rolestring

Deine Rolle im Projekt: owner, editor oder viewer. Siehe Teammitglieder.

lockedboolean

true, wenn das Projekt schreibgeschützt ist, weil der Tarif des Eigentümers es nicht abdeckt. Siehe Abrechnung.

repo_modestring

managed, wenn Typemark das Repository hostet, connected, wenn es mit GitHub synchronisiert wird. github_repo ist bei verbundenen Projekten gesetzt.

deploy_modestring

auto oder manual. Siehe Veröffentlichung.

deploy_statusstring

Der letzte Build: pending, building, live oder failed.

site_statusstring

live, wenn Leser die Seite sehen können, offline, wenn sie ausgeblendet ist.

urlstring

Wo Leser die Seite finden: deine eigene Domain, sobald sie verifiziert ist, andernfalls https://{slug}.typemark.dev.

has_unpublished_changesboolean

Im manuellen Veröffentlichungsmodus true, wenn es Änderungen gibt, die noch nicht veröffentlicht wurden.

Veröffentlichungen

Jede Veröffentlichung der Seite ist eine Deployment. Übergib limit, um festzulegen, wie viele du zurückerhältst: standardmäßig 20, maximal 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 oder failed. Bei failed erklärt error_message den Grund.

Beispiel: In CI auf eine Veröffentlichung warten

Nachdem du Dokumentationsänderungen zu GitHub gepusht hast, warte, bis Typemark sie veröffentlicht hat:

#!/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

Fehler

Fehler werden als JSON mit einem prüfbaren Code und einer anzeigbaren Meldung zurückgegeben:

{
  "error": {
    "code": "not_found",
    "message": "Not found."
  }
}
StatusCodeBedeutung
400bad_requestEin erforderlicher Parameter fehlt
401unauthorizedDas Token fehlt, ist falsch, widerrufen oder abgelaufen
403forbiddenDeine Rolle im Projekt erlaubt dies nicht, zum Beispiel ein Push durch einen Viewer
403plan_limitDer Tarif des Projekteigentümers umfasst dies nicht. Der Fehler enthält feature und upgrade_url.
403project_limitProjekt erstellen: Dein Tarif hat keinen Platz für ein weiteres. Der Fehler enthält upgrade_url.
403unconfirmedProjekt erstellen: Bestätige zuerst deine E-Mail-Adresse
404not_foundDas Projekt oder die Veröffentlichung existiert nicht, oder du bist kein Mitglied des Projekts
409conflictEin Push ändert Dateien, die sich seit base_sha auch in Typemark geändert haben. Der Fehler listet sie in conflicts auf.
409stale_baseEin Push basiert auf einem Commit, den Typemark nicht hat. Ziehe das Projekt erneut und pushe dann.
409connected_repoDas Projekt synchronisiert sich mit GitHub, daher gehen Pushes stattdessen zu GitHub
409busyEine andere Änderung am Projekt wird gerade gespeichert. Versuche es gleich noch einmal.
413too_largeEin Push überschreitet die Grenzen: 500 Dateien, 10 MB pro Datei, 50 MB pro Push, 100 MB pro Projekt. Eine OpenAPI-Spezifikation über 10 MB.
422slug_taken, invalidProjekt erstellen: Der Slug ist vergeben, oder Name bzw. Slug ist ungültig (field gibt an, welcher)
422invalid_specEine OpenAPI-Spezifikation, die nicht geparst werden kann. Die Meldung sagt, wo.
422invalid_pathEin Push nennt einen Pfad, den Typemark nicht schreibt: leer, beginnend mit /, mit einem Backslash, . oder .. darin oder innerhalb von .git/ oder .typemark/
422not_mintlify, not_gitbook, not_readmeMigration: Die Dateien sehen nicht wie eine Mintlify-Konfiguration, ein GitBook-Space oder ein ReadMe-Projekt aus
426cli_outdatedDie Typemark CLI ist für die API zu alt. Der hint erklärt, wie du aktualisierst. Nur Anfragen, die eine CLI-Version angeben, erhalten dies.
429Zu viele Anfragen. Warte so viele Sekunden, wie im Header Retry-After stehen.
503git_errorDas Repository des Projekts konnte nicht gelesen oder geschrieben werden. Versuche es gleich noch einmal.

Limits

Jede IP-Adresse kann 300 API-Anfragen pro Minute stellen, darunter höchstens 30 Pushes, 30 Archiv-Downloads und 30 OpenAPI-Spezifikationen.