✨ Feature Request: API Access to Retrieve Private Markdown Documents Securely

Start by reviewing the existing account settings and authentication entry points, then inspect how documents and permissions are exposed in the application. Define the token-management flow and the two proposed endpoints, including the Markdown versus ProseMirror/BlockNote JSON response choice. Done means securely generated tokens, permission-scoped document access, and documented curl examples for listing and retrieving documents.

Title: Feature Request: Simple Token-Based API Access for Private Documents (Initial Phase)

Feature Request

Is your feature request related to a problem or unsupported use case? Please describe.
Currently, users cannot programmatically retrieve their private documents from Docs without manual intervention. This prevents automation of workflows like backups, content integration, or syncing with external tools while keeping documents private.

Describe the solution you'd like
A minimal, secure API to retrieve documents privately, inspired by Grist’s simplicity:

1. Token Generation:

   • Users can generate a personal API token in their account settings (e.g., under "API Tokens" or "Integrations").
   • Example UI: A button to "Generate new token" with a clear warning about token security.

2. Endpoints:

   • List Documents:

     GET /api/documents  
     

     Returns a simple JSON list of documents the user has access to, with metadata (e.g., id, title, last_modified).

   • Get Document Content:

     GET /api/documents/{document_id}  
     

     Returns the document’s content in Markdown (or raw JSON/HTML if Markdown conversion is complex).

3. Authentication:

   • Token sent via Authorization: Bearer {token} header.
   • Tokens inherit the user’s permissions (e.g., only documents they can view are accessible).

Drawbacks:

• Minimal filtering/pagination for /api/documents initially (can be improved later).
• No support for bulk exports or formats like PDF in this phase.

Describe alternatives you've considered

• Manual UI Exports: Not scalable for automation.
• Web Scraping: Fragile and insecure.
• Complex API Design: Overkill for initial use cases. A minimal MVP aligns better with user needs.

Discovery, Documentation, Adoption, Migration Strategy

• Discovery: Users find the token generator in their profile/account settings.

• Documentation Example:

  ### Retrieve Documents via API (Beta)  
  1. **Generate a token**:  
     Go to **Account Settings → API Tokens → Generate Token**.  
  
  2. **List your documents**:  
     ```bash  
     curl -H "Authorization: Bearer YOUR_TOKEN" https://{instance}/api/documents  
  

  3. Get a document:

     curl -H "Authorization: Bearer YOUR_TOKEN" https://{instance}/api/documents/DOCUMENT_ID  
     

• Adoption: Announce this as a beta feature for developers/automation enthusiasts.

• Security Note: Advise users to store tokens securely and rotate them periodically.

Do you want to work on it through a Pull Request?
Yes, I’d like to collaborate on this after aligning with maintainers on:

• Token storage/management implementation (e.g., Django REST Framework Token).
• Preferred response format (Markdown vs. existing Prosemirror/BlockNote JSON).