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
Konto öffnen
Klicke unten in der Seitenleiste des Dashboards auf deinen Namen und dann auf Konto.
Token benennen
Gib unter API-Tokens dem Token einen Namen, der angibt, wo er verwendet wird, zum Beispiel
GitHub Actions.Ablauf festlegen
Wähle 30 Tage, 90 Tage, ein Jahr oder nie. Wenn ein Token abläuft, funktionieren Anfragen damit nicht mehr.
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
| Methode | Pfad | Liefert |
|---|---|---|
GET | /user | Den Benutzer des Tokens, seinen Tarif und das Token selbst |
GET | /projects | Alle 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 | /projects | Erstellt ein Projekt. Wird von typemark create verwendet. |
GET | /projects/{slug}/deployments | Letzte Veröffentlichungen, neueste zuerst |
GET | /projects/{slug}/deployments/{id} | Eine Veröffentlichung |
GET | /projects/{slug}/files | Alle Dateien des Projekts mit ihrer Git-Blob-ID und dem Commit, aus dem sie stammen |
GET | /projects/{slug}/archive | Die 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/mintlify | Konvertiert eine Mintlify-docs.json oder mint.json in typemark.json. Wird von typemark migrate verwendet. |
POST | /migrate/gitbook, /migrate/readme | Konvertiert einen GitBook-Space oder ein ReadMe-Projekt in Typemark-Seiten und typemark.json. Wird von typemark migrate verwendet. |
POST | /openapi/pages | Die 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 | /token | Widerruft 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}.
| Status | Code | Bedeutung |
|---|---|---|
403 | project_limit | Dein Tarif hat keinen Platz für ein weiteres Projekt. Der Fehler enthält upgrade_url. |
403 | unconfirmed | Bestätige zuerst deine E-Mail-Adresse |
422 | slug_taken | Ein anderes Projekt hat diesen Slug |
422 | invalid | Der Name ist leer, oder der Slug besteht nicht nur aus Kleinbuchstaben, Ziffern und Bindestrichen oder ist nicht verwendbar. Der Fehler enthält field. |
rolestringDeine Rolle im Projekt: owner, editor oder viewer. Siehe Teammitglieder.
lockedbooleantrue, wenn das Projekt schreibgeschützt ist, weil der Tarif des Eigentümers es nicht abdeckt. Siehe Abrechnung.
repo_modestringmanaged, wenn Typemark das Repository hostet, connected, wenn es mit GitHub synchronisiert wird. github_repo ist bei verbundenen Projekten gesetzt.
deploy_modestringauto oder manual. Siehe Veröffentlichung.
deploy_statusstringDer letzte Build: pending, building, live oder failed.
site_statusstringlive, wenn Leser die Seite sehen können, offline, wenn sie ausgeblendet ist.
urlstringWo Leser die Seite finden: deine eigene Domain, sobald sie verifiziert ist, andernfalls https://{slug}.typemark.dev.
has_unpublished_changesbooleanIm 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"
}
]
}
statusstringpending, 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."
}
}
| Status | Code | Bedeutung |
|---|---|---|
400 | bad_request | Ein erforderlicher Parameter fehlt |
401 | unauthorized | Das Token fehlt, ist falsch, widerrufen oder abgelaufen |
403 | forbidden | Deine Rolle im Projekt erlaubt dies nicht, zum Beispiel ein Push durch einen Viewer |
403 | plan_limit | Der Tarif des Projekteigentümers umfasst dies nicht. Der Fehler enthält feature und upgrade_url. |
403 | project_limit | Projekt erstellen: Dein Tarif hat keinen Platz für ein weiteres. Der Fehler enthält upgrade_url. |
403 | unconfirmed | Projekt erstellen: Bestätige zuerst deine E-Mail-Adresse |
404 | not_found | Das Projekt oder die Veröffentlichung existiert nicht, oder du bist kein Mitglied des Projekts |
409 | conflict | Ein Push ändert Dateien, die sich seit base_sha auch in Typemark geändert haben. Der Fehler listet sie in conflicts auf. |
409 | stale_base | Ein Push basiert auf einem Commit, den Typemark nicht hat. Ziehe das Projekt erneut und pushe dann. |
409 | connected_repo | Das Projekt synchronisiert sich mit GitHub, daher gehen Pushes stattdessen zu GitHub |
409 | busy | Eine andere Änderung am Projekt wird gerade gespeichert. Versuche es gleich noch einmal. |
413 | too_large | Ein Push überschreitet die Grenzen: 500 Dateien, 10 MB pro Datei, 50 MB pro Push, 100 MB pro Projekt. Eine OpenAPI-Spezifikation über 10 MB. |
422 | slug_taken, invalid | Projekt erstellen: Der Slug ist vergeben, oder Name bzw. Slug ist ungültig (field gibt an, welcher) |
422 | invalid_spec | Eine OpenAPI-Spezifikation, die nicht geparst werden kann. Die Meldung sagt, wo. |
422 | invalid_path | Ein Push nennt einen Pfad, den Typemark nicht schreibt: leer, beginnend mit /, mit einem Backslash, . oder .. darin oder innerhalb von .git/ oder .typemark/ |
422 | not_mintlify, not_gitbook, not_readme | Migration: Die Dateien sehen nicht wie eine Mintlify-Konfiguration, ein GitBook-Space oder ein ReadMe-Projekt aus |
426 | cli_outdated | Die 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. |
429 | Zu viele Anfragen. Warte so viele Sekunden, wie im Header Retry-After stehen. | |
503 | git_error | Das 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.