Note Management

Overview

Notes provide a collaborative documentation system where agents and users can create, update, and share information. Notes support different types (spec, task, general) and can be organized by workspace and session.

Note Types

Type	Description
`spec`	Specification documents
`task`	Task-related notes
`general`	General purpose notes

List Notes

curl "http://localhost:3000/api/notes?workspaceId=default"

Endpoint

GET /api/notes

GET

List notes with optional filters

Query Parameters

workspaceId

string

required

Workspace ID (defaults to "default")

type

string

Filter by note type: spec, task, or general

noteId

string

If provided, returns a single note

Response

notes

array

Array of note objects (when listing)

note

object

Single note object (when querying by noteId)

Note Object

string

required

Unique note identifier

title

string

required

Note title

content

string

required

Note content (supports Markdown)

workspaceId

string

required

Workspace this note belongs to

metadata

object

required

Metadata object containing type and custom fields

metadata.type

string

required

Note type: spec, task, or general

metadata.taskStatus

string

Associated task status (for task notes)

metadata.assignedAgentIds

array

Array of agent IDs assigned to this note

metadata.parentNoteId

string

ID of parent note (for hierarchical notes)

metadata.linkedTaskId

string

ID of linked task

metadata.custom

object

Custom metadata fields

createdAt

string

required

ISO 8601 timestamp of creation

updatedAt

string

required

ISO 8601 timestamp of last update

Response Example

{
  "notes": [
    {
      "id": "note-abc123",
      "title": "API Design Specification",
      "content": "# API Design\n\nThis document outlines...",
      "workspaceId": "default",
      "metadata": {
        "type": "spec",
        "custom": {
          "version": "1.0"
        }
      },
      "createdAt": "2026-03-03T10:00:00.000Z",
      "updatedAt": "2026-03-03T10:30:00.000Z"
    }
  ]
}

Create or Update Note

# Create new note
curl -X POST http://localhost:3000/api/notes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Design Specification",
    "content": "# API Design\n\nDetailed specs...",
    "workspaceId": "default",
    "type": "spec"
  }'

# Update existing note
curl -X POST http://localhost:3000/api/notes \
  -H "Content-Type: application/json" \
  -d '{
    "noteId": "note-abc123",
    "title": "Updated Title",
    "content": "Updated content",
    "workspaceId": "default"
  }'

Endpoint

POST /api/notes

POST

Create a new note or update an existing one

Request Body

noteId

string

If provided, updates existing note. Otherwise creates new note.

title

string

required

Note title (defaults to “Untitled” for new notes)

content

string

Note content (supports Markdown)

workspaceId

string

required

Workspace ID

type

string

Note type: spec, task, or general (defaults to general)

metadata

object

Additional metadata for the note

Response

note

object

required

The created or updated note object

Response Example

{
  "note": {
    "id": "note-abc123",
    "title": "API Design Specification",
    "content": "# API Design\n\nDetailed specs...",
    "workspaceId": "default",
    "metadata": {
      "type": "spec"
    },
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T10:00:00.000Z"
  }
}

Get Note by Path

curl http://localhost:3000/api/notes/default/note-abc123

Endpoint

GET /api/notes/{workspaceId}/{noteId}

GET

Get a note by workspace and note ID

Path Parameters

workspaceId

string

required

The workspace ID

noteId

string

required

The note ID

Response

note

object

required

The note object

Delete Note (Query)

curl -X DELETE "http://localhost:3000/api/notes?noteId=note-abc123&workspaceId=default"

Endpoint

DELETE /api/notes

DELETE

Delete a note using query parameters

Query Parameters

noteId

string

required

The note ID to delete

workspaceId

string

Workspace ID (defaults to "default")

Response

deleted

boolean

required

Always true when successful

noteId

string

required

The deleted note ID

Response Example

{
  "deleted": true,
  "noteId": "note-abc123"
}

Delete Note (Path)

curl -X DELETE http://localhost:3000/api/notes/default/note-abc123

Endpoint

DELETE /api/notes/{workspaceId}/{noteId}

DELETE

Delete a note using path parameters

Path Parameters

workspaceId

string

required

The workspace ID

noteId

string

required

The note ID to delete

Response

deleted

boolean

required

Always true when successful

noteId

string

required

The deleted note ID

Note Events (SSE)

curl "http://localhost:3000/api/notes/events?workspaceId=default"

Endpoint

GET /api/notes/events

GET

Server-Sent Events (SSE) stream for real-time note change notifications

Query Parameters

workspaceId

string

Filter events by workspace ID

Event Types

The SSE stream sends events for:

Note created
Note updated
Note deleted

Event Format

data: {"type": "note-updated", "noteId": "note-abc123", "workspaceId": "default"}

Error Responses

400 Bad Request

{
  "error": "workspaceId is required"
}

404 Not Found

{
  "error": "Note not found"
}

REST API

MCP Tools

ACP

A2A

Note Management

Overview

Note Types

List Notes

Endpoint

Query Parameters

Response

Note Object

Response Example

Create or Update Note

Endpoint

Request Body

Response

Response Example

Get Note by Path

Endpoint

Path Parameters

Response

Delete Note (Query)

Endpoint

Query Parameters

Response

Response Example

Delete Note (Path)

Endpoint

Path Parameters

Response

Note Events (SSE)

Endpoint

Query Parameters

Event Types

Event Format

Error Responses

400 Bad Request

404 Not Found

Build docs developers (and LLMs) love

REST API

MCP Tools

ACP

A2A

​Overview

​Note Types

​List Notes

​Endpoint

​Query Parameters

​Response

​Note Object

​Response Example

​Create or Update Note

​Endpoint

​Request Body

​Response

​Response Example

​Get Note by Path

​Endpoint

​Path Parameters

​Response

​Delete Note (Query)

​Endpoint

​Query Parameters

​Response

​Response Example

​Delete Note (Path)

​Endpoint

​Path Parameters

​Response

​Note Events (SSE)

​Endpoint

​Query Parameters

​Event Types

​Event Format

​Error Responses

​400 Bad Request

​404 Not Found

Build docs developers (and LLMs) love

Overview

Note Types

List Notes

Endpoint

Query Parameters

Response

Note Object

Response Example

Create or Update Note

Endpoint

Request Body

Response

Response Example

Get Note by Path

Endpoint

Path Parameters

Response

Delete Note (Query)

Endpoint

Query Parameters

Response

Response Example

Delete Note (Path)

Endpoint

Path Parameters

Response

Note Events (SSE)

Endpoint

Query Parameters

Event Types

Event Format

Error Responses

400 Bad Request

404 Not Found