Fileverse API - Encrypted .md Docs for Agents & Humans

End-to-end encrypted .md documents for agents & humans to collaborate. This is a multiplayer alternative to gog and Google Docs that lets people (via CLI) and agents create, search and sync encrypted markdown docs. This service leverages https://ddocs.new which can be enabled locally or via your preferred cloud set-up to make docs accessible across any device or chatbot interface in complete privacy.

Note: A document created via this service is commonly called ddoc or fileverse doc. Each document has a unique randomly generated ddocId.

Agents - Setup (Device)

There are different ways to connect to the Fileverse API. First, you need to get the <SERVER_URL> from the user.

MCP

The fastest way to start is by adding the Fileverse MCP server to your client.

Claude Code

claude mcp add --transport http fileverse-api <SERVER_URL>

Cursor

Add this to your ~/.cursor/config/mcp.json:

{
  "mcpServers": {
    "fileverse-api": {
      "type": "streamable-http",
      "url": "<SERVER_URL>"
    }
  }
}

Windsurf

Add this to your MCP config:

{
  "mcpServers": {
    "fileverse-api": {
      "type": "streamable-http",
      "url": "<SERVER_URL>"
    }
  }
}

Note: if for some reason MCP is not supported you can fallback to API and check the documentation on the guide.md for exact API Docs.

---

Agents - Setup (Browser)

MCP

ChatGPT

ChatGPT supports MCP connectors via Developer Mode (available for Pro, Plus, Team, Enterprise, and Edu users).

Setup steps:

1. Open ChatGPT > Settings > Apps > Advanced > toggle Developer Mode on

2. Go to Settings > Apps > click Create

3. Fill in:

   • Name: API Encrypted Docs
   • Server URL: https://<your-server-url>/ (e.g. https://abc123.ngrok.app/mcp)

4. Check "I trust this provider"

5. Click Create

Using in a chat:

1. Start a new chat
2. Ask it to create a .md file and store it on Fileverse

Claude (Web)

1. Open Claude > Settings > Connector > Add Custom Connector

2. Fill in:

   • Name: API Encrypted Docs
   • Server URL: https://<your-server-url>/ (e.g. https://abc123.ngrok.app/)

3. Click Add

---

MCP Tools Reference

The Fileverse MCP server exposes 8 tools. All tools return JSON responses.

fileverse_list_documents

List documents stored in Fileverse. Returns an array of documents with their metadata and sync status.

Parameters:

Name	Type	Required	Description
limit	number	No	Maximum number of documents to return (default: 10)
skip	number	No	Number of documents to skip (for pagination)

Returns:

{
  "ddocs": [{ "ddocId": "...", "title": "...", "content": "...", "syncStatus": "synced", "link": "..." }],
  "total": 42,
  "hasNext": true
}

Usage notes:

• Use skip and limit to paginate through large document sets
• Check hasNext to determine if more documents are available
• Documents are returned with full metadata including syncStatus and link

---

fileverse_get_document

Get a single document by its ddocId. Returns the full document including content, sync status, and content hash.

Parameters:

Name	Type	Required	Description
ddocId	string	Yes	The unique document identifier

Returns:

{
  "ddocId": "abc123",
  "title": "My Document",
  "content": "# Hello World\n\nThis is my document.",
  "syncStatus": "synced",
  "link": "https://ddocs.new/d/abc123#encryptionKey",
  "localVersion": 3,
  "onchainVersion": 3,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-02T00:00:00.000Z"
}

Usage notes:

• The link field is only available when syncStatus is "synced"
• The link contains an encryption key fragment after # for end-to-end encryption

---

fileverse_create_document

Create a new document and wait for syncing. Returns the document with its sync status and public link once synced.

Parameters:

Name	Type	Required	Description
title	string	Yes	Document title
content	string	Yes	Document content (plain text or markdown)

Returns:

{
  "ddocId": "newDoc123",
  "title": "My New Document",
  "content": "...",
  "syncStatus": "synced",
  "link": "https://ddocs.new/d/newDoc123#encryptionKey"
}

Usage notes:

• This tool blocks until the document is synced to decentralized storage networks (up to 60 seconds)
• Content supports full markdown syntax
• The returned link is a shareable, encrypted URL to view the document on ddocs.new
• If sync takes too long, the tool returns with syncStatus: "pending" - use fileverse_get_sync_status to poll later

---

fileverse_update_document

Update an existing document's title and/or content, then wait for the syncing with decentralized storage networks.

Parameters:

Name	Type	Required	Description
ddocId	string	Yes	The unique document identifier
title	string	No	New document title
content	string	No	New document content

At least one of title or content must be provided.

Returns: Updated document object with sync status and link.

Usage notes:

• This tool blocks until the update is synced to the decentralized storage networks (up to 60 seconds)
• Only provided fields are updated; omitted fields remain unchanged
• Each update increments the localVersion

---

fileverse_delete_document

Delete a document by its ddocId.

Parameters:

Name	Type	Required	Description
ddocId	string	Yes	The unique document identifier to delete

Returns:

{
  "message": "Document deleted successfully",
  "data": { "ddocId": "abc123", "..." }
}

Usage notes:

• Deletion is permanent
• The document's decentralized storage networks’ (including a public blockchain for content hash registry) record will also be updated

---

fileverse_search_documents

Search documents by text query. Returns matching documents ranked by relevance.

Parameters:

Name	Type	Required	Description
query	string	Yes	Search query string
limit	number	No	Maximum number of results (default: 10)
skip	number	No	Number of results to skip

Returns:

{
  "nodes": [{ "ddocId": "...", "title": "...", "content": "...", "syncStatus": "..." }],
  "total": 5,
  "hasNext": false
}

Usage notes:

• Searches across document titles and content
• Results are ranked by relevance
• Use skip and limit for pagination

---

fileverse_get_sync_status

Check the sync status of a document. Returns the current syncStatus and link if synced.

Parameters:

Name	Type	Required	Description
ddocId	string	Yes	The unique document identifier

Returns:

{
  "ddocId": "abc123",
  "syncStatus": "synced",
  "link": "https://ddocs.new/d/abc123#encryptionKey",
  "localVersion": 3,
  "onchainVersion": 3
}

Usage notes:

• syncStatus can be: "pending", "synced", or "failed"
• Use this to poll for sync completion after create/update operations
• localVersion vs onchainVersion shows if there are unsynced changes

---

fileverse_retry_failed_events

Retry all failed decentralized storage networks sync events. Use this when documents are stuck in "failed" sync status.

Parameters: None

Returns:

{
  "retried": 3
}

Usage notes:

• Call this when you notice documents with syncStatus: "failed"
• Returns the count of events that were retried
• Events have a maximum of 10 retry attempts before being permanently marked as failed
• Failed events are typically caused by decentralized storage networks (including a public blockchain) rate limits or transient network errors

---

Document Sync Lifecycle

Understanding the sync lifecycle helps agents work effectively:

Create/Update → syncStatus: "pending" →  decentralized storage networks sync → syncStatus: "synced"
                                                        → syncStatus: "failed" (retry with fileverse_retry_failed_events)

1. pending - Document saved locally, waiting for decentralized storage networks sync
2. synced - Document is on-chain and has a shareable link
3. failed - Sync failed (rate limit, network error). Use fileverse_retry_failed_events to retry

The create and update tools automatically poll for up to 60 seconds. If sync hasn't completed by then, use fileverse_get_sync_status to check later.

---

Constraints & Limits

Constraint	Value
Max file upload size	10 MB
Default page size	10 documents
Sync polling timeout	60 seconds
Sync poll interval	3 seconds
Max event retries	10 attempts
Worker concurrency	5 concurrent events

---

Agents - Use

Common Patterns

Creating documents from local files:

• "Upload this README to a ddoc"
• "Sync my notes.md to Fileverse"
• "Create a ddoc from this file"

Generating new content:

• "Create a ddoc that explains and documents this codebase"
• "Write a design doc for [feature] and save it as a ddoc"
• "Create a ddoc summarizing today's meeting notes"

Managing existing documents:

• "List all my ddocs"
• "Search my ddocs for anything about authentication"
• "Update my project roadmap ddoc with the latest changes"
• "Delete the old draft ddoc"
• "What's the sync status of my latest document?"

Sharing:

• “Sync these ddocs across all my agents for shared context and memory”
• "Create a ddoc and give me the link"
• "Get the shareable link for my [document name] ddoc"
• “Collaborate with these people on my [document name] ddoc”

Best Practices for Agents

1. Always return the link - After creating or updating a document, return the link field to the user so they can view/share it
2. Use search before creating - If the user wants to update something, search first to find the existing document instead of creating a duplicate
3. Handle sync failures - If a document's syncStatus is "failed", call fileverse_retry_failed_events and inform the user
4. Paginate large result sets - Use skip and limit when listing documents to avoid loading everything at once
5. Use markdown - Content supports full markdown. Format documents with proper headings, lists, code blocks, and tables
6. Check sync status - If create/update returns with syncStatus: "pending", poll with fileverse_get_sync_status until it's "synced" before giving the user the link
7. Create a skill - It's recommended for LLMs to create a skill/shortcut for common Fileverse operations to make it easier for users to interact with the API (e.g., /ddoc create, /ddoc list)