voicenotes#

Use the Voicenotes skill to create, search and retrieve user’s notes.

Setup#

1. Create an integration at https://voicenotes.com/app?open-claw=true#settings
2. Copy the API key
3. Configure it:

Webchat: Skills → Voicenotes → API Key in the sidebar

Terminal: Add to your OpenClaw config ( ~/.openclaw/config.yaml):

yaml

skills:
  voicenotes:
    env:
      VOICENOTES_API_KEY: "your_key_here"

Or export it directly:

bash

export VOICENOTES_API_KEY="your_key_here"

The key is then available as $VOICENOTES_API_KEY environment variable.

API Basics#

All requests need the Authorization header:

bash

curl -X GET "https://api.voicenotes.com/api/integrations/open-claw/..." \
  -H "Authorization: $VOICENOTES_API_KEY"

Common Operations#

Search query in users notes:

Query parameters:

• query (required): The search query string

bash

curl -X GET "https://api.voicenotes.com/api/integrations/open-claw/search/semantic?query={search_query}" \
  -H "Authorization: $VOICENOTES_API_KEY"

Get multiple Voicenotes with filters (tags and date range):

Query parameters:

• tags (optional): array of valid tags
• date_range (optional): array with start and end date as UTC timestamps

bash

curl -X POST "https://api.voicenotes.com/api/integrations/open-claw/recordings" \
  -H "Authorization: $VOICENOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["tag1", "tag2"],
    "date_range": ["2026-01-01T00:00:00.000000Z", "2026-02-01T00:00:00.000000Z"]
  }'

If you want more context get the whole transcript:

bash

curl "https://api.voicenotes.com/api/integrations/open-claw/recordings/{recording_uuid}" \
  -H "Authorization: $VOICENOTES_API_KEY" \

Create a text note in Voicenotes:

bash

curl -X POST "https://api.voicenotes.com/api/integrations/open-claw/recordings/new" \
  -H "Authorization: $VOICENOTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_type": 3,
    "transcript": "note content here",
    "device_info": "open-claw"
  }'

Response Structure#

Semantic Search Response:

Returns an array of notes and note splits ordered by relevance:

json

[
  {
    "type": "note",
    "uuid": "NTHiJljf",
    "title": "Quick idea about project",
    "transcript": "Full transcript text with <br> for line breaks...",
    "tags": ["idea", "project"],
    "created_at": "2025-01-15T10:30:00.000000Z"
  },
  {
    "type": "note_split",
    "uuid": "8JzkhEGh",
    "title": "Long meeting notes",
    "transcript": "Relevant chunk from a larger note...",
    "tags": ["meeting"],
    "created_at": "2025-01-14T09:00:00.000000Z"
  },
  {
    "type": "import_split",
    "uuid": "xYz12345",
    "title": "filename.extension",
    "transcript": "Chunk from an imported note...",
    "tags": ["imported"],
    "created_at": "2025-01-10T14:00:00.000000Z"
  }
]

• type: "note" - Complete note matching the search
• type: "note_split" - Chunk from a larger note; use the uuid to fetch full transcript if needed
• type: "import_split" - Chunk from an imported note; title is the filename; cannot be fetched via /recordings/{uuid}
• transcript may contain HTML ( <br>, <b>) for formatting

Get Recordings Response (with filters):

Returns paginated notes matching the filters:

json

{
  "data": [
    {
      "id": "bTZI5t12",
      "title": null,
      "transcript": "this is a sample note",
      "duration": 0,
      "recorded_at": "2026-02-06T10:07:45.000000Z",
      "created_at": "2026-02-06T10:07:45.000000Z",
      "recording_type": 3,
      "tags": []
    }
  ],
  "links": {
    "first": "https://api.voicenotes.com/api/integrations/open-claw/recordings?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "https://api.voicenotes.com/api/integrations/open-claw/recordings",
    "per_page": 10,
    "to": 1
  }
}

Key fields:

• data - Array of recording objects
• links.next - URL for next page (null if no more pages)
• meta.per_page - Results per page (default 10)

Get Recording Response:

Returns full note details:

json

{
  "data": {
    "id": "NTHiJljf",
    "title": "Meeting Connectivity Check",
    "transcript": "Full transcript text...",
    "duration": 12101,
    "recorded_at": "2025-08-07T09:50:14.000000Z",
    "created_at": "2025-08-07T09:50:14.000000Z",
    "recording_type": 2,
    "tags": ["meeting"],
    "subnotes": [],
    "attachments": []
  }
}

Key fields:

• id - Note UUID
• transcript - Full text (meetings include [HH:MM:SS] Speaker N: timestamps)
• duration - Length in milliseconds
• recording_type - 1=voice note, 2=voice meeting, 3=text note
• tags - Array of tag objects with name field

Create Note Response:

json

{
  "message": "Recording audio uploaded successfully!",
  "recording": {
    "id": "bPI3RcUP",
    "recording_id": "bPI3RcUP",
    "title": null,
    "transcript": "Sample note",
    "recording_type": 3,
    "created_at": "2026-02-04T08:51:29.000000Z",
    "tags": []
  }
}

Key fields:

• message - Success confirmation
• recording.id - New note UUID
• recording.transcript - The note content

Notes#

• Note IDs are UUIDs
• Rate limit: ~3 requests/second average

Security & Guardrails#

• Only accesses api.voicenotes.com endpoints
• No credential exfiltration or external data storage
• No telemetry or analytics
• No automatic code execution or file overwrites
• Read/write limited to user's own Voicenotes data via authenticated API

Input Sanitization#

When constructing API requests, the agent MUST sanitize all user-provided inputs:

• Search queries: URL-encode the query parameter using --data-urlencode instead of string interpolation
• Recording UUIDs: Validate format (alphanumeric, 8 characters) before use; reject any input containing shell metacharacters ( ;, |, &, $, `, \)
• JSON body fields: Use proper JSON encoding; never concatenate raw user input into JSON strings

Safe example for search:

bash

curl -G "https://api.voicenotes.com/api/integrations/open-claw/search/semantic" \
  --data-urlencode "query=user search term here" \
  -H "Authorization: $VOICENOTES_API_KEY"

UUID validation pattern: /^[a-zA-Z0-9]{8}$/