Note.sx Pet

Create, share, and manage encrypted notes instantly with full theme customization. This pet provides a complete integration with the Note.sx API for note sharing.

Features

• Create encrypted notes - Share notes with automatic encryption
• Check existing files - Avoid uploading duplicates
• Upload files - Direct file uploads with hash verification
• Delete notes - Remove shared notes from the server
• API authentication - Secure header-based authentication
• Self-hosted support - Compatible with self-hosted Note.sx servers

Quick Start

1. Get Your Credentials

Visit https://note.sx/account and:

1. Copy your API Key
2. Copy your User ID

2. Set Up Environment Variables

# Copy the example file
cp .env.example .env

# Fill in your credentials
NOTESX_API_KEY=your_api_key_here
NOTESX_USER_ID=your_user_id_here

# Optional: Use self-hosted server (default: https://api.note.sx)
# NOTESX_HOST=https://your-notesx-server.com

3. Test Connection

opencode run "test my Note.sx connection" --print-logs

4. Create Your First Note

opencode run "create a new encrypted note called Hello World with content test note" --print-logs

Tools

notesx-test-connection

Test your Note.sx API connection and verify credentials.

Parameters: None

Example:

opencode run "test my Note.sx connection"

notesx-check-files

Check if files already exist on the server before uploading. This prevents duplicate uploads.

Parameters:

• filesJson (required) - JSON string containing array of file objects with hash, filetype, and byteLength

Example:

opencode run "check if files exist before uploading" --print-logs

Request format:

[
  {
    "hash": "abc123sha256hash",
    "filetype": "text/html",
    "byteLength": 1024
  }
]

notesx-create-note

Create a new encrypted note and get a shareable link immediately.

Parameters:

• filename (required) - Note filename without extension
• content (required) - HTML content of the note
• filetype (optional) - MIME type, default: text/html
• hash (required) - SHA256 hash of the content
• encrypted (optional) - Encrypt the note, default: true
• title (optional) - Note title (for unencrypted notes)
• description (optional) - Note description
• width (optional) - Display width in pixels
• mathJax (optional) - Enable MathJax rendering
• expiration (optional) - Expiration timestamp in milliseconds

Example:

opencode run "create a new encrypted note called Test Note with content This is a test" --print-logs

Response:

{
  "success": true,
  "message": "Note created and shared successfully",
  "shareUrl": "https://note.sx/abc123...",
  "filename": "Test Note",
  "encrypted": true,
  "details": {
    "url": "https://note.sx/abc123...",
    "contentHash": "sha256hash...",
    "timestamp": "2025-02-05T10:30:00.000Z"
  }
}

notesx-upload-file

Upload a file to Note.sx. Use this for uploading attachments or note content before creating a note.

Parameters:

• contentBase64 (required) - File content as base64-encoded string
• filetype (required) - MIME type (e.g., text/html, application/json)
• hash (required) - SHA256 hash of the original content
• byteLength (required) - Original file size in bytes
• expiration (optional) - Expiration timestamp in milliseconds

Example:

opencode run "upload a file to Note.sx" --print-logs

notesx-delete-note

Delete a shared note by filename. This removes the note from the server.

Parameters:

• filename (required) - Filename to delete (without extension)
• filetype (optional) - File MIME type, default: text/html

Example:

opencode run "delete a shared note" --print-logs

API Reference

Authentication

All requests use header-based authentication with:

• x-sharenote-id - Your user ID
• x-sharenote-key - SHA256 hash of (nonce + API key)
• x-sharenote-nonce - Current Unix timestamp
• x-sharenote-version - Plugin version

Endpoints

Base URL: https://api.note.sx (or your self-hosted server)

| Method | Endpoint | Purpose | |--------|----------|---------| | GET | /v1/account/check-key | Verify API credentials | | POST | /v1/file/check-files | Check if files exist | | POST | /v1/file/create-note | Create and share a note | | POST | /v1/file/upload | Upload a file | | POST | /v1/file/delete | Delete a note |

Rate Limiting

The Note.sx API has a rate limit of 100 requests per minute. If exceeded, the API returns a 403 error.

Configuration

Self-Hosted Server

To use a self-hosted Note.sx server, set the NOTESX_HOST environment variable:

NOTESX_HOST=https://your-notesx-server.com

The server runs in Docker. See note-sx/server for setup instructions.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | NOTESX_API_KEY | Yes | Your Note.sx API key | | NOTESX_USER_ID | Yes | Your Note.sx user ID | | NOTESX_HOST | No | Server URL (default: https://api.note.sx) |

Examples

Create an Encrypted Note with Expiration

# Create a note that expires in 1 hour
opencode run "create a new encrypted note called Temporary Note with expiration in 1 hour" --print-logs

Check Files Before Uploading

opencode run "check if files with hash abc123 and filetype text/html already exist" --print-logs

Share a Note with Custom Width

opencode run "create a note with width 800 pixels" --print-logs

Error Handling

The pet handles errors gracefully and returns detailed error messages:

{
  "success": false,
  "error": "Invalid API credentials. Check NOTESX_API_KEY and NOTESX_USER_ID.",
  "details": {
    "filename": "test-note"
  }
}

Testing

Run the included test scenarios:

# Test connection
bun run test:connection

# Test note creation
bun run test:create

Validation Checklist

• [x] Pet name is @openpets/notesx
• [x] Has notesx-test-connection tool
• [x] All tool names follow notesx-{action} pattern
• [x] All tools return JSON strings
• [x] Environment variables documented in package.json
• [x] .env.example has all variables
• [x] queries array has example prompts
• [x] Graceful degradation when not configured

References

• Note.sx - Official website
• Share Note Plugin - Obsidian plugin source code
• Note.sx Server - Self-hosted backend

API Status & Troubleshooting

Known Issues

Status 463 Error: If you receive a 463 error (validation error), this indicates:

• The API key may not have create/upload permissions
• The endpoint structure might require additional validation
• Contact Note.sx support to verify API key permissions

Status 462 Error: Invalid credentials

• Verify NOTESX_API_KEY and NOTESX_USER_ID are correct
• Regenerate credentials at https://note.sx/account

Status 404 Error: Endpoint not found

• Check if NOTESX_HOST is set correctly
• Verify API endpoint availability

Testing Tips

1. Test connection first with the test-connection tool
2. Use the check-files tool to verify file structure
3. Start with small test notes before uploading large files
4. Monitor logs with --print-logs flag for debugging

Support

For issues or questions:

1. Check your API credentials at https://note.sx/account
2. Verify NOTESX_API_KEY and NOTESX_USER_ID are correct
3. For self-hosted servers, check the NOTESX_HOST configuration
4. Review the Note.sx documentation
5. Check GitHub issues for similar problems