660 lines
8.7 KiB
Markdown
660 lines
8.7 KiB
Markdown
# Ironpad API Reference
|
|
|
|
Base URL: `http://localhost:3000`
|
|
|
|
## Notes
|
|
|
|
### List Notes
|
|
|
|
```http
|
|
GET /api/notes
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "20260205-123456",
|
|
"title": "My Note",
|
|
"path": "notes/20260205-123456.md",
|
|
"created": "2026-02-05T12:34:56Z",
|
|
"updated": "2026-02-05T12:34:56Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Create Note
|
|
|
|
```http
|
|
POST /api/notes
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "Optional Title",
|
|
"content": "# My Note\n\nContent here"
|
|
}
|
|
```
|
|
|
|
**Response:** `201 Created`
|
|
```json
|
|
{
|
|
"id": "20260205-123456",
|
|
"title": "Optional Title",
|
|
"path": "notes/20260205-123456.md",
|
|
"content": "# My Note\n\nContent here",
|
|
"created": "2026-02-05T12:34:56Z",
|
|
"updated": "2026-02-05T12:34:56Z"
|
|
}
|
|
```
|
|
|
|
### Get Note
|
|
|
|
```http
|
|
GET /api/notes/:id
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "20260205-123456",
|
|
"title": "My Note",
|
|
"path": "notes/20260205-123456.md",
|
|
"content": "# My Note\n\nFull content...",
|
|
"created": "2026-02-05T12:34:56Z",
|
|
"updated": "2026-02-05T12:34:56Z"
|
|
}
|
|
```
|
|
|
|
### Update Note
|
|
|
|
```http
|
|
PUT /api/notes/:id
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"content": "# Updated Content\n\nNew content here"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "20260205-123456",
|
|
"title": "Updated Content",
|
|
"path": "notes/20260205-123456.md",
|
|
"content": "# Updated Content\n\nNew content here",
|
|
"created": "2026-02-05T12:34:56Z",
|
|
"updated": "2026-02-05T12:35:00Z"
|
|
}
|
|
```
|
|
|
|
### Delete (Archive) Note
|
|
|
|
```http
|
|
DELETE /api/notes/:id
|
|
```
|
|
|
|
**Response:** `200 OK`
|
|
|
|
Note: The note is moved to `archive/`, not permanently deleted.
|
|
|
|
---
|
|
|
|
## Projects
|
|
|
|
### List Projects
|
|
|
|
```http
|
|
GET /api/projects
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "ferrite",
|
|
"title": "Ferrite",
|
|
"description": "A Rust project",
|
|
"path": "projects/ferrite",
|
|
"created": "2026-02-04T10:00:00Z",
|
|
"updated": "2026-02-05T12:00:00Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Create Project
|
|
|
|
```http
|
|
POST /api/projects
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "New Project",
|
|
"description": "Project description"
|
|
}
|
|
```
|
|
|
|
**Response:** `201 Created`
|
|
```json
|
|
{
|
|
"id": "new-project",
|
|
"title": "New Project",
|
|
"description": "Project description",
|
|
"path": "projects/new-project",
|
|
"created": "2026-02-05T12:34:56Z",
|
|
"updated": "2026-02-05T12:34:56Z"
|
|
}
|
|
```
|
|
|
|
### Get Project
|
|
|
|
```http
|
|
GET /api/projects/:id
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "ferrite",
|
|
"title": "Ferrite",
|
|
"description": "A Rust project",
|
|
"path": "projects/ferrite",
|
|
"created": "2026-02-04T10:00:00Z",
|
|
"updated": "2026-02-05T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
### Get Project Content
|
|
|
|
```http
|
|
GET /api/projects/:id/content
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"content": "# Ferrite\n\nProject overview content..."
|
|
}
|
|
```
|
|
|
|
### Update Project Content
|
|
|
|
```http
|
|
PUT /api/projects/:id/content
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"content": "# Updated Overview\n\nNew content..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Project Notes
|
|
|
|
### List Project Notes
|
|
|
|
```http
|
|
GET /api/projects/:id/notes
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "20260205-123456",
|
|
"title": "Project Note",
|
|
"path": "projects/ferrite/notes/20260205-123456.md",
|
|
"created": "2026-02-05T12:34:56Z",
|
|
"updated": "2026-02-05T12:34:56Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Create Project Note
|
|
|
|
```http
|
|
POST /api/projects/:id/notes
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "New Note",
|
|
"content": "Note content..."
|
|
}
|
|
```
|
|
|
|
### Get Project Note
|
|
|
|
```http
|
|
GET /api/projects/:id/notes/:noteId
|
|
```
|
|
|
|
### Update Project Note
|
|
|
|
```http
|
|
PUT /api/projects/:id/notes/:noteId
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"content": "Updated content..."
|
|
}
|
|
```
|
|
|
|
### Delete Project Note
|
|
|
|
```http
|
|
DELETE /api/projects/:id/notes/:noteId
|
|
```
|
|
|
|
---
|
|
|
|
## Project Tasks
|
|
|
|
### List Project Tasks
|
|
|
|
```http
|
|
GET /api/projects/:id/tasks
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "task-20260205-123456",
|
|
"title": "Implement feature X",
|
|
"completed": false,
|
|
"section": "Active",
|
|
"priority": "high",
|
|
"due_date": "2026-02-10",
|
|
"is_active": true,
|
|
"content": "## Requirements\n\n- Item 1\n- Item 2",
|
|
"path": "projects/ferrite/tasks/task-20260205-123456.md",
|
|
"created": "2026-02-05T12:34:56Z",
|
|
"updated": "2026-02-05T12:34:56Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Create Task
|
|
|
|
```http
|
|
POST /api/projects/:id/tasks
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "New Task",
|
|
"content": "Task description..."
|
|
}
|
|
```
|
|
|
|
### Get Task
|
|
|
|
```http
|
|
GET /api/projects/:id/tasks/:taskId
|
|
```
|
|
|
|
### Update Task Content
|
|
|
|
```http
|
|
PUT /api/projects/:id/tasks/:taskId
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"content": "Updated task description..."
|
|
}
|
|
```
|
|
|
|
### Update Task Metadata
|
|
|
|
```http
|
|
PUT /api/projects/:id/tasks/:taskId/meta
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "New Title",
|
|
"is_active": false,
|
|
"section": "Backlog",
|
|
"priority": "low",
|
|
"due_date": "2026-02-15"
|
|
}
|
|
```
|
|
|
|
### Toggle Task Completion
|
|
|
|
```http
|
|
PUT /api/projects/:id/tasks/:taskId/toggle
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"completed": true
|
|
}
|
|
```
|
|
|
|
### Delete Task
|
|
|
|
```http
|
|
DELETE /api/projects/:id/tasks/:taskId
|
|
```
|
|
|
|
---
|
|
|
|
## All Tasks
|
|
|
|
### List All Tasks (across projects)
|
|
|
|
```http
|
|
GET /api/tasks
|
|
```
|
|
|
|
Returns tasks from all projects, useful for global task views.
|
|
|
|
---
|
|
|
|
## Daily Notes
|
|
|
|
### List Daily Notes
|
|
|
|
```http
|
|
GET /api/daily
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"date": "2026-02-05",
|
|
"path": "daily/2026-02-05.md",
|
|
"created": "2026-02-05T08:00:00Z",
|
|
"updated": "2026-02-05T12:00:00Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Today's Note
|
|
|
|
```http
|
|
GET /api/daily/today
|
|
```
|
|
|
|
Creates the daily note if it doesn't exist.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"date": "2026-02-05",
|
|
"content": "# 2026-02-05\n\n## Todo\n\n- [ ] Task 1",
|
|
"path": "daily/2026-02-05.md",
|
|
"created": "2026-02-05T08:00:00Z",
|
|
"updated": "2026-02-05T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
### Get/Create Daily Note by Date
|
|
|
|
```http
|
|
GET /api/daily/:date
|
|
POST /api/daily/:date
|
|
```
|
|
|
|
Date format: `YYYY-MM-DD`
|
|
|
|
---
|
|
|
|
## Assets
|
|
|
|
### Upload Asset
|
|
|
|
```http
|
|
POST /api/assets/upload
|
|
Content-Type: multipart/form-data
|
|
|
|
project: ferrite
|
|
file: (binary data)
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"url": "/api/assets/ferrite/image-20260205-123456.png",
|
|
"filename": "image-20260205-123456.png"
|
|
}
|
|
```
|
|
|
|
### Get Asset
|
|
|
|
```http
|
|
GET /api/assets/:project/:filename
|
|
```
|
|
|
|
Returns the binary file with appropriate Content-Type header.
|
|
|
|
---
|
|
|
|
## Search
|
|
|
|
### Search Content
|
|
|
|
```http
|
|
GET /api/search?q=search+term
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"path": "notes/20260205-123456.md",
|
|
"title": "My Note",
|
|
"matches": [
|
|
{
|
|
"line": 5,
|
|
"text": "This is a **search term** example"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Git Operations
|
|
|
|
### Get Status
|
|
|
|
```http
|
|
GET /api/git/status
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"branch": "main",
|
|
"ahead": 2,
|
|
"behind": 0,
|
|
"staged": [],
|
|
"modified": ["notes/20260205-123456.md"],
|
|
"untracked": [],
|
|
"has_conflicts": false
|
|
}
|
|
```
|
|
|
|
### Commit Changes
|
|
|
|
```http
|
|
POST /api/git/commit
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"message": "Update notes"
|
|
}
|
|
```
|
|
|
|
### Push to Remote
|
|
|
|
```http
|
|
POST /api/git/push
|
|
```
|
|
|
|
### Fetch from Remote
|
|
|
|
```http
|
|
POST /api/git/fetch
|
|
```
|
|
|
|
### Get Commit Log
|
|
|
|
```http
|
|
GET /api/git/log?limit=20
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "abc123...",
|
|
"message": "Update notes",
|
|
"author": "User Name",
|
|
"date": "2026-02-05T12:34:56Z",
|
|
"files_changed": 3
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Working Directory Diff
|
|
|
|
```http
|
|
GET /api/git/diff
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"diff": "diff --git a/notes/... "
|
|
}
|
|
```
|
|
|
|
### Get Commit Diff
|
|
|
|
```http
|
|
GET /api/git/diff/:commitId
|
|
```
|
|
|
|
### Get Remote Info
|
|
|
|
```http
|
|
GET /api/git/remote
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"name": "origin",
|
|
"url": "git@github.com:user/repo.git",
|
|
"ahead": 2,
|
|
"behind": 0
|
|
}
|
|
```
|
|
|
|
### Check for Conflicts
|
|
|
|
```http
|
|
GET /api/git/conflicts
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"has_conflicts": false,
|
|
"files": []
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## WebSocket
|
|
|
|
### Connect
|
|
|
|
```
|
|
WS /ws
|
|
```
|
|
|
|
### Messages (Client → Server)
|
|
|
|
**Lock File:**
|
|
```json
|
|
{
|
|
"type": "lock_file",
|
|
"path": "notes/20260205-123456.md",
|
|
"lock_type": "editor"
|
|
}
|
|
```
|
|
|
|
**Unlock File:**
|
|
```json
|
|
{
|
|
"type": "unlock_file",
|
|
"path": "notes/20260205-123456.md"
|
|
}
|
|
```
|
|
|
|
### Messages (Server → Client)
|
|
|
|
**File Locked:**
|
|
```json
|
|
{
|
|
"type": "file_locked",
|
|
"path": "notes/20260205-123456.md",
|
|
"client_id": "client-123"
|
|
}
|
|
```
|
|
|
|
**File Unlocked:**
|
|
```json
|
|
{
|
|
"type": "file_unlocked",
|
|
"path": "notes/20260205-123456.md"
|
|
}
|
|
```
|
|
|
|
**File Modified (broadcast):**
|
|
```json
|
|
{
|
|
"type": "file_modified",
|
|
"path": "notes/20260205-123456.md"
|
|
}
|
|
```
|
|
|
|
**Git Status Update:**
|
|
```json
|
|
{
|
|
"type": "git_status",
|
|
"status": { ... }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Responses
|
|
|
|
All endpoints return errors in this format:
|
|
|
|
```json
|
|
{
|
|
"error": "Human-readable error message",
|
|
"code": "ERROR_CODE"
|
|
}
|
|
```
|
|
|
|
### Common Error Codes
|
|
|
|
| Code | HTTP Status | Description |
|
|
|------|-------------|-------------|
|
|
| `NOT_FOUND` | 404 | Resource doesn't exist |
|
|
| `BAD_REQUEST` | 400 | Invalid request data |
|
|
| `CONFLICT` | 409 | Resource conflict (e.g., Git) |
|
|
| `INTERNAL_ERROR` | 500 | Server error |
|