Schicken Sie eine Word-Datei, eine Webseite, eine Tabelle oder schlichtes Markdown, und es wird ein Dokument in Ihrem Konto. Zurück bekommen Sie es als Markdown, HTML, Word oder PDF, oder als Link, den jemand öffnen kann.
Ein Skript erreicht dasselbe Konto über HTTP. `POST /api/v1/documents` nimmt eine Datei als Request-Body und wandelt sie beim Eingang in Markdown um. Das Ergebnis bleibt in Ihrem Konto, wo es sich in einem anderen Format abrufen, mit neuem Text versehen, in einen Ordner legen oder teilen lässt.
Gespeichert wird alles als Markdown, darum lässt sich ein Dokument auf vier Arten zurücklesen. `GET /api/v1/documents/:id` antwortet mit JSON, das die Markdown-Quelle und die Angaben zum Dokument enthält; hängt man `.html`, `.docx` oder `.pdf` an dieselbe Adresse, kommt stattdessen eine eigenständige Webseite, eine Word-Datei oder ein PDF.
Einen separaten Aufruf nur zum Umwandeln gibt es nicht. Ein umgewandeltes Dokument ist ein Dokument im Konto und belegt dessen Platz wie jedes andere — genau das macht das Ergebnis zu etwas, das eine zweite Anfrage wiederfindet.
`?kind=` benennt die Umwandlung, mit denselben Namen wie die Seiten dieser Website; ohne ihn ist der Body Markdown. `html-to-markdown`, `csv-to-markdown` — auch für eine `.tsv`, erkannt am Namen —, `json-to-markdown`, `text-to-markdown` und `evernote-to-markdown` lesen den Body als Text.
`word-to-markdown`, `excel-to-markdown`, `powerpoint-to-markdown`, `epub-to-markdown`, `odt-to-markdown`, `rtf-to-markdown` sowie `notion-to-markdown`, `confluence-to-markdown` und `obsidian-to-markdown` für Export-Zips lesen ihn als die Bytes der Datei; eine `.docx` oder eine `.zip` wird also genau so geschickt, wie sie auf der Festplatte liegt.
Markdown in die andere Richtung ist die Leseseite. Schicken Sie Markdown ohne `kind` und fragen Sie dann nach `.html` für eine fertige Seite mit eingebetteten Styles — `?theme=dark` für die dunkle Palette —, nach `.docx` für Word mit Words eigenen Überschriftenformatvorlagen oder nach `.pdf`.
Ein Dokument umfasst höchstens 4 MB, ob Markdown oder die umzuwandelnde Datei; ein größeres wird mit einer 413 beantwortet.
Erstellen Sie im Kontomenü unter „API-Schlüssel“ einen Schlüssel und senden Sie ihn als `Authorization: Bearer tp_live_…`. Er wird einmal angezeigt und nur als Hash gespeichert. Ein Schlüssel erreicht Dokumente, Ordner und Freigaben, aber nie das Konto oder die Schlüssel selbst; ein geleakter Schlüssel kann sich also keinen Ersatz ausstellen und Sie nicht aussperren. Ein Widerruf wirkt ab der nächsten Anfrage.
Eine angemeldete Browser-Sitzung funktioniert an denselben Endpunkten, sodass sich ein `GET` im Browser ausprobieren lässt, bevor es überhaupt einen Schlüssel gibt. Das Präfix `tp_live_` macht einen Schlüssel überall leicht auffindbar, wo er nicht hingehört — im falschen Eingabefeld oder in einem Commit.
`POST /api/v1/documents` legt eines an. `?name=` benennt es, `?share=link` oder `?share=people` veröffentlicht es in derselben Anfrage und gibt die Adresse zurück, `?expires_at=` beendet diesen Link zu einem Zeitpunkt nach ISO 8601, und `?folder=` legt es in einen Ordner.
`GET /api/v1/documents` listet die neuesten 5.000, und `?q=` durchsucht ihren Text. `PUT /api/v1/documents/:id` ersetzt den Text eines Dokuments und behält seine id und seinen Link; der alte Text bleibt als eine von zehn Revisionen erhalten. `DELETE` legt ein Dokument für 14 Tage in den Papierkorb, und `/api/v1/trash` listet und stellt wieder her, was darin liegt.
`PUT /api/v1/documents/:id/share` setzt den Modus, die benannten Adressen, ein Ablaufdatum und ein Passwort, das im Body reist und nie in der Adresse. `GET …/views` listet die Aufrufe des Links, `/api/v1/folders` legt Ordner an, benennt, verschiebt, teilt und löscht sie, `POST /api/v1/documents/:id/summary` schreibt eine kurze Zusammenfassung, und `GET /api/v1/usage` sagt, wie viel Platz noch bleibt.
Ein Fehler ist JSON, `{ "error": "…" }`, mit einem Satz zum Lesen und einem Status, der meint, was er sagt: 400 für eine Anfrage, mit der der Endpunkt nichts anfangen kann, 401 für einen unbekannten oder widerrufenen Schlüssel, 403, wenn das Konto keinen Platz mehr hat oder noch nicht veröffentlichen darf, 404 für ein Dokument, das nicht Ihnen gehört, 410 für eine Quelle, die verschwunden ist, 413 für ein Dokument über 4 MB, 429 für zu viele Anfragen.
Jeder Schlüssel darf 60 Anfragen pro Minute stellen; darüber hinaus trägt die 429 einen `Retry-After`-Header, der sagt, wie lange zu warten ist. Ein Konto fasst 5.000 Dokumente und 250 MB. Wer eine Grenze erreicht, bekommt den Schreibvorgang verweigert und den Grund genannt; gelöscht wird nichts, um Platz zu schaffen.
Ein Empfänger kann benachrichtigt werden, statt abzufragen. Webhooks, im Kontomenü eingetragen, senden ein `POST`, wenn ein Dokument angelegt oder mit benannten Personen geteilt wird, signiert mit HMAC-SHA256 im Header `x-transformpipe-signature`. Verwaltet werden sie nur aus einer angemeldeten Sitzung, damit ein geleakter Schlüssel sich nicht in einen Strom aller künftigen Dokumente verwandeln kann.