# BMS API Examples

Quick reference for using the BMS (Bookmarks, Snippets, Notes Manager) API.

## Base URL

```bash
# Local development
BASE_URL="http://localhost:8081"

# Production
BASE_URL="https://bms.j4bitzs.cloud"
```

## Health Check

```bash
curl $BASE_URL/health
```

**Response:**
```json
{
  "status": "ok",
  "database": "ok",
  "notes_storage": "ok"
}
```

---

## Bookmarks

### Create Bookmark

```bash
curl -X POST $BASE_URL/bookmarks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "OpenClaw Documentation",
    "url": "https://openclaw.com/docs",
    "tags": "documentation,ai,tools",
    "description": "Official OpenClaw documentation and guides"
  }'
```

**Response:**
```json
{
  "id": 1,
  "title": "OpenClaw Documentation",
  "url": "https://openclaw.com/docs",
  "tags": "documentation,ai,tools",
  "description": "Official OpenClaw documentation and guides",
  "created_at": "2026-04-05T14:12:10Z"
}
```

### List All Bookmarks

```bash
curl $BASE_URL/bookmarks
```

### Get Single Bookmark

```bash
curl $BASE_URL/bookmarks/1
```

### Delete Bookmark

```bash
curl -X DELETE $BASE_URL/bookmarks/1
```

---

## Snippets

### Create Snippet

```bash
curl -X POST $BASE_URL/snippets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Docker Compose Up",
    "content": "docker compose up -d --build",
    "language": "bash",
    "tags": "docker,deployment,devops"
  }'
```

**Response:**
```json
{
  "id": 1,
  "title": "Docker Compose Up",
  "content": "docker compose up -d --build",
  "language": "bash",
  "tags": "docker,deployment,devops",
  "created_at": "2026-04-05T14:12:14Z"
}
```

### List All Snippets

```bash
curl $BASE_URL/snippets
```

### Get Single Snippet

```bash
curl $BASE_URL/snippets/1
```

### Delete Snippet

```bash
curl -X DELETE $BASE_URL/snippets/1
```

---

## Notes

### Create Note

```bash
curl -X POST $BASE_URL/notes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Ideas",
    "content": "# Project Ideas\n\n## Web Apps\n- Todo app with AI suggestions\n- Bookmark manager (done!)\n\n## CLI Tools\n- Git workflow helper\n- Log analyzer",
    "tags": "ideas,projects,todo"
  }'
```

**Response:**
```json
{
  "id": 1,
  "title": "Project Ideas",
  "tags": "ideas,projects,todo",
  "file_path": "/data/notes/1.md",
  "created_at": "2026-04-05T14:12:18Z"
}
```

### List All Notes

```bash
curl $BASE_URL/notes
```

**Response:**
```json
[
  {
    "id": 1,
    "title": "Project Ideas",
    "tags": "ideas,projects,todo",
    "file_path": "/data/notes/1.md",
    "created_at": "2026-04-05T14:12:18Z"
  }
]
```

### Get Single Note (with content)

```bash
curl $BASE_URL/notes/1
```

**Response:**
```json
{
  "id": 1,
  "title": "Project Ideas",
  "content": "# Project Ideas\n\n## Web Apps\n- Todo app with AI suggestions\n- Bookmark manager (done!)\n\n## CLI Tools\n- Git workflow helper\n- Log analyzer",
  "tags": "ideas,projects,todo",
  "file_path": "/data/notes/1.md",
  "created_at": "2026-04-05T14:12:18Z"
}
```

### Delete Note

```bash
curl -X DELETE $BASE_URL/notes/1
```

---

## Search

### Search Notes

Search for notes containing a specific query:

```bash
curl "$BASE_URL/search?q=docker"
```

**Response:**
```json
[
  {
    "id": 1,
    "title": "Docker Cheatsheet",
    "content": "# Docker Commands\n\n## Basic\n- docker ps\n- docker compose up -d",
    "tags": "docker,devops,cheatsheet",
    "file_path": "/data/notes/1.md",
    "created_at": "2026-04-05T14:12:20Z"
  }
]
```

---

## Example Workflows

### Save a Web Article as Bookmark + Note

```bash
# 1. Save bookmark
BOOKMARK=$(curl -s -X POST $BASE_URL/bookmarks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Interesting Article",
    "url": "https://example.com/article",
    "tags": "reading,tech",
    "description": "Article about modern web development"
  }')

echo "Bookmark saved: $BOOKMARK"

# 2. Save reading notes
curl -X POST $BASE_URL/notes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Notes: Interesting Article",
    "content": "# Key Takeaways\n\n- Point 1\n- Point 2\n- Point 3",
    "tags": "reading,tech,notes"
  }'
```

### Create a Code Snippet Library

```bash
# Git shortcuts
curl -X POST $BASE_URL/snippets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Git Force Push with Lease",
    "content": "git push --force-with-lease",
    "language": "bash",
    "tags": "git,safety"
  }'

# Docker cleanup
curl -X POST $BASE_URL/snippets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Docker System Prune",
    "content": "docker system prune -a --volumes",
    "language": "bash",
    "tags": "docker,cleanup,maintenance"
  }'

# SQL query template
curl -X POST $BASE_URL/snippets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SQL Find Duplicates",
    "content": "SELECT column, COUNT(*)\nFROM table\nGROUP BY column\nHAVING COUNT(*) > 1;",
    "language": "sql",
    "tags": "sql,query,duplicates"
  }'
```

### Project Journal

```bash
# Daily log
TODAY=$(date +%Y-%m-%d)
curl -X POST $BASE_URL/notes \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"Journal: $TODAY\",
    \"content\": \"# $TODAY\n\n## Done\n- Completed T3 deployment\n- Fixed health check\n\n## Next\n- Production deployment\n- Monitoring setup\",
    \"tags\": \"journal,daily,$(date +%Y-%m)\"
  }"
```

---

## Using with `jq` for Better Output

```bash
# Pretty-print JSON
curl -s $BASE_URL/bookmarks | jq

# Extract specific fields
curl -s $BASE_URL/snippets | jq '.[] | {title, language, tags}'

# Count items
curl -s $BASE_URL/notes | jq 'length'

# Filter by tag
curl -s $BASE_URL/bookmarks | jq '.[] | select(.tags | contains("docker"))'
```

---

## Error Handling

### HTTP Status Codes

- `200` - Success
- `201` - Created
- `404` - Not Found
- `500` - Internal Server Error
- `503` - Service Unavailable (health check failed)

### Example Error Response

```json
{
  "error": "bookmark not found"
}
```

---

## Bulk Operations (Using Shell Scripts)

### Import Bookmarks from CSV

```bash
#!/bin/bash
# import-bookmarks.sh

while IFS=, read -r title url tags description; do
  curl -X POST $BASE_URL/bookmarks \
    -H "Content-Type: application/json" \
    -d "{
      \"title\": \"$title\",
      \"url\": \"$url\",
      \"tags\": \"$tags\",
      \"description\": \"$description\"
    }"
  sleep 0.5  # Rate limiting
done < bookmarks.csv
```

### Backup All Data

```bash
#!/bin/bash
# backup.sh

BACKUP_DIR="bms-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Backup bookmarks
curl -s $BASE_URL/bookmarks > "$BACKUP_DIR/bookmarks.json"

# Backup snippets
curl -s $BASE_URL/snippets > "$BACKUP_DIR/snippets.json"

# Backup notes
curl -s $BASE_URL/notes > "$BACKUP_DIR/notes.json"

echo "Backup saved to $BACKUP_DIR"
```

---

## Tips & Best Practices

1. **Use tags consistently** - Makes filtering and organization easier
2. **Keep descriptions concise** - Focus on why you saved it
3. **Use meaningful titles** - Searchable and self-documenting
4. **Leverage search** - Find notes across all content
5. **Regular backups** - Export data periodically
6. **Health checks** - Monitor service status in production

---

**Production API:** https://bms.j4bitzs.cloud  
**Documentation:** See [DEPLOYMENT.md](./DEPLOYMENT.md)