Imported from Trompetilla/Skills (skills/chrisagiddings/openclaw-yatta-skill/SKILL.md). Install upstream with npx skills add Trompetilla/Skills --skill openclaw-yatta-skill. Copyright stays with the author.

Yatta! Skill

Interact with Yatta! task management system via API. Requires an API key from your Yatta! account.

⚠️ Security Warning

This skill can perform DESTRUCTIVE operations on your Yatta! account:

• Task Management: Create, update, archive, and batch-modify tasks
• Project Management: Create, update, and archive projects
• Context Management: Create contexts and assign them to tasks
• Comment Management: Add, update, and delete task comments
• Calendar Management: Create, sync, and modify calendar subscriptions
• Follow-Up Management: Update delegation schedules and mark complete
• Capacity Management: Trigger capacity computations

Operation Types:

Read-Only Operations (✅ Safe):

• List tasks, projects, contexts, comments
• Get analytics, insights, streaks
• View capacity and calendar data
• Get Eisenhower Matrix view
• All GET requests

Destructive Operations (⚠️ Modify or delete data):

• Create/update/archive tasks (POST, PUT, DELETE)
• Batch update tasks
• Create/update projects
• Create/assign contexts
• Add/update/delete comments
• Add/sync calendar subscriptions
• Update follow-up schedules
• All POST, PUT, DELETE requests

Best Practices:

1. Review commands before running - Check what the API call will do
2. No undo for deletions - Archived tasks can be recovered, but some operations are permanent
3. Test on non-critical data first - Create test tasks/projects to verify behavior
4. Batch operations affect multiple items - Be extra careful with batch updates
5. Real-time sync - Changes appear in Yatta! UI immediately

For detailed API operation documentation, see API-REFERENCE.md.

Setup

⚠️ API Key Security

Your Yatta! API key provides FULL access to your account:

• Can create, read, update, and delete ALL tasks, projects, contexts
• Can modify calendar subscriptions and follow-up schedules
• Can archive data and trigger computations
• No read-only scopes available - keys have full permissions

Security Best Practices:

• Store keys in a secure password manager (1Password CLI recommended)
• Use environment variables, never hardcode keys in scripts
• Rotate keys regularly (every 90 days recommended)
• Create separate keys for different integrations
• Revoke unused keys immediately
• Never commit keys to version control

1. Get Your API Key

1. Log into Yatta! app
2. Go to Settings → API Keys
3. Create new key (e.g., "OpenClaw Integration")
4. Copy the yatta_... key
5. Store it securely

2. Configure the Skill

Option A: Environment Variables (Recommended)

# Add to your shell profile (~/.zshrc, ~/.bashrc)
export YATTA_API_KEY="yatta_your_key_here"
export YATTA_API_URL="https://zunahvofybvxpptjkwxk.supabase.co/functions/v1"  # Default

Option B: 1Password CLI (Most Secure)

# Store key in 1Password
op item create --category=API_CREDENTIAL \
  --title="Yatta API Key" \
  api_key[password]="yatta_your_key_here"

# Use in commands
export YATTA_API_KEY=$(op read "op://Private/Yatta API Key/api_key")

Note: Currently using direct Supabase URL. Clean branded URLs (yattadone.com/api) coming soon.

3. Test Connection

curl -s "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[:3]'  # Show first 3 tasks

Tasks API

List Tasks

All tasks:

curl -s "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Filter by status:

# TODO tasks only
curl -s "$YATTA_API_URL/tasks?status=todo" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

# Doing (active) tasks
curl -s "$YATTA_API_URL/tasks?status=doing" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

# Completed tasks
curl -s "$YATTA_API_URL/tasks?status=done" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Filter by priority:

# High priority tasks
curl -s "$YATTA_API_URL/tasks?priority=high" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {title, due_date, priority}'

Filter by project:

# Get project ID first
PROJECT_ID=$(curl -s "$YATTA_API_URL/projects" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq -r '.[] | select(.name=="Website Redesign") | .id')

# Get tasks for that project
curl -s "$YATTA_API_URL/tasks?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Filter by matrix state:

# Delegated tasks
curl -s "$YATTA_API_URL/tasks?matrix_state=delegated" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {title, delegated_to, follow_up_date}'

# Waiting tasks
curl -s "$YATTA_API_URL/tasks?matrix_state=waiting" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Date range queries:

# Tasks due this week
WEEK_END=$(date -v+7d "+%Y-%m-%d")
curl -s "$YATTA_API_URL/tasks?due_date_lte=$WEEK_END" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {title, due_date}'

# Overdue tasks
TODAY=$(date "+%Y-%m-%d")
curl -s "$YATTA_API_URL/tasks?due_date_lte=$TODAY&status=todo" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {title, due_date}'

Pagination:

# First 50 tasks
curl -s "$YATTA_API_URL/tasks?limit=50&offset=0" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

# Next 50 tasks
curl -s "$YATTA_API_URL/tasks?limit=50&offset=50" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Archived tasks:

curl -s "$YATTA_API_URL/tasks?archived=true" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Create Task

Simple task:

curl -s "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Finish report",
    "priority": "high"
  }' \
  | jq '.'

Task with full details:

curl -s "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review Q1 numbers",
    "description": "Go through revenue, costs, and projections",
    "priority": "high",
    "due_date": "2026-02-15",
    "effort_points": 5,
    "project_id": "uuid-of-project",
    "matrix_state": "active"
  }' \
  | jq '.'

Delegated task with follow-up:

curl -s "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website redesign",
    "delegated_to": "Dev Team",
    "matrix_state": "delegated",
    "follow_up_schedule": {
      "type": "weekly",
      "day_of_week": "monday",
      "next_follow_up": "2026-02-17"
    }
  }' \
  | jq '.'

Recurring task:

curl -s "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team standup",
    "recurrence_rule": {
      "frequency": "daily",
      "interval": 1,
      "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"]
    },
    "effort_points": 1
  }' \
  | jq '.'

Update Task

Update single task:

TASK_ID="uuid-of-task"
curl -s -X PUT "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "'$TASK_ID'",
    "status": "done",
    "completed_at": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'"
  }' \
  | jq '.'

Batch update tasks:

curl -s -X PUT "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["uuid-1", "uuid-2", "uuid-3"],
    "priority": "high",
    "project_id": "project-uuid"
  }' \
  | jq '.'

Archive Task

TASK_ID="uuid-of-task"
curl -s -X DELETE "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "'$TASK_ID'"
  }' \
  | jq '.'

Projects API

List Projects

# All projects
curl -s "$YATTA_API_URL/projects" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

# With task counts
curl -s "$YATTA_API_URL/projects?with_counts=true" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {name, task_count, open_count}'

Create Project

curl -s "$YATTA_API_URL/projects" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Redesign",
    "description": "Complete overhaul of company site",
    "color": "#3b82f6",
    "icon": "🌐"
  }' \
  | jq '.'

Update Project

PROJECT_ID="uuid-of-project"
curl -s -X PUT "$YATTA_API_URL/projects" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "'$PROJECT_ID'",
    "name": "Website Redesign v2",
    "archived": false
  }' \
  | jq '.'

Get Project Tasks

PROJECT_ID="uuid-of-project"
curl -s "$YATTA_API_URL/projects/$PROJECT_ID/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Contexts API

List Contexts

# All contexts
curl -s "$YATTA_API_URL/contexts" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

# With task counts
curl -s "$YATTA_API_URL/contexts?with_counts=true" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {name, task_count}'

Create Context

curl -s "$YATTA_API_URL/contexts" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@deep-focus",
    "color": "#8b5cf6",
    "icon": "🧠"
  }' \
  | jq '.'

Assign Context to Task

TASK_ID="uuid-of-task"
CONTEXT_ID="uuid-of-context"

curl -s -X POST "$YATTA_API_URL/contexts/assign" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "'$TASK_ID'",
    "context_ids": ["'$CONTEXT_ID'"]
  }' \
  | jq '.'

Get Task Contexts

TASK_ID="uuid-of-task"
curl -s "$YATTA_API_URL/tasks/$TASK_ID/contexts" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Get Context Tasks

CONTEXT_ID="uuid-of-context"
curl -s "$YATTA_API_URL/contexts/$CONTEXT_ID/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Comments API

List Task Comments

TASK_ID="uuid-of-task"
curl -s "$YATTA_API_URL/tasks/$TASK_ID/comments" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Add Comment

TASK_ID="uuid-of-task"
curl -s -X POST "$YATTA_API_URL/tasks/$TASK_ID/comments" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Waiting on client feedback before proceeding"
  }' \
  | jq '.'

Update Comment

COMMENT_ID="uuid-of-comment"
curl -s -X PUT "$YATTA_API_URL/task-comments" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "'$COMMENT_ID'",
    "content": "Client responded, moving forward"
  }' \
  | jq '.'

Delete Comment

COMMENT_ID="uuid-of-comment"
curl -s -X DELETE "$YATTA_API_URL/task-comments" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "'$COMMENT_ID'"
  }' \
  | jq '.'

Follow-Ups API

Get Today's Follow-Ups

curl -s "$YATTA_API_URL/follow-ups" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {title, delegated_to, follow_up_date}'

Get Follow-Ups for Date

DATE="2026-02-15"
curl -s "$YATTA_API_URL/follow-ups?date=$DATE" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Mark Follow-Up Complete

TASK_ID="uuid-of-task"
curl -s -X POST "$YATTA_API_URL/tasks/$TASK_ID/follow-up" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  | jq '.'

Update Follow-Up Schedule

TASK_ID="uuid-of-task"
curl -s -X PUT "$YATTA_API_URL/tasks/$TASK_ID/follow-up-schedule" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "every_n_days",
    "interval": 3,
    "next_follow_up": "2026-02-12"
  }' \
  | jq '.'

Calendar API

List Calendar Subscriptions

curl -s "$YATTA_API_URL/calendar/subscriptions" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Add Calendar Subscription

curl -s -X POST "$YATTA_API_URL/calendar/subscriptions" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work Calendar",
    "ical_url": "https://calendar.google.com/calendar/ical/...",
    "default_context_id": "context-uuid"
  }' \
  | jq '.'

Trigger Calendar Sync

SUBSCRIPTION_ID="uuid-of-subscription"
curl -s -X POST "$YATTA_API_URL/calendar/subscriptions/$SUBSCRIPTION_ID/sync" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

List Calendar Events

# Events for date range
START="2026-02-10"
END="2026-02-17"
curl -s "$YATTA_API_URL/calendar/events?start=$START&end=$END" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Capacity API

Get Today's Capacity

curl -s "$YATTA_API_URL/capacity/today" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '{date, utilization_percent, status, used_minutes, total_minutes}'

Get Capacity for Date Range

START="2026-02-10"
END="2026-02-17"
curl -s "$YATTA_API_URL/capacity?start=$START&end=$END" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.[] | {date, status, utilization_percent}'

Trigger Capacity Computation

curl -s -X POST "$YATTA_API_URL/capacity/compute" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Analytics API

Get Summary Insights

curl -s "$YATTA_API_URL/analytics/summary" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Get Velocity Metrics

curl -s "$YATTA_API_URL/analytics/velocity" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Get Task Distribution

curl -s "$YATTA_API_URL/analytics/distribution" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '{by_status, by_priority, by_matrix_state}'

Get Streaks

curl -s "$YATTA_API_URL/analytics/streaks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Get AI Insights

curl -s "$YATTA_API_URL/analytics/insights" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '.'

Matrix Endpoint

Get Eisenhower Matrix View

curl -s "$YATTA_API_URL/tasks/matrix" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq '{do_first, schedule, delegate, eliminate}'

Common Patterns

Daily Workflow Automation

Morning briefing:

#!/bin/bash
echo "=== Today's Tasks ==="
curl -s "$YATTA_API_URL/tasks?status=todo&due_date_lte=$(date +%Y-%m-%d)" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq -r '.[] | "- [\(.priority)] \(.title)"'

echo ""
echo "=== Follow-Ups Due ==="
curl -s "$YATTA_API_URL/follow-ups" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq -r '.[] | "- \(.title) (delegated to: \(.delegated_to))"'

echo ""
echo "=== Capacity Status ==="
curl -s "$YATTA_API_URL/capacity/today" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq -r '"Utilization: \(.utilization_percent)% - \(.status)"'

Create Task from Email

#!/bin/bash
# Extract email subject and body
SUBJECT="$1"
BODY="$2"

curl -s "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "'"$SUBJECT"'",
    "description": "'"$BODY"'",
    "priority": "medium",
    "import_source": "email"
  }' \
  | jq -r '"Task created: \(.title)"'

Weekly Planning Report

#!/bin/bash
WEEK_START=$(date -v+mon "+%Y-%m-%d")
WEEK_END=$(date -v+sun "+%Y-%m-%d")

echo "=== Week of $WEEK_START ==="
curl -s "$YATTA_API_URL/capacity?start=$WEEK_START&end=$WEEK_END" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq -r '.[] | "\(.date): \(.status) (\(.utilization_percent)%)"'

echo ""
echo "=== Tasks Due This Week ==="
curl -s "$YATTA_API_URL/tasks?due_date_gte=$WEEK_START&due_date_lte=$WEEK_END" \
  -H "Authorization: Bearer $YATTA_API_KEY" \
  | jq -r '.[] | "[\(.due_date)] \(.title)"'

Error Handling

Check response status:

RESPONSE=$(curl -s -w "\n%{http_code}" "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY")

STATUS=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$STATUS" -eq 200 ]; then
  echo "$BODY" | jq '.'
else
  echo "Error: HTTP $STATUS"
  echo "$BODY" | jq '.error'
fi

Rate limit handling:

RESPONSE=$(curl -s -i "$YATTA_API_URL/tasks" \
  -H "Authorization: Bearer $YATTA_API_KEY")

# Check X-RateLimit headers
REMAINING=$(echo "$RESPONSE" | grep -i "X-RateLimit-Remaining" | cut -d' ' -f2)
RESET=$(echo "$RESPONSE" | grep -i "X-RateLimit-Reset" | cut -d' ' -f2)

if [ "$REMAINING" -lt 10 ]; then
  echo "Warning: Only $REMAINING requests remaining"
  echo "Rate limit resets at: $(date -r $RESET)"
fi

Tips

• Store API key securely: Use 1Password CLI, env vars, or secrets manager
• Use jq for filtering: Pipe responses through jq for clean output
• Batch operations: Update multiple tasks at once when possible
• Rate limits: 100 requests/minute per API key
• Date formats: Always use ISO 8601 (YYYY-MM-DD for dates, YYYY-MM-DDTHH:MM:SSZ for timestamps)
• Error responses: Include error field with description

Resources

• API Documentation: Yatta! API Docs (coming soon)
• GitHub Repo: https://github.com/chrisagiddings/openclaw-yatta-skill
• Report Issues: https://github.com/chrisagiddings/openclaw-yatta-skill/issues

API URL Note

Currently using the direct Supabase Edge Functions URL for reliability:

https://zunahvofybvxpptjkwxk.supabase.co/functions/v1

Branded URLs (yattadone.com/api) will be available in a future release once proxy configuration is resolved with the hosting provider.