Ironpad API Reference

Base URL: http://localhost:3000

Notes

List Notes

GET /api/notes

Response:

[
  {
    "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

POST /api/notes
Content-Type: application/json

{
  "title": "Optional Title",
  "content": "# My Note\n\nContent here"
}

Response: 201 Created

{
  "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

GET /api/notes/:id

Response:

{
  "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

PUT /api/notes/:id
Content-Type: application/json

{
  "content": "# Updated Content\n\nNew content here"
}

Response:

{
  "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

DELETE /api/notes/:id

Response: 200 OK

Note: The note is moved to archive/, not permanently deleted.

Projects

List Projects

GET /api/projects

Response:

[
  {
    "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

POST /api/projects
Content-Type: application/json

{
  "title": "New Project",
  "description": "Project description"
}

Response: 201 Created

{
  "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

GET /api/projects/:id

Response:

{
  "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

GET /api/projects/:id/content

Response:

{
  "content": "# Ferrite\n\nProject overview content..."
}

Update Project Content

PUT /api/projects/:id/content
Content-Type: application/json

{
  "content": "# Updated Overview\n\nNew content..."
}

Project Notes

List Project Notes

GET /api/projects/:id/notes

Response:

[
  {
    "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

POST /api/projects/:id/notes
Content-Type: application/json

{
  "title": "New Note",
  "content": "Note content..."
}

Get Project Note

GET /api/projects/:id/notes/:noteId

Update Project Note

PUT /api/projects/:id/notes/:noteId
Content-Type: application/json

{
  "content": "Updated content..."
}

Delete Project Note

DELETE /api/projects/:id/notes/:noteId

Get Note Titles (for link autocomplete)

GET /api/projects/:id/notes-titles

Returns all notes in the project with their frontmatter IDs and titles. Used by the /link slash command dropdown.

Response:

{
  "notes": [
    { "id": "ferrite-index", "title": "Ferrite", "path": "projects/ferrite/index.md" },
    { "id": "ferrite-20260227-153000", "title": "Meeting Notes", "path": "projects/ferrite/notes/20260227-153000.md" }
  ]
}

Search Project Notes

GET /api/projects/:id/notes-search?q=meeting&limit=10

Filter notes by partial title or ID match within a project.

Response:

{
  "query": "meeting",
  "results": [
    { "id": "ferrite-20260227-153000", "title": "Meeting Notes", "path": "projects/ferrite/notes/20260227-153000.md" }
  ]
}

Backlinks

See backlinks.md for full feature documentation.

Get Links for a Note

Returns both backlinks (incoming) and forward links (outgoing).

GET /api/backlinks/notes/:noteId/links

Response:

{
  "note_id": "ferrite-20260227-153000",
  "backlinks": [
    {
      "source_id": "ferrite-20260226-100000",
      "source_title": "Project Overview",
      "source_path": "projects/ferrite/notes/20260226-100000.md",
      "context": "See [Meeting Notes](ferrite-20260227-153000) for details",
      "line_number": 5
    }
  ],
  "forward_links": [
    {
      "target_id": "ferrite-20260225-090000",
      "target_title": "Architecture Notes",
      "context": "Based on the [Architecture Notes](ferrite-20260225-090000)",
      "line_number": 12
    }
  ]
}

Get Backlinks Only

GET /api/backlinks/notes/:noteId/backlinks

Response:

{
  "note_id": "ferrite-20260227-153000",
  "backlinks": [...],
  "count": 1
}

Get Forward Links Only

GET /api/backlinks/notes/:noteId/forward-links

Response:

{
  "note_id": "ferrite-20260227-153000",
  "forward_links": [...],
  "count": 2
}

Rebuild Link Index

Force a full rescan of all note files and rebuild the in-memory link index.

POST /api/backlinks/links/rebuild

Response:

{
  "success": true,
  "indexed_notes": 42,
  "message": "Indexed 42 notes"
}

Get Link Statistics

GET /api/backlinks/links/stats

Response:

{
  "total_links": 15,
  "unique_targets": 8
}

Project Tasks

List Project Tasks

GET /api/projects/:id/tasks

Response:

[
  {
    "id": "task-20260205-123456",
    "title": "Implement feature X",
    "completed": false,
    "section": "Active",
    "priority": "high",
    "due_date": "2026-02-10",
    "is_active": true,
    "tags": ["backend", "api"],
    "parent_id": null,
    "recurrence": null,
    "recurrence_interval": null,
    "project_id": "ferrite",
    "last_comment": "API endpoint done, moving to frontend",
    "path": "projects/ferrite/tasks/task-20260205-123456.md",
    "created": "2026-02-05T12:34:56Z",
    "updated": "2026-02-05T12:34:56Z"
  }
]

Create Task

POST /api/projects/:id/tasks
Content-Type: application/json

{
  "title": "New Task",
  "content": "Task description..."
}

Get Task

GET /api/projects/:id/tasks/:taskId

Update Task Content

PUT /api/projects/:id/tasks/:taskId
Content-Type: application/json

{
  "content": "Updated task description..."
}

Update Task Metadata

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

PUT /api/projects/:id/tasks/:taskId/toggle

Response:

{
  "completed": true
}

Delete Task

DELETE /api/projects/:id/tasks/:taskId

Add Comment

POST /api/projects/:id/tasks/:taskId/comments
Content-Type: application/json

{
  "text": "Started work on this — API integration is in progress."
}

Response: 201 Created

{
  "id": "task-20260216-120000",
  "title": "Implement feature X",
  "completed": false,
  "section": "Active",
  "is_active": true,
  "comments": [
    {
      "date": "2026-02-16T10:30:00+00:00",
      "text": "Created initial spec"
    },
    {
      "date": "2026-02-16T12:00:00+00:00",
      "text": "Started work on this — API integration is in progress."
    }
  ],
  "content": "## Requirements\n\n- Item 1\n- Item 2",
  "...": "other task fields"
}

Comments are stored as a YAML sequence in the task's frontmatter. The response returns the full TaskWithContent object with all comments.

Delete Comment

DELETE /api/projects/:id/tasks/:taskId/comments/:commentIndex

Removes the comment at the given zero-based index.

Response:

{
  "id": "task-20260216-120000",
  "comments": [],
  "...": "full TaskWithContent"
}

Comment in List Views

When listing tasks (GET /api/projects/:id/tasks or GET /api/tasks), each task includes a last_comment field with the text of the most recent comment (or null if no comments exist). This enables showing a quick status summary without loading the full task.

{
  "id": "task-20260216-120000",
  "title": "Implement feature X",
  "last_comment": "Started work on this — API integration is in progress.",
  "...": "other task fields"
}

All Tasks

List All Tasks (across projects)

GET /api/tasks

Returns tasks from all projects, useful for global task views.

Daily Notes

List Daily Notes

GET /api/daily

Response:

[
  {
    "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

GET /api/daily/today

Creates the daily note if it doesn't exist.

Response:

{
  "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

GET /api/daily/:date
POST /api/daily/:date

Date format: YYYY-MM-DD

Assets

Upload Asset

POST /api/assets/upload
Content-Type: multipart/form-data

project: ferrite
file: (binary data)

Response:

{
  "url": "/api/assets/ferrite/image-20260205-123456.png",
  "filename": "image-20260205-123456.png"
}

Get Asset

GET /api/assets/:project/:filename

Returns the binary file with appropriate Content-Type header.

Search

Search Content

GET /api/search?q=search+term

Response:

{
  "results": [
    {
      "path": "notes/20260205-123456.md",
      "title": "My Note",
      "matches": [
        {
          "line": 5,
          "text": "This is a **search term** example"
        }
      ]
    }
  ]
}

Git Operations

Get Status

GET /api/git/status

Response:

{
  "branch": "main",
  "ahead": 2,
  "behind": 0,
  "staged": [],
  "modified": ["notes/20260205-123456.md"],
  "untracked": [],
  "has_conflicts": false
}

Commit Changes

POST /api/git/commit
Content-Type: application/json

{
  "message": "Update notes"
}

Push to Remote

POST /api/git/push

Fetch from Remote

POST /api/git/fetch

Get Commit Log

GET /api/git/log?limit=20

Response:

[
  {
    "id": "abc123...",
    "message": "Update notes",
    "author": "User Name",
    "date": "2026-02-05T12:34:56Z",
    "files_changed": 3
  }
]

Get Working Directory Diff

GET /api/git/diff

Response:

{
  "diff": "diff --git a/notes/... "
}

Get Commit Diff

GET /api/git/diff/:commitId

Get Remote Info

GET /api/git/remote

Response:

{
  "name": "origin",
  "url": "git@github.com:user/repo.git",
  "ahead": 2,
  "behind": 0
}

Check for Conflicts

GET /api/git/conflicts

Response:

{
  "has_conflicts": false,
  "files": []
}

WebSocket

Connect

WS /ws

Messages (Client → Server)

Lock File:

{
  "type": "lock_file",
  "path": "notes/20260205-123456.md",
  "lock_type": "editor"
}

Unlock File:

{
  "type": "unlock_file",
  "path": "notes/20260205-123456.md"
}

Messages (Server → Client)

File Locked:

{
  "type": "file_locked",
  "path": "notes/20260205-123456.md",
  "client_id": "client-123"
}

File Unlocked:

{
  "type": "file_unlocked",
  "path": "notes/20260205-123456.md"
}

File Modified (broadcast):

{
  "type": "file_modified",
  "path": "notes/20260205-123456.md"
}

Git Status Update:

{
  "type": "git_status",
  "status": { ... }
}

Error Responses

All endpoints return errors in this format:

{
  "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

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Ironpad API Reference

Notes

List Notes

Create Note

Get Note

Update Note

Delete (Archive) Note

Projects

List Projects

Create Project

Get Project

Get Project Content

Update Project Content

Project Notes

List Project Notes

Create Project Note

Get Project Note

Update Project Note

Delete Project Note

Get Note Titles (for link autocomplete)

Search Project Notes

Backlinks

Get Links for a Note

Get Backlinks Only

Get Forward Links Only

Rebuild Link Index

Get Link Statistics

Project Tasks

List Project Tasks

Create Task

Get Task

Update Task Content

Update Task Metadata

Toggle Task Completion

Delete Task

Add Comment

Delete Comment

Comment in List Views

All Tasks

List All Tasks (across projects)

Daily Notes

List Daily Notes

Get Today's Note

Get/Create Daily Note by Date

Assets

Upload Asset

Get Asset

Search

Search Content

Git Operations

Get Status

Commit Changes

Push to Remote

Fetch from Remote

Get Commit Log

Get Working Directory Diff

Get Commit Diff

Get Remote Info

Check for Conflicts

WebSocket

Connect

Messages (Client → Server)

Messages (Server → Client)

Error Responses

Common Error Codes