Notes

Create, list, update, and delete notes. Attach notes to CRM records, control visibility, and use @mentions to notify teammates.

Notes let your team capture context about contacts, companies, and opportunities. Each note supports rich HTML content, can be linked to one or more CRM records, and respects visibility rules so private notes stay private.

List Notes

GET /api/v1/notes

Returns a paginated list of notes. Visibility filtering is applied automatically: you will see workspace-visible notes and your own private notes.

Query Parameters

Parameter	Type	Default	Description
`entity_type`	string	--	Filter by linked entity type: `contacts`, `companies`, `opportunities`
`entity_id`	string	--	Filter by linked entity ID
`filters`	string	--	JSON-encoded FilterGroup for advanced filtering
`sort`	string	--	JSON array for multi-field sorting. When provided, `sort_by` and `sort_dir` are ignored.
`sort_by`	string	`created_at`	Single field to sort by (used only when `sort` is absent or not valid JSON)
`sort_dir`	string	`desc`	Sort direction: `asc` or `desc` (used only with `sort_by`)
`cursor`	string	--	Pagination cursor from a previous response
`limit`	number	`20`	Number of results per page (max 100)

Example: Notes for a Contact

curl -X GET "https://kasar.app/api/v1/notes?entity_type=contacts&entity_id=a1b2c3d4-e5f6-7890-abcd-ef0123456789" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
      "title": "Call summary - contract renewal",
      "content": "<p>Alice confirmed she wants to renew for 2 years. Needs updated pricing by Friday.</p>",
      "visibility": "workspace",
      "created_by_display": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "display": "Marc Dupont",
        "image": "https://lh3.googleusercontent.com/a/photo.jpg"
      },
      "created_at": "2025-03-12T16:45:00Z",
      "updated_at": "2025-03-12T16:45:00Z"
    }
  ],
  "total": 4,
  "nextCursor": null
}

Each note includes a created_by_display object with the author's name and avatar, ready for display in your UI.

Example: All Notes

curl -X GET "https://kasar.app/api/v1/notes?limit=50&sort_dir=desc" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..."

Create a Note

POST /api/v1/notes

Creates a new note. If an entity context is provided, a many-to-many link is created automatically.

Request Body

Field	Type	Required	Description
`content`	string	Yes	HTML content of the note
`entity_type`	string	No	Entity type to link: `contacts`, `companies`, `opportunities`
`entity_id`	string	No	Entity ID to link
`mentioned_user_ids`	array	No	Array of workspace user UUIDs to notify as @mentions (see Mentions)
`data`	object	No	Additional metadata
`data.visibility`	string	No	`workspace` (default) or `private`

Example

curl -X POST "https://kasar.app/api/v1/notes" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<p>Alice confirmed she wants to renew for 2 years. Needs updated pricing by Friday.</p>",
    "entity_type": "contacts",
    "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "data": {
      "visibility": "workspace"
    }
  }'

Response (201):

{
  "note_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "action": "created"
}

The note title is auto-generated from the HTML content. You do not need to provide it manually.

If your note content contains @mentions (referencing workspace users), notifications are sent to the mentioned users automatically. You can also pass mentioned_user_ids explicitly. See the Mentions section for details.

Update a Note

PUT /api/v1/notes/{id}

Updates the content or linked entities of an existing note. Only include the fields you want to change.

Request Body

Field	Type	Description
`content`	string	Updated HTML content
`linked_entities`	array	Replace linked entities with this list of `{ id, type }` objects

Example: Update Content

curl -X PUT "https://kasar.app/api/v1/notes/b2c3d4e5-f6a7-8901-bcde-f01234567890" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<p>Alice confirmed renewal for 2 years. Updated pricing sent on March 14.</p>"
  }'

Response:

{
  "note_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "action": "updated"
}

Example: Link to Multiple Entities

curl -X PUT "https://kasar.app/api/v1/notes/b2c3d4e5-f6a7-8901-bcde-f01234567890" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "linked_entities": [
      { "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "type": "contacts" },
      { "id": "c3d4e5f6-a7b8-9012-cdef-012345678901", "type": "opportunities" }
    ]
  }'

Passing linked_entities replaces all existing many-to-many links. To keep current links, include them in the array alongside any new ones.

When content is updated, the auto-generated title is regenerated to reflect the new content.

Delete a Note

DELETE /api/v1/notes/{id}

Permanently deletes a note and removes all entity links.

Example

curl -X DELETE "https://kasar.app/api/v1/notes/b2c3d4e5-f6a7-8901-bcde-f01234567890" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..."

Response (204): No content.

Mentions

Notes support @mentions to notify workspace users. Mentions are resolved in two ways:

Automatic extraction from HTML content. The API scans the note's HTML for links pointing to workspace users (e.g., <a href="/workspace_users/{uuid}">@Name</a>). Any user IDs found this way receive a mention_in_note notification.
Explicit mentioned_user_ids array. You can pass an array of workspace user UUIDs in the request body. When provided, this list takes precedence over automatic extraction.

In both cases, the note's author is excluded from notifications (you will not notify yourself).

Mentions work on both create and update. When a note's content is updated, new mentions in the updated content trigger notifications.

Example: Explicit Mentions

curl -X POST "https://kasar.app/api/v1/notes" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<p>Discussed pricing with the team. Need input from sales.</p>",
    "mentioned_user_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660f9511-f30c-52e5-b827-557766551111"
    ]
  }'

Visibility

Notes support two visibility levels:

Visibility	Description
`workspace`	Visible to all members of the workspace. This is the default.
`private`	Visible only to the note's author.

The API enforces visibility automatically on list requests. You will never see another user's private notes in API responses.

Error Responses

Note Not Found

{
  "error": true,
  "code": "RECORD_NOT_FOUND",
  "message": "Note not found"
}

Missing Content

{
  "error": true,
  "code": "MISSING_REQUIRED_FIELD",
  "message": "Field 'content' is required"
}

Notes

On this page