--- name: motion description: | Motion API integration with managed OAuth. Manage tasks, projects, workspaces, and more with AI-powered scheduling. Use this skill when users want to create, update, or manage tasks and projects in Motion, or query their scheduled work. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 homepage: "https://maton.ai" requires: env: - MATON_API_KEY ---

Motion

Access the Motion API with managed OAuth authentication. Manage tasks, projects, workspaces, comments, and recurring tasks with full CRUD operations.

Quick Start

# List tasks
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/motion/v1/tasks')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/motion/{native-api-path}

Replace {native-api-path} with the actual Motion API endpoint path. The gateway proxies requests to api.usemotion.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Motion OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=motion&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'motion'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "motion",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Motion connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/motion/v1/tasks')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Task Operations

List Tasks

GET /motion/v1/tasks

Query Parameters:

• workspaceId (string) - Filter by workspace
• projectId (string) - Filter by project
• assigneeId (string) - Filter by assignee
• status (array) - Filter by status (cannot combine with includeAllStatuses)
• includeAllStatuses (boolean) - Return tasks across all statuses
• label (string) - Filter by label
• name (string) - Search task names (case-insensitive)
• cursor (string) - Pagination cursor

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/motion/v1/tasks?workspaceId=WORKSPACE_ID')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Task

GET /motion/v1/tasks/{taskId}

Create Task

POST /motion/v1/tasks
Content-Type: application/json

{
  "name": "Task name",
  "workspaceId": "WORKSPACE_ID",
  "dueDate": "2024-03-15T10:00:00Z",
  "duration": 60,
  "priority": "HIGH",
  "description": "Task description in markdown",
  "projectId": "PROJECT_ID",
  "assigneeId": "USER_ID",
  "labels": ["label1", "label2"],
  "autoScheduled": {
    "startDate": "2024-03-14T09:00:00Z",
    "deadlineType": "SOFT",
    "schedule": "Work Hours"
  }
}

Required Fields:

• name (string) - Task title
• workspaceId (string) - Workspace ID

Optional Fields:

• dueDate (datetime, ISO 8601) - Task deadline (required for scheduled tasks)
• duration (string | number) - "NONE", "REMINDER", or minutes (integer > 0)
• status (string) - Defaults to workspace default status
• projectId (string) - Associated project
• description (string) - GitHub Flavored Markdown supported
• priority (string) - ASAP, HIGH, MEDIUM, or LOW
• labels (array) - Label names to add
• assigneeId (string) - User ID for task assignment
• autoScheduled (object) - Auto-scheduling settings with startDate, deadlineType (HARD, SOFT, NONE), and schedule

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    'name': 'New task',
    'workspaceId': 'WORKSPACE_ID',
    'priority': 'HIGH',
    'duration': 30
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/motion/v1/tasks', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Update Task

PATCH /motion/v1/tasks/{taskId}
Content-Type: application/json

{
  "name": "Updated task name",
  "status": "Completed",
  "priority": "LOW"
}

Delete Task

DELETE /motion/v1/tasks/{taskId}

Move Task

POST /motion/v1/tasks/{taskId}/move
Content-Type: application/json

{
  "workspaceId": "NEW_WORKSPACE_ID"
}

Unassign Task

POST /motion/v1/tasks/{taskId}/unassign

Project Operations

List Projects

GET /motion/v1/projects?workspaceId={workspaceId}

Query Parameters:

• workspaceId (string, required) - Workspace ID
• cursor (string) - Pagination cursor

Get Project

GET /motion/v1/projects/{projectId}

Create Project

POST /motion/v1/projects
Content-Type: application/json

{
  "name": "Project name",
  "workspaceId": "WORKSPACE_ID",
  "description": "Project description",
  "dueDate": "2024-06-30T00:00:00Z",
  "priority": "HIGH",
  "labels": ["label1"]
}

Required Fields:

• name (string) - Project name
• workspaceId (string) - Workspace ID

...