Craft.do Integration Skill

# Craft.do Integration Skill

Complete REST API integration for Craft.do - the beautiful note-taking and document app.

## Overview

This skill provides full programmatic access to Craft.do for:
- **Task automation:** Create, update, manage tasks across inbox/daily notes/logbook
- **Document workflows:** Programmatically create, read, organize documents
- **Folder management:** Build nested folder hierarchies via API
- **Obsidian migration:** One-time full vault migration with content preservation
- **Content manipulation:** Add/edit markdown content via blocks API

Craft.do features:
- Native markdown support
- Task management (inbox, daily notes, logbook)
- Collections (database tables)
- Hierarchical folders and documents
- Full REST API access

## Setup

1. Get your API key from Craft.do settings
2. Store credentials securely:

```bash
export CRAFT_API_KEY="pdk_xxx"
export CRAFT_ENDPOINT="https://connect.craft.do/links/YOUR_LINK/api/v1"
```

## API Capabilities

### ✅ What Works

#### List Folders
```bash
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/folders"
```

Returns all locations: unsorted, daily_notes, trash, templates, and custom folders.

#### List Documents
```bash
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/documents?folderId=FOLDER_ID"
```

#### Create Folder (with optional parent for nesting)
```bash
# Root-level folder
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folders": [{
      "name": "Projects"
    }]
  }' \
  "$CRAFT_ENDPOINT/folders"

# Nested folder (requires parent folder ID)
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folders": [{
      "name": "Q1 2024",
      "parentFolderId": "PARENT_FOLDER_ID"
    }]
  }' \
  "$CRAFT_ENDPOINT/folders"
```

#### Create Document
```bash
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "title": "Document Title"
    }],
    "destination": {
      "folderId": "FOLDER_ID"
    }
  }' \
  "$CRAFT_ENDPOINT/documents"
```

**Note:** Documents are created without content initially. Use the `/blocks` endpoint to add content.

#### Add Content to Document
```bash
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [{
      "type": "text",
      "markdown": "# Document content\n\nFull markdown support!"
    }],
    "position": {
      "pageId": "DOCUMENT_ID",
      "position": "end"
    }
  }' \
  "$CRAFT_ENDPOINT/blocks"
```

#### Read Document Content
```bash
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/blocks?id=DOCUMENT_ID"
```

Returns full markdown content with all blocks.

#### Create Task
```bash
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [{
      "markdown": "Task description",
      "location": {"type": "inbox"},
      "status": "active"
    }]
  }' \
  "$CRAFT_ENDPOINT/tasks"
```

#### Update Task (Mark Complete)
```bash
curl -X PUT \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasksToUpdate": [{
      "id": "TASK_ID",
      "markdown": "- [x] Completed task"
    }]
  }' \
  "$CRAFT_ENDPOINT/tasks"
```

#### List Tasks
```bash
# Active tasks
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=active"

# All completed (logbook)
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=logbook"

# Upcoming
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=upcoming"

# Inbox only
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=inbox"
```

#### Move Documents
```bash
curl -X PUT \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIds": ["DOC_ID"],
    "destination": {"location": "unsorted"}
  }' \
  "$CRAFT_ENDPOINT/documents/move"
```

Note: Can only move to `unsorted`, `templates`, or custom folder IDs. Cannot move directly to `trash`.

### ❌ Limitations

- **No Collections API** - Collections (databases) not accessible via API
- **No task deletion** - Can only create/update tasks, not delete
- **No document deletion** - Cannot delete documents directly (only move)
- **No search endpoint** - Search requires specific query format (needs more testing)
- **Limited filtering** - Collections filtering/grouping only in UI, not via API

## Common Use Cases

### Sync Tasks from External System
```bash
# Create task in Craft from Mission Control
TASK_TITLE="Deploy new feature"
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"tasks\": [{
      \"markdown\": \"$TASK_TITLE\",
      \"location\": {\"type\": \"inbox\"},
      \"status\": \"active\"
    }]
  }" \
  "$CRAFT_ENDPOINT/tasks"
```

### Create Daily Note
```bash
TODAY=$(date +%Y-%m-%d)
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"documents\": [{
      \"title\": \"Daily Note - $TODAY\",
      \"content\": [{\"textContent\": \"# $TODAY\\n\\n## Tasks\\n\\n## Notes\\n\"}],
      \"location\": \"daily_notes\"
    }]
  }" \
  "$CRAFT_ENDPOINT/documents"
```

### Archive Completed Work
```bash
# Get all completed tasks
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=logbook" | jq '.items[] | {id, markdown, completedAt}'
```

## Integration Patterns

### Mission Control → Craft Sync

**Problem:** Mission Control has automation but ugly UI. Craft has beautiful UI but no automation.

**Solution:** Use Mission Control as the source of truth, sync completed work to Craft for viewing.

```bash
#!/bin/bash
# sync-to-craft.sh - Sync completed tasks to Craft

# Read completed tasks from Mission Control
COMPLETED_TASKS=$(cat mission-control/tasks.json | jq -r '.[] | select(.status=="done") | .title')

# Push each to Craft
echo "$COMPLETED_TASKS" | while read -r task; do
  curl -X POST \
    -H "Authorization: Bearer $CRAFT_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"tasks\": [{
        \"markdown\": \"- [x] $task\",
        \"location\": {\"type\": \"inbox\"}
      }]
    }" \
    "$CRAFT_ENDPOINT/tasks"
done
```

## Markdown Support

Craft fully supports markdown:
- Headers: `# H1`, `## H2`, etc.
- Lists: `- item`, `1. item`
- Tasks: `- [ ] todo`, `- [x] done`
- Links: `[text](url)`
- Code: `` `inline` `` or ` ```block``` `
- Emphasis: `*italic*`, `**bold**`

All content is stored and returned as markdown, making it perfect for programmatic manipulation.

## Best Practices

1. **Store API key securely** - Never commit to code
2. **Test in unsorted folder first** - Easy to find/clean up
3. **Use markdown format** - Native to both systems
4. **One-way sync only** - Craft → read-only, Mission Control → write
5. **Batch operations** - API supports arrays for efficiency
6. **Handle errors gracefully** - API returns detailed validation errors

## Error Handling

Common errors:
- `VALIDATION_ERROR` - Check required fields (markdown, location)
- `403` - Invalid/expired API key
- `404` - Document/task ID not found

Example validation error:
```json
{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [{
    "path": ["tasks", 0, "markdown"],
    "message": "Invalid input: expected string"
  }]
}
```

## Future Possibilities

When Craft adds to their API:
- [ ] Collections CRUD via API
- [ ] Task deletion
- [ ] Document deletion
- [ ] Advanced search
- [ ] Webhooks for real-time sync
- [ ] Batch operations for large datasets

## Resources

- [Craft API Docs](https://craft.do/api) (get your personal API endpoint from Craft settings)
- [Craft Blog - Collections](https://www.craft.do/blog/introducing-collections)
- [Craft YouTube](https://www.youtube.com/channel/UC8OIJ9uNRQZiG78K2BSn67A)

## Testing Checklist

- [x] List folders
- [x] List documents
- [x] Create document
- [x] Add content to document (via /blocks endpoint)
- [x] Read document content
- [x] Create task
- [x] Update task (mark complete)
- [x] List tasks (all scopes)
- [x] Move documents between locations
- [x] Full Obsidian → Craft migration with content
- [ ] Search (needs format refinement)
- [x] Collections - NOT accessible via API
- [x] Delete tasks - NOT supported
- [x] Delete documents - NOT supported (only move)

## Example: Complete Workflow

```bash
# 1. Create a project folder
PROJECT_ID=$(curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 2024 Projects"}' \
  "$CRAFT_ENDPOINT/folders" | jq -r '.id')

# 2. Create a project document
DOC_ID=$(curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"documents\": [{
      \"title\": \"Project Alpha\",
      \"content\": [{\"textContent\": \"## Overview\\n\\nProject details here.\"}],
      \"location\": \"$PROJECT_ID\"
    }]
  }" \
  "$CRAFT_ENDPOINT/documents" | jq -r '.items[0].id')

# 3. Create tasks for the project
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {"markdown": "Design wireframes", "location": {"type": "inbox"}},
      {"markdown": "Build prototype", "location": {"type": "inbox"}},
      {"markdown": "User testing", "location": {"type": "inbox"}}
    ]
  }' \
  "$CRAFT_ENDPOINT/tasks"

# 4. Mark first task complete
TASK_ID=$(curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=active" | jq -r '.items[0].id')

curl -X PUT \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"tasksToUpdate\": [{
      \"id\": \"$TASK_ID\",
      \"markdown\": \"- [x] Design wireframes\"
    }]
  }" \
  "$CRAFT_ENDPOINT/tasks"
```

---

**Status:** Tested and working (2026-01-31)
**Tested with:** Craft API v1
**Author:** Eliza