The document pipeline
Diagrams, form fields, composition and retrieval are not four products. They are four things you do to one object, and the object is a document.
Generate
Markdown, HTML, mermaid, an image or a PDF becomes a document.
POST /api/v1/pdfs
Compose
Draw a diagram onto page four of the document that needed explaining.
POST /api/v1/diagrams
Annotate
Put fields on it, send it out, and read the answers back.
POST /api/v1/forms
Retrieve
The same document as .pdf, .png, .svg, .json, .mmd or .drawio.
GET /api/v1/documents/{id}.pdf
Generate#
POST
/api/v1/pdfs
One source field in, one document out. Markdown and HTML are
set as real, selectable text — headings, lists, tables, links,
images, quotes and code — rather than screenshotted, so the file is
kilobytes and its words can be searched and copied. Mermaid
flowchart is parsed and laid out. A picture becomes a page
the size of the picture. Somebody else's PDF is imported page by page so
it stays editable.
Compose#
POST
/api/v1/diagrams
A diagram here is not a picture pasted on top. Connectors attach
to shapes and route around whatever is in the way, and the result is
written into the page as vector artwork. Because the diagram and the
imported PDF are nodes in the same model, a diagram on a document
needs no second feature: fetch .json, add the nodes, put the
model back.
Annotate#
POST
/api/v1/forms
A form is an ordinary document with shape: "field"
nodes on it — which is why a photograph of a paper form can become one.
Rendering it as .pdf writes a genuine AcroForm:
fields anybody can type into in Acrobat, Preview or a browser, machine
readable afterwards. Each submission is stored twice on purpose — as a
row of answers for a program, and as its own document with the answers
set into the page for a person.
Retrieve#
GET
/api/v1/documents/{id}.pdf
Six renderings of one document, made when you ask rather than
stored. There is also a seventh link on every response —
open — which is not an API link at all and is the most useful
one in the list: hand it to a person and they are looking at the
document.
And the URL resolver, which is not part of this#
URL bending mints a docubend address that goes on pointing at
the current file when the file moves or is replaced. It is a Pro and
Enterprise feature of the workspace, and it has no /api/v1
route — it is POST /api/urlbends, which a credential cannot
reach.
It is also the one place in the product that reads a URL you give it, and
the boundaries are code rather than policy: it reads only what a page
declares about its own asset, sends no credential ever, identifies
itself, obeys robots.txt for everything it fetches, stores no
bytes, and reports a refusal rather than routing around it. Sixty lookups
per account per day.
Nothing under /api/v1 fetches a URL on your behalf. A server
that will GET any address it is given is a server that will read a cloud
provider's metadata endpoint. Send the bytes.