Invia un file Word, una pagina web, un foglio di calcolo o semplice Markdown, e diventa un documento del tuo account. Richiedilo indietro in Markdown, HTML, Word o PDF, oppure come link che qualcuno può aprire.
Uno script raggiunge lo stesso account via HTTP. `POST /api/v1/documents` riceve un file come corpo della richiesta e lo converte in Markdown all’arrivo. Il risultato resta nel tuo account, dove si può richiedere in un altro formato, ricevere testo nuovo, finire in una cartella o essere condiviso.
Tutto è conservato in Markdown, quindi un documento si rilegge in quattro modi. `GET /api/v1/documents/:id` risponde in JSON con la sorgente Markdown e i dati del documento; aggiungendo `.html`, `.docx` o `.pdf` allo stesso indirizzo si ottiene invece una pagina web autonoma, un file Word o un PDF.
Non esiste una chiamata separata che si limiti a convertire. Un documento convertito è un documento dell’account e ne occupa lo spazio come qualsiasi altro, ed è proprio questo a rendere il risultato qualcosa che una seconda richiesta può ritrovare.
`?kind=` indica la conversione, con gli stessi nomi delle pagine di questo sito; senza, il corpo è Markdown. `html-to-markdown`, `csv-to-markdown` — anche un `.tsv`, riconosciuto dal nome —, `json-to-markdown`, `text-to-markdown` ed `evernote-to-markdown` leggono il corpo come testo.
`word-to-markdown`, `excel-to-markdown`, `powerpoint-to-markdown`, `epub-to-markdown`, `odt-to-markdown`, `rtf-to-markdown`, e `notion-to-markdown`, `confluence-to-markdown` e `obsidian-to-markdown` per gli zip di esportazione, lo leggono come i byte del file, così un `.docx` o uno `.zip` si invia esattamente com’è sul disco.
Il Markdown nella direzione opposta è il lato della lettura. Invia Markdown senza `kind`, poi chiedi `.html` per una pagina finita con gli stili al suo interno — `?theme=dark` per la tavolozza scura —, `.docx` per un Word con gli stili di titolo propri di Word, oppure `.pdf`.
Un documento pesa al massimo 4 MB, che sia il Markdown o il file da convertire; uno più grande riceve un 413.
Crea una chiave nel menu dell’account, alla voce Chiavi API, e inviala come `Authorization: Bearer tp_live_…`. Viene mostrata una sola volta e conservata solo come hash. Una chiave raggiunge documenti, cartelle e condivisioni, mai l’account né le chiavi stesse, quindi una chiave trapelata non può crearsi una sostituta né chiuderti fuori; revocarla la ferma alla richiesta successiva.
Una sessione del browser autenticata funziona sugli stessi endpoint, così un `GET` si può provare nel browser prima ancora che esista una chiave. Il prefisso `tp_live_` rende una chiave facile da trovare ovunque non dovrebbe stare — incollata nel campo sbagliato o finita in un commit.
`POST /api/v1/documents` ne crea uno. `?name=` gli dà un nome, `?share=link` o `?share=people` lo pubblica nella stessa richiesta e restituisce l’indirizzo, `?expires_at=` chiude quel link a un’ora in formato ISO 8601, e `?folder=` lo mette in una cartella.
`GET /api/v1/documents` elenca i 5.000 più recenti, e `?q=` cerca nel loro testo. `PUT /api/v1/documents/:id` sostituisce il testo di un documento mantenendo id e link, con il testo vecchio conservato come una di dieci revisioni. `DELETE` sposta un documento nel Cestino per 14 giorni, e `/api/v1/trash` elenca e ripristina ciò che contiene.
`PUT /api/v1/documents/:id/share` imposta la modalità, gli indirizzi indicati, una scadenza e una password, che viaggia nel corpo e mai nell’indirizzo. `GET …/views` elenca le aperture del link, `/api/v1/folders` crea, rinomina, sposta, condivide ed elimina cartelle, `POST /api/v1/documents/:id/summary` scrive un breve riassunto, e `GET /api/v1/usage` dice quanto spazio resta.
Un errore è JSON, `{ "error": "…" }`, con una frase fatta per essere letta e uno stato che significa quello che dice: 400 per una richiesta che l’endpoint non può usare, 401 per una chiave sconosciuta o revocata, 403 quando l’account ha finito lo spazio o non può ancora pubblicare, 404 per un documento che non è tuo, 410 per una sorgente che non c’è più, 413 per un documento oltre i 4 MB, 429 per troppe richieste.
Ogni chiave può fare 60 richieste al minuto; oltre, il 429 porta un’intestazione `Retry-After` che dice quanto aspettare. Un account contiene 5.000 documenti e 250 MB. Raggiungere un limite fa rifiutare la scrittura e ne spiega il motivo; non si cancella nulla di vecchio per fare spazio.
Un ricevitore può essere avvisato invece di interrogare. I webhook, registrati nel menu dell’account, inviano un `POST` quando un documento viene creato o condiviso con persone specifiche, firmato con HMAC-SHA256 nell’intestazione `x-transformpipe-signature`. Si gestiscono solo da una sessione autenticata, perché una chiave trapelata non possa trasformarsi in un flusso di tutti i documenti futuri.