NoteStream API

Base URL: https://api.notestream.cloud

All paths below are relative to this base URL. For example, POST /search means POST https://api.notestream.cloud/search.

There is no separate AI namespace — agents call the same endpoints as the app. Every endpoint accepts either a user API token or a session JWT:

X-API-Key: your-api-key-here

Authorization: Bearer <jwt>

API keys can be created from Settings > API Keys in the NoteStream app. A token maps to a real user, so a request sees exactly what that user can see (their own notes plus everything shared with them via direct shares, hashtags, groups, and share links).

A note and its content are separate entities with a 1:1 mapping. A note holds metadata (ID, author, sharing, timestamps); note content holds the document body as ProseMirror JSON. Every note has exactly one content record, and they share the same ID. The root node is always { type: "doc", content: [...] }.

Search notes

Search across every note the caller can see. The request body is a filter AST; the only required field is visibility.

POST /search

Request body

{
  "ast": {
    "visibility": "my-world",
    "text": "meeting"
  },
  "page": 1,
  "pageSize": 25
}

Filter AST fields:

Response

{
  "notes": [
    {
      "id": "0192d4e5-7a8b-7c6d-9e0f-1a2b3c4d5e6f",
      "author": {
        "id": "user-uuid",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "email": "ada@example.com",
        "profilePicture": null
      }
    }
  ],
  "totalCount": 250,
  "page": 1,
  "pageSize": 25
}

Results are note IDs (with author info), not snippets — fetch a note's body with GET /content/:id.

Errors

Get a note

Retrieve the metadata of a note the caller owns.

GET /notes/:id

Parameters

Response

{
  "id": "0192d4e5-7a8b-7c6d-9e0f-1a2b3c4d5e6f",
  "authorId": "user-uuid",
  "isShared": false,
  "pinnedPosition": null,
  "folderId": null,
  "deletedAt": null,
  "createdAt": 1711900800000,
  "updatedAt": 1711900800000
}

Errors

Create a note

Create a new note from ProseMirror JSON content. The note is assigned to the caller.

POST /notes

Request body

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "A brand new note" }]
      }
    ]
  },
  "isShared": true,
  "anonymousRole": "VIEWER"
}

Response

Returns the full note object (same shape as GET /notes/:id).

Errors

Read note content

Retrieve a note's content as ProseMirror JSON.

GET /content/:id

Parameters

Response

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Hello world" }]
      }
    ]
  }
}

If the note has no content, returns an empty document:

{ "content": { "type": "doc", "content": [{ "type": "paragraph" }] } }

Errors

Replace note content

Replace the entire content of an existing note with new ProseMirror JSON.

PUT /content/:id

Parameters

Request body

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Updated content" }]
      }
    ]
  }
}

The content field must be a valid ProseMirror document with type: "doc" and a content array.

Response

{ "success": true }

Errors

Update note sharing

Set a note's sharing entries. Supports anonymous (anyone-with-link) and per-email sharing.

PUT /notes/sharing/:id

Parameters

Request body

{
  "entries": [
    { "principalType": "ANONYMOUS", "principal": "anonymous", "role": "VIEWER" }
  ]
}

Errors

Note: When a note is shared anonymously it becomes accessible via a shareable link. The URL removes dashes from the note ID: https://notestream.cloud/shared/note/{noteId without dashes}. For example, note 0192d4e5-7a8b-7c6d-9e0f-1a2b3c4d5e6f becomes https://notestream.cloud/shared/note/0192d4e57a8b7c6d9e0f1a2b3c4d5e6f.

Create a group

Create a new group. The caller becomes its OWNER member.

POST /groups

Request body

{
  "name": "Design Team",
  "description": "Where the design crew collaborates"
}

Response

Returns the created group:

{
  "group": {
    "id": "0192d4e5-7a8b-7c6d-9e0f-1a2b3c4d5e6f",
    "slug": "design-team-a1b2c3d4",
    "name": "Design Team",
    "description": "Where the design crew collaborates",
    "logo": null,
    "ownerId": "user-uuid",
    "shareCode": null,
    "shareCanEdit": false,
    "createdAt": "2026-06-27T16:00:00.000Z",
    "updatedAt": "2026-06-27T16:00:00.000Z"
  }
}

Errors

List groups

List the groups the caller belongs to, each with their role and member count.

GET /groups

Response

{
  "groups": [
    {
      "id": "0192d4e5-7a8b-7c6d-9e0f-1a2b3c4d5e6f",
      "slug": "design-team-a1b2c3d4",
      "name": "Design Team",
      "description": null,
      "logo": null,
      "ownerId": "user-uuid",
      "shareCode": null,
      "shareCanEdit": false,
      "createdAt": "2026-06-27T16:00:00.000Z",
      "updatedAt": "2026-06-27T16:00:00.000Z",
      "myRole": "OWNER",
      "memberCount": 3
    }
  ]
}

Errors

Add group members

Add or update members of a group by email. Owner-only — the caller must own the group. Membership is keyed by email, so an invitee who has not registered yet resolves to their account once they sign up with that email.

POST /groups/:id/members

Parameters

Request body

{
  "members": [
    { "email": "alice@example.com", "role": "CONTRIBUTOR" },
    { "email": "bob@example.com", "role": "VIEWER" }
  ]
}

Response

Returns the upserted member rows:

{
  "members": [
    {
      "id": "0192d4e5-7a8b-7c6d-9e0f-1a2b3c4d5e6f",
      "groupId": "0192d4e5-7a8b-7c6d-9e0f-1a2b3c4d5e70",
      "principal": "alice@example.com",
      "role": "CONTRIBUTOR",
      "createdAt": "2026-06-27T16:00:00.000Z",
      "updatedAt": "2026-06-27T16:00:00.000Z"
    }
  ]
}

Errors

ProseMirror node types

Notes support the following node types in the content array:

Mentions are atomic inline nodes rendered as pills (e.g. @John). The id serves as the mention identifier and label is the display text. The type attribute defaults to "text" for free-text mentions.

Text marks

Text nodes can have marks for inline formatting:

Example: rich note

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 1 },
        "content": [{ "type": "text", "text": "Meeting Notes" }]
      },
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Discussed the " },
          { "type": "text", "text": "roadmap", "marks": [{ "type": "bold" }] },
          { "type": "text", "text": " for Q2." }
        ]
      },
      {
        "type": "taskList",
        "content": [
          {
            "type": "taskItem",
            "attrs": { "checked": false },
            "content": [
              {
                "type": "paragraph",
                "content": [{ "type": "text", "text": "Follow up with design team" }]
              }
            ]
          }
        ]
      }
    ]
  }
}