Post a Word file, a web page, a spreadsheet or plain Markdown, and it becomes a document in your account. Ask for it back as Markdown, HTML, Word or PDF, or as a link somebody can open.
A script reaches the same account over HTTP. `POST /api/v1/documents` takes a file as the request body and converts it to Markdown on the way in. The result is kept in your account, where it can be fetched in another format, given new text, filed in a folder or shared.
Markdown is the shape everything is stored in, so one document reads back four ways. `GET /api/v1/documents/:id` answers JSON with the Markdown source and the document’s details; adding `.html`, `.docx` or `.pdf` to the same address returns a self-contained web page, a Word file or a PDF instead.
There is no separate convert-only call. A converted document is a document in the account and uses its room like any other, which is also what makes the result something a second request can find.
`?kind=` names the conversion, with the same names as the pages of this site; without it, the body is Markdown. `html-to-markdown`, `csv-to-markdown` — a `.tsv` too, by its name — `json-to-markdown`, `text-to-markdown` and `evernote-to-markdown` read the body as text.
`word-to-markdown`, `excel-to-markdown`, `powerpoint-to-markdown`, `epub-to-markdown`, `odt-to-markdown`, `rtf-to-markdown`, and `notion-to-markdown`, `confluence-to-markdown` and `obsidian-to-markdown` for export zips, read it as the file’s bytes, so a `.docx` or a `.zip` is posted exactly as it sits on disk.
Markdown going the other way is the read side. Post Markdown with no `kind`, then ask for `.html` for a finished page with its styles inside it — `?theme=dark` for the dark palette — `.docx` for Word with Word’s own heading styles, or `.pdf`.
One document carries at most 4 MB, whether that is the Markdown or the file being converted, and a larger one is answered with a 413.
Create a key in the account menu under API keys and send it as `Authorization: Bearer tp_live_…`. It is shown once and stored only as a hash. A key reaches documents, folders and shares, and never the account or the keys themselves, so a leaked key cannot mint its own replacement or lock you out; revoking one stops it on the next request.
A signed-in browser session works on the same endpoints, so a `GET` can be tried in the browser before any key exists. The `tp_live_` prefix makes a key easy to find wherever it should not be — pasted into the wrong box, or committed to a repository.
`POST /api/v1/documents` makes one. `?name=` names it, `?share=link` or `?share=people` publishes it in the same request and returns the address, `?expires_at=` ends that link at an ISO 8601 time, and `?folder=` files it in a folder.
`GET /api/v1/documents` lists the newest 5,000, and `?q=` searches their text. `PUT /api/v1/documents/:id` replaces a document’s text and keeps its id and its link, with the old text kept as one of ten revisions. `DELETE` moves a document to the Trash for 14 days, and `/api/v1/trash` lists and restores what is there.
`PUT /api/v1/documents/:id/share` sets the mode, the named addresses, an end date and a password, which travels in the body and never in the address. `GET …/views` lists the opens of the link, `/api/v1/folders` makes, renames, moves, shares and deletes folders, `POST /api/v1/documents/:id/summary` writes a short summary, and `GET /api/v1/usage` says how much room is left.
An error is JSON, `{ "error": "…" }`, in a sentence meant to be read, under a status that means what it says: 400 for a request the endpoint cannot use, 401 for an unknown or revoked key, 403 when the account is out of room or may not publish yet, 404 for a document that is not yours, 410 for a source that has gone, 413 for a document over 4 MB, 429 for too many requests.
Each key may make 60 requests a minute, and past that the 429 carries a `Retry-After` header saying how long to wait. An account holds 5,000 documents and 250 MB. Reaching a limit refuses the write and says why; nothing older is deleted to make room.
A receiver can be told instead of polling. Webhooks, registered in the account menu, send a `POST` when a document is created or shared with named people, signed with HMAC-SHA256 in the `x-transformpipe-signature` header. They are managed from a signed-in session only, so a leaked key cannot turn itself into a feed of every future document.