adds cloud docs

docs/cloud.md

@@ -91,12 +91,70 @@ All requests contain a header `X-Hocuspocus-Signature-256` which signs the entir
 }
 ```
 
-### Screenshots
+
+## API
+
+Each Tiptap Collab instance comes with an API for the most common operations. Is is provided directly by your Tiptap Collab instance, so it's available under your custom URL:
+
+`https://YOUR_APP_ID.collab.tiptap.cloud/`
+
+Authentication is done using an admin secret which you can find in your collab [settings area](https://collab.tiptap.dev/). The secret has to be sent as an `Authorization` header.
+If your document identifier contains a slash (`/`), just make sure that you encode it as `%2F` (e.g. using javascripts `encodeURIComponent`).
+
+### POST /api/documents/:identifier
+
+This call takes a binary yjs update message (an existing Ydoc on your side must be encoded using `Y.encodeStateAsUpdate`) and creates a document. This can be used to seed documents before a user connects to the Tiptap Collab server.
+
+```bash
+curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
+--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
+--data '@yjsUpdate.binary.txt'
+
+// returns either http status 204 if the document was created successfully
+// or http status 409 if the document already exists (if you wish to overwrite it, just delete it first)
+```
+
+### GET /api/documents/:identifier?format=:format&fragment=:fragment
+
+This call exports the given document (all fragments) in json format. We are exporting either the current in-memory version (in case the document is currently open on your server, or we fetch the most recent version from the database).
+
+`format` supports either `yjs` or `json`, default=`json`
+
+If you choose the `yjs` format, you'll get the binary Y.js update message (created using `Y.encodeStateAsUpdate`)
+
+`fragment` can be an array of (`fragment=a&fragment=b`) or a single fragment that you want exported. By default we're exporting all fragments. Note that this is only considered when using `json` format, otherwise you'll always get the entire Y.doc.
+
+```bash
+curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
+--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
+
+// returns either http status 200 and the requested document
+// or http status 404 if the document was not found
+```
+
+### DELETE /api/documents/:identifier
+
+This simply deletes a document from the server after terminating any open connection to the document.
+
+```bash
+curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
+--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'
+
+// returns either http status 204 if the document was deleted successfully
+// or http status 404 if the document was not found
+```
+
+### ANY /api/
+
+Need something else? Hit us up and we'll see what we can do (links below)
+
+
+## Screenshots
 
 [![Cloud Documents](https://tiptap.dev/images/docs/server/cloud/documents.png)](https://tiptap.dev/images/docs/server/cloud/documents.png)
 
 [![Cloud Settings](https://tiptap.dev/images/docs/server/cloud/settings.png)](https://tiptap.dev/images/docs/server/cloud/settings.png)
 
-### Need anything else?
+## Need anything else?
 
 Contact us on [Discord](https://tiptap.dev/discord) or send an email to [humans@tiptap.dev](mailto:humans@tiptap.dev).