Envía un archivo de Word, una página web, una hoja de cálculo o Markdown sin más, y se convierte en un documento de tu cuenta. Pídelo de vuelta en Markdown, HTML, Word o PDF, o como un enlace que alguien pueda abrir.
Un script llega a la misma cuenta por HTTP. `POST /api/v1/documents` recibe un archivo como cuerpo de la petición y lo convierte a Markdown al llegar. El resultado se guarda en tu cuenta, donde se puede pedir en otro formato, recibir texto nuevo, archivarse en una carpeta o compartirse.
Todo se guarda como Markdown, así que un documento se lee de cuatro maneras. `GET /api/v1/documents/:id` responde con JSON que trae la fuente Markdown y los datos del documento; añadir `.html`, `.docx` o `.pdf` a la misma dirección devuelve en su lugar una página web autónoma, un archivo de Word o un PDF.
No hay una llamada aparte que solo convierta. Un documento convertido es un documento de la cuenta y ocupa su espacio como cualquier otro, y eso mismo es lo que hace del resultado algo que una segunda petición puede encontrar.
`?kind=` nombra la conversión, con los mismos nombres que las páginas de este sitio; sin él, el cuerpo es Markdown. `html-to-markdown`, `csv-to-markdown` — también un `.tsv`, por su nombre —, `json-to-markdown`, `text-to-markdown` y `evernote-to-markdown` leen el cuerpo como texto.
`word-to-markdown`, `excel-to-markdown`, `powerpoint-to-markdown`, `epub-to-markdown`, `odt-to-markdown`, `rtf-to-markdown`, y `notion-to-markdown`, `confluence-to-markdown` y `obsidian-to-markdown` para los zips de exportación, lo leen como los bytes del archivo, así que un `.docx` o un `.zip` se envía tal como está en el disco.
El Markdown en sentido contrario es el lado de lectura. Envía Markdown sin `kind` y pide después `.html` para una página terminada con sus estilos dentro — `?theme=dark` para la paleta oscura —, `.docx` para un Word con los estilos de título propios de Word, o `.pdf`.
Un documento ocupa como mucho 4 MB, sea el Markdown o el archivo que se convierte; uno mayor recibe un 413.
Crea una clave en el menú de la cuenta, en Claves API, y envíala como `Authorization: Bearer tp_live_…`. Se muestra una sola vez y se guarda solo como hash. Una clave llega a los documentos, las carpetas y los enlaces compartidos, y nunca a la cuenta ni a las propias claves, así que una clave filtrada no puede fabricarse su sustituta ni dejarte fuera; revocarla la detiene en la siguiente petición.
Una sesión de navegador iniciada funciona en los mismos endpoints, así que un `GET` se puede probar en el navegador antes de que exista ninguna clave. El prefijo `tp_live_` hace que una clave sea fácil de encontrar donde no debería estar: pegada en la casilla equivocada o subida a un repositorio.
`POST /api/v1/documents` crea uno. `?name=` le pone nombre, `?share=link` o `?share=people` lo publica en la misma petición y devuelve la dirección, `?expires_at=` termina ese enlace a una hora en ISO 8601, y `?folder=` lo archiva en una carpeta.
`GET /api/v1/documents` enumera los 5.000 más recientes, y `?q=` busca en su texto. `PUT /api/v1/documents/:id` sustituye el texto de un documento y conserva su id y su enlace, con el texto antiguo guardado como una de diez revisiones. `DELETE` manda un documento a la Papelera durante 14 días, y `/api/v1/trash` enumera y restaura lo que hay en ella.
`PUT /api/v1/documents/:id/share` fija el modo, las direcciones nombradas, una fecha de caducidad y una contraseña, que viaja en el cuerpo y nunca en la dirección. `GET …/views` enumera las aperturas del enlace, `/api/v1/folders` crea, renombra, mueve, comparte y borra carpetas, `POST /api/v1/documents/:id/summary` escribe un resumen breve, y `GET /api/v1/usage` dice cuánto espacio queda.
Un error es JSON, `{ "error": "…" }`, con una frase pensada para leerse y un estado que significa lo que dice: 400 para una petición que el endpoint no puede usar, 401 para una clave desconocida o revocada, 403 cuando la cuenta no tiene espacio o aún no puede publicar, 404 para un documento que no es tuyo, 410 para una fuente que ya no está, 413 para un documento de más de 4 MB, 429 para demasiadas peticiones.
Cada clave puede hacer 60 peticiones por minuto; pasado eso, el 429 lleva una cabecera `Retry-After` que dice cuánto esperar. Una cuenta guarda 5.000 documentos y 250 MB. Llegar a un límite hace que se rechace la escritura y se diga por qué; no se borra nada antiguo para hacer sitio.
Un receptor puede recibir avisos en lugar de preguntar. Los webhooks, registrados en el menú de la cuenta, envían un `POST` cuando se crea un documento o se comparte con personas concretas, firmado con HMAC-SHA256 en la cabecera `x-transformpipe-signature`. Solo se gestionan desde una sesión iniciada, para que una clave filtrada no pueda convertirse en un canal de todos los documentos futuros.