Envoyez un fichier Word, une page web, un tableur ou du Markdown brut : il devient un document de votre compte. Récupérez-le en Markdown, HTML, Word ou PDF, ou sous forme de lien que quelqu’un peut ouvrir.
Un script atteint le même compte en HTTP. `POST /api/v1/documents` prend un fichier comme corps de requête et le convertit en Markdown à l’arrivée. Le résultat est conservé dans votre compte, où il peut être récupéré dans un autre format, recevoir un nouveau texte, être rangé dans un dossier ou partagé.
Tout est stocké en Markdown, si bien qu’un document se relit de quatre façons. `GET /api/v1/documents/:id` répond en JSON avec la source Markdown et les informations du document ; ajouter `.html`, `.docx` ou `.pdf` à la même adresse renvoie à la place une page web autonome, un fichier Word ou un PDF.
Il n’existe pas d’appel qui ne ferait que convertir. Un document converti est un document du compte et occupe sa place comme les autres — c’est aussi ce qui fait du résultat quelque chose qu’une deuxième requête retrouve.
`?kind=` nomme la conversion, avec les mêmes noms que les pages de ce site ; sans lui, le corps est du Markdown. `html-to-markdown`, `csv-to-markdown` — un `.tsv` aussi, reconnu à son nom —, `json-to-markdown`, `text-to-markdown` et `evernote-to-markdown` lisent le corps comme du texte.
`word-to-markdown`, `excel-to-markdown`, `powerpoint-to-markdown`, `epub-to-markdown`, `odt-to-markdown`, `rtf-to-markdown`, ainsi que `notion-to-markdown`, `confluence-to-markdown` et `obsidian-to-markdown` pour les zips d’export, le lisent comme les octets du fichier : un `.docx` ou un `.zip` s’envoie tel qu’il est sur le disque.
Le Markdown dans l’autre sens, c’est le côté lecture. Envoyez du Markdown sans `kind`, puis demandez `.html` pour une page finie avec ses styles intégrés — `?theme=dark` pour la palette sombre —, `.docx` pour un Word avec les styles de titre propres à Word, ou `.pdf`.
Un document pèse au plus 4 Mo, qu’il s’agisse du Markdown ou du fichier à convertir ; au-delà, la réponse est une 413.
Créez une clé dans le menu du compte, sous Clés API, et envoyez-la sous la forme `Authorization: Bearer tp_live_…`. Elle n’est affichée qu’une fois et stockée uniquement sous forme de hachage. Une clé atteint les documents, les dossiers et les partages, jamais le compte ni les clés elles-mêmes : une clé divulguée ne peut ni fabriquer sa remplaçante ni vous enfermer dehors, et la révoquer l’arrête dès la requête suivante.
Une session de navigateur connectée fonctionne sur les mêmes points d’entrée, si bien qu’un `GET` s’essaie dans le navigateur avant même qu’une clé existe. Le préfixe `tp_live_` rend une clé facile à repérer partout où elle n’a rien à faire — collée dans le mauvais champ, ou commise dans un dépôt.
`POST /api/v1/documents` en crée un. `?name=` le nomme, `?share=link` ou `?share=people` le publie dans la même requête et renvoie l’adresse, `?expires_at=` met fin à ce lien à une heure au format ISO 8601, et `?folder=` le range dans un dossier.
`GET /api/v1/documents` liste les 5 000 plus récents, et `?q=` cherche dans leur texte. `PUT /api/v1/documents/:id` remplace le texte d’un document en gardant son id et son lien, l’ancien texte étant conservé parmi dix révisions. `DELETE` envoie un document à la Corbeille pour 14 jours, et `/api/v1/trash` liste et restaure ce qui s’y trouve.
`PUT /api/v1/documents/:id/share` définit le mode, les adresses nommées, une date de fin et un mot de passe, qui voyage dans le corps et jamais dans l’adresse. `GET …/views` liste les ouvertures du lien, `/api/v1/folders` crée, renomme, déplace, partage et supprime les dossiers, `POST /api/v1/documents/:id/summary` rédige un court résumé, et `GET /api/v1/usage` indique la place qui reste.
Une erreur est du JSON, `{ "error": "…" }`, avec une phrase faite pour être lue et un statut qui dit ce qu’il veut dire : 400 pour une requête dont le point d’entrée ne peut rien faire, 401 pour une clé inconnue ou révoquée, 403 quand le compte n’a plus de place ou ne peut pas encore publier, 404 pour un document qui n’est pas le vôtre, 410 pour une source disparue, 413 pour un document de plus de 4 Mo, 429 pour trop de requêtes.
Chaque clé peut faire 60 requêtes par minute ; au-delà, la 429 porte un en-tête `Retry-After` qui dit combien de temps attendre. Un compte contient 5 000 documents et 250 Mo. Atteindre une limite fait refuser l’écriture, avec la raison ; rien d’ancien n’est supprimé pour faire de la place.
Un récepteur peut être prévenu au lieu d’interroger. Les webhooks, déclarés dans le menu du compte, envoient un `POST` quand un document est créé ou partagé avec des personnes nommées, signé en HMAC-SHA256 dans l’en-tête `x-transformpipe-signature`. Ils ne se gèrent que depuis une session connectée, pour qu’une clé divulguée ne puisse pas se transformer en flux de tous les documents à venir.