API Overview on notd

Core Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Pages

Pages are top-level containers for notes. Each page has a unique name and can contain multiple notes.

Notes

Notes are the core content blocks that belong to pages. Notes can be nested under other notes, creating a hierarchical structure.

Properties

Properties are metadata extracted from content using pattern matching:

{key::value} - Public property (weight 2)
{key:::value} - Internal property (weight 3)
{key::::value} - System log property (weight 4)

Task States

The API supports task status tracking with these states:

Quick Start Examples

Mon, 01 Jan 0001 00:00:00 +0000

1. Create a Page and Add Notes

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# Create a page with notes
curl -X POST http://localhost/api/v1/append_to_page \
 -H "Content-Type: application/json" \
 -d '{
 "page_name": "My Project",
 "notes": [
 {
 "content": "Project overview {priority::high}",
 "order_index": 1
 },
 {
 "content": "TODO Research competitors",
 "order_index": 2
 }
 ]
 }'

2. Search for Tasks

1
2


# Find all TODO tasks
curl "http://localhost/api/v1/search?tasks=TODO&page=1&per_page=10"

3. Get Recent Pages

1
2


# Get the 7 most recently updated pages
curl "http://localhost/api/v1/recent_pages"

4. Full-text Search

1
2


# Search for notes containing "project"
curl "http://localhost/api/v1/search?q=project&page=1&per_page=10"

5. Batch Operations

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# Create multiple notes in one request
curl -X POST http://localhost/api/v1/notes \
 -H "Content-Type: application/json" \
 -d '{
 "action": "batch",
 "operations": [
 {
 "type": "create",
 "payload": {
 "page_id": 1,
 "content": "First note {tags::important}",
 "order_index": 1
 }
 },
 {
 "type": "create",
 "payload": {
 "page_id": 1,
 "content": "Second note",
 "order_index": 2
 }
 }
 ]
 }'

Advanced Features

Mon, 01 Jan 0001 00:00:00 +0000

notd includes several advanced features that leverage both the backend API and frontend capabilities to create powerful workflows and automation.

Frontend-Driven Features

Dynamic SQL Queries

The frontend can execute SQL queries embedded directly in notes, providing powerful data analysis and reporting capabilities:

1

SQL{SELECT id FROM Notes WHERE content LIKE '%important%'}

This creates dynamic content that updates automatically when underlying data changes.

Query Examples

Project Dashboard:

Best Practices

Mon, 01 Jan 0001 00:00:00 +0000

1. Use Batch Operations

For multiple note operations, use batch operations instead of individual requests:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// Good
const batchResponse = await fetch('/api/v1/notes', {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({
 action: 'batch',
 operations: [
 { type: 'create', payload: {...} },
 { type: 'update', payload: {...} }
 ]
 })
});

// Avoid
await fetch('/api/v1/notes', { method: 'POST', body: JSON.stringify({...}) });
await fetch('/api/v1/notes', { method: 'POST', body: JSON.stringify({...}) });

2. Include Parent Properties

When fetching notes, consider including parent properties for context:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Common Issues

Database Locked Errors
- The API will retry automatically
- If persistent, check for long-running transactions
Property Not Found
- Properties are extracted from content automatically
- Check that your content uses the correct syntax: {key::value}
Search Not Working
- Ensure search terms are properly URL-encoded
- Check that the content contains the search terms
Template Processing Errors
- Verify template syntax
- Check that placeholder names are valid

Debug Mode

Enable debug logging by checking the server logs for detailed error information.

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Version 1.0.0

Initial API release
Full CRUD operations for pages and notes
Property system with pattern matching
Full-text search capabilities
File attachment support
Template system
Webhook notifications
Batch operations for efficiency