notes:query

Description: Retrieve a list of notes for the authenticated account.

Request Schema

{
  "payload": {
    "type": "notes:query",
    "q": {
      "per_page": 25,
      "page": 1,
      "title_cont": "meeting",
      "commentable_import_id_or_commentable_id": "P001"
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

See global request attributes
See search request attributes, and:
payload.q.title_cont - String - Records containing a given string in the note title
payload.q.commentable_import_id_or_commentable_id - String/Integer - Find notes by subject’s import_id or id
payload.q.page - Integer - Page number for pagination (default: 1)
payload.q.per_page - Integer - Items per page (default: 20)

Authentication Behavior

This endpoint follows Pattern A: Full Account Access.

All authentication methods see the same data - no person filtering is applied.

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "type": "notes:query",
    "q": {
      "per_page": 25,
      "page": 1,
      "total": 10
    },
    "resources": [
      {
        "id": 1,
        "import_id": "NOTE-001",
        "title": "Meeting Notes",
        "body_plain": "Discussion about project timeline...",
        "body_html": "<p>Discussion about project timeline...</p>",
        "commentable": {
          "type": "Person",
          "id": 789,
          "name": "John Doe",
          "import_id": "P001"
        },
        "created_at": "2025-03-17T09:00:00Z",
        "updated_at": "2025-03-17T09:00:00Z"
      }
    ]
  }
}

Response Attributes

payload.q - Object - Query metadata including pagination info
- per_page - Integer - Items per page
- page - Integer - Current page number
- total - Integer - Total number of matching notes
payload.resources - Array of note objects:
- id - Integer - Unique identifier
- import_id - String - External reference ID (optional)
- title - String - Note title
- body_plain - String - Note content as plain text
- body_html - String - Note content as HTML
- commentable - Object - The subject this note is about
  - type - String - Class name (Person, Organization, Household)
  - id - Integer - Subject ID
  - name - String - Display name of the subject
  - import_id - String - Subject’s import ID (if available)
- created_at - ISO 8601 timestamp - Creation time
- updated_at - ISO 8601 timestamp - Last update time

Error Responses

When an invalid query parameter is provided:

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "notes:query",
    "q": { "invalid_param" => "value" }
  },
  "error": "Error message",
  "status": "bad_request"
}

Real Life Example

{
  "source_public_key": "bwyexzko74pnnjn741936fnaujxyhib9rpx8rggtejwnc3cz6ans",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.co"
  },
  "created_at": "2026-02-14T14:14:22Z",
  "signature": "0b7cf3e421c4d7e4212e2069fbfbfd6734d0809fa3603e492949dc5b948da691f277c601d48b9cbac2bebbfdf697e8e01aa93ff54ae53afab4c5c2272dea0400",
  "payload": {
    "type": "notes:query",
    "q": {
      "per_page": 10,
      "page": 1,
      "total": 5,
      "title_cont": "meeting"
    },
    "resources": [
      {
        "id": 123,
        "import_id": "NOTE-2024-001",
        "title": "Weekly Meeting Notes",
        "body_plain": "Attendees: Sarah, Mike, John\n\nAgenda:\n1. Project status\n2. Budget review\n\nAction items:\n- Sarah to follow up on vendor contracts",
        "body_html": "<p>Attendees: Sarah, Mike, John</p><p>Agenda:</p><ol><li>Project status</li><li>Budget review</li></ol><p>Action items:</p><ul><li>Sarah to follow up on vendor contracts</li></ul>",
        "commentable": {
          "type": "Organization",
          "id": 456,
          "name": "Community Garden Club",
          "import_id": "ORG-001"
        },
        "created_at": "2025-03-15T10:00:00Z",
        "updated_at": "2025-03-15T10:00:00Z"
      }
    ]
  }
}

Usage Notes

This is an ephemeral query - no message is persisted to the database
Notes are ordered by created_at DESC (newest first) by default
Soft-deleted notes are automatically excluded from results
Authentication can be via token, whitelist, or membership
All notes in the account are accessible regardless of authentication method