Joplin Search

Joplin Search

This skill searches notes, notebooks, and tags in Joplin via the REST API.

Configuration

• Base URL: http://localhost:${JOPLIN_PORT:-41184}
• Auth Token: $JOPLIN_TOKEN

Basic Search

curl -s "http://localhost:${JOPLIN_PORT:-41184}/search?query=SEARCH_TERMS&token=$JOPLIN_TOKEN&fields=id,title,body,parent_id,updated_time&limit=20"

Search Operators

Search Types

By default, search returns notes. Use the type parameter to search other item types:

# Search notebooks
curl -s "http://localhost:${JOPLIN_PORT:-41184}/search?query=TERM&type=folder&token=$JOPLIN_TOKEN&fields=id,title"

# Search tags
curl -s "http://localhost:${JOPLIN_PORT:-41184}/search?query=TERM&type=tag&token=$JOPLIN_TOKEN&fields=id,title"

Pagination

Search results are paginated. Check has_more and increment page:

# Page 1 (default)
curl -s "http://localhost:${JOPLIN_PORT:-41184}/search?query=TERMS&token=$JOPLIN_TOKEN&fields=id,title,updated_time&limit=50&page=1"

# Page 2
curl -s "http://localhost:${JOPLIN_PORT:-41184}/search?query=TERMS&token=$JOPLIN_TOKEN&fields=id,title,updated_time&limit=50&page=2"

Response format:

{
  "items": [
    {"id": "abc123", "title": "Meeting Notes", "updated_time": 1700000000000}
  ],
  "has_more": false
}

Workflow

1. Parse the user's search intent and construct the query string.
2. URL-encode the query parameter (spaces become %20 or +).
3. Execute the search.
4. Present results in a clear list: title, notebook (resolve parent_id if needed), last updated.
5. If has_more is true, ask if the user wants more results.
6. If the user wants to see a specific note's content, fetch it by ID:

   curl -s "http://localhost:${JOPLIN_PORT:-41184}/notes/NOTE_ID?token=$JOPLIN_TOKEN&fields=id,title,body,parent_id,updated_time"
   

Getting Notebook Names for Results

To show notebook names alongside results, fetch notebooks:

curl -s "http://localhost:${JOPLIN_PORT:-41184}/folders?token=$JOPLIN_TOKEN&fields=id,title"

Then map parent_id from notes to the notebook title.

Error Handling

• 403: Invalid token
• Empty results: Try broader search terms, remove operators, or use wildcards
• Connection refused: Joplin not running

Tips

• URL-encode special characters in the query: use --data-urlencode or %20 for spaces
• For better results, use curl -s -G "http://localhost:${JOPLIN_PORT:-41184}/search" --data-urlencode "query=SEARCH TERMS" --data-urlencode "token=$JOPLIN_TOKEN" --data-urlencode "fields=id,title,body,parent_id,updated_time"
• Limit fields to only what you need — omitting body makes responses much smaller for listing
• When searching for exact titles, use title:"exact note title"