> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caret.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Notes

> Get a paginated list of notes with various filtering options

### Query Parameters

<ParamField query="limit" type="number" default="20">
  Number of notes to return (1-100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset
</ParamField>

<ParamField query="sortBy" type="string" default="createdAt">
  Field to sort by. Options: `createdAt`, `updatedAt`, `title`
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Sort order. Options: `asc`, `desc`
</ParamField>

<ParamField query="status" type="string">
  Filter by note status. Options: `idle`, `recording`, `transcript-processing`,
  `recorded-not-summarized`, `summarizing`, `completed`
</ParamField>

<ParamField query="kind" type="string">
  Filter by note kind. Options: `online`, `in-person`, `podcast` (currently only
  `online` is supported)
</ParamField>

<ParamField query="search" type="string">
  Search query for title
</ParamField>

<ParamField query="createdBy" type="string">
  Filter by creator user ID
</ParamField>

<ParamField query="fromDate" type="string">
  Filter notes created after date (ISO 8601 format)
</ParamField>

<ParamField query="toDate" type="string">
  Filter notes created before date (ISO 8601 format)
</ParamField>

<ParamField query="folderIds" type="string">
  Comma-separated folder IDs to filter by
</ParamField>

<ParamField query="tagIds" type="string" deprecated>
  Deprecated: Use `folderIds` instead. Comma-separated tag IDs
</ParamField>

<ParamField query="participantEmail" type="string">
  Filter by participant email address
</ParamField>

### Response

<ResponseField name="items" type="Note[]">
  <Expandable title="Note">
    <ResponseField name="id" type="string">
      Unique identifier for the note
    </ResponseField>

    <ResponseField name="title" type="string">
      Title of the note
    </ResponseField>

    <ResponseField name="kind" type="string">
      Type of the note. One of `online`, `in-person`, `podcast`
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the note
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO8601 timestamp when the note was created
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO8601 timestamp when the note was last updated
    </ResponseField>

    <ResponseField name="visibility" type="string">
      Visibility setting. One of `only-me`, `workspace`, `public`
    </ResponseField>

    <ResponseField name="tags" type="object[]">
      Folders associated with the note (returned as tags for compatibility)

      <Expandable title="Tag">
        <ResponseField name="id" type="string">
          Tag ID
        </ResponseField>

        <ResponseField name="name" type="string">
          Tag name
        </ResponseField>

        <ResponseField name="color" type="string">
          Tag color
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="participants" type="object[]">
      Participants from the calendar event

      <Expandable title="Participant">
        <ResponseField name="name" type="string">
          Participant name
        </ResponseField>

        <ResponseField name="email" type="string">
          Participant email
        </ResponseField>

        <ResponseField name="profileImageUrl" type="string">
          Profile image URL
        </ResponseField>

        <ResponseField name="accountName" type="string">
          Company name
        </ResponseField>

        <ResponseField name="accountDomain" type="string">
          Company domain
        </ResponseField>

        <ResponseField name="accountImageUrl" type="string">
          Company logo URL
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="totalDurationSec" type="number">
      Total duration of the recording in seconds
    </ResponseField>

    <ResponseField name="userWrittenNote" type="string">
      User-written note content
    </ResponseField>

    <ResponseField name="enhancedNote" type="string">
      AI-enhanced note content (empty in list response)
    </ResponseField>

    <ResponseField name="summary" type="string">
      Meeting summary content (empty in list response)
    </ResponseField>

    <ResponseField name="transcripts" type="object[]">
      Transcript segments (empty in list response)
    </ResponseField>

    <ResponseField name="calendarEvent" type="object | null">
      Associated calendar event data

      <Expandable title="CalendarEvent">
        <ResponseField name="id" type="string">
          Event ID
        </ResponseField>

        <ResponseField name="href" type="string">
          Event URL
        </ResponseField>

        <ResponseField name="title" type="string">
          Event title
        </ResponseField>

        <ResponseField name="startsAt" type="string">
          Start time (ISO8601)
        </ResponseField>

        <ResponseField name="endsAt" type="string">
          End time (ISO8601)
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          Created time (ISO8601)
        </ResponseField>

        <ResponseField name="updatedAt" type="string">
          Updated time (ISO8601)
        </ResponseField>

        <ResponseField name="calendarId" type="string">
          Calendar ID
        </ResponseField>

        <ResponseField name="attendees" type="object[]">
          List of attendees

          <Expandable title="Attendee">
            <ResponseField name="self" type="boolean">
              Whether this is the authenticated user
            </ResponseField>

            <ResponseField name="email" type="string">
              Attendee email
            </ResponseField>

            <ResponseField name="displayName" type="string">
              Attendee display name
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="inputLanguage" type="string | null">
      Language of the audio input
    </ResponseField>

    <ResponseField name="translationLanguage" type="string | null">
      Translation target language (if applicable)
    </ResponseField>

    <ResponseField name="meetingApp" type="string | null">
      App used to auto-start the meeting
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination">
    <ResponseField name="limit" type="number">
      Number of items per page
    </ResponseField>

    <ResponseField name="nextOffset" type="number | null">
      Offset for the next page, null if last page
    </ResponseField>

    <ResponseField name="isLast" type="boolean">
      Whether this is the last page
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash curl theme={null}

  curl --request GET \
   --url 'https://api.caret.so/v1/notes?limit=10&status=completed' \
   --header 'Authorization: Bearer <your_api_key>'

  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "items": [
      {
        "id": "note_123456789",
        "title": "Weekly Team Sync",
        "kind": "online",
        "status": "completed",
        "createdAt": "2024-01-28T10:00:00Z",
        "updatedAt": "2024-01-28T11:30:00Z",
        "visibility": "workspace",
        "tags": [
          {
            "id": "fld_123",
            "name": "Sales",
            "color": "#4A90E2"
          }
        ],
        "participants": [
          {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "profileImageUrl": "https://example.com/avatar.jpg",
            "accountName": "Acme Corp",
            "accountDomain": "acme.com",
            "accountImageUrl": "https://example.com/logo.png"
          }
        ],
        "totalDurationSec": 3600,
        "userWrittenNote": "",
        "enhancedNote": "",
        "summary": "",
        "transcripts": [],
        "calendarEvent": null,
        "inputLanguage": "en",
        "translationLanguage": null,
        "meetingApp": null
      }
    ],
    "pagination": {
      "limit": 10,
      "nextOffset": 10,
      "isLast": false
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "unauthorized",
      "message": "Invalid or missing API key"
    }
  }
  ```
</ResponseExample>