🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Motion
πŸ¦€ ClawHub

Motion

by @byungkyu

Motion API integration with managed OAuth. Manage tasks, projects, workspaces, and more with AI-powered scheduling. Use this skill when users want to create,...

Versionv1.0.1
Downloads1,373
#crypto-defi#security#legal#productivity
TERMINAL
clawhub install motion

πŸ“– About This Skill

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://api.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://api.maton.ai/motion/{native-api-path}

Maton 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://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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://api.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://api.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": "{connection_id}",
    "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://api.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://api.maton.ai/motion/v1/tasks')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

  • Access is scoped to tasks, projects, workspaces, and more with AI-powered scheduling within the connected Motion account.
  • All write operations require explicit user approval. Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.

    • 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://api.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://api.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

    • Optional Fields:

  • dueDate (datetime, ISO 8601) - Project deadline
  • description (string) - HTML input accepted
  • labels (array) - Label names
  • priority (string) - ASAP, HIGH, MEDIUM (default), or LOW
  • projectDefinitionId (string) - Template ID (requires stages array if provided)
  • stages (array) - Stage objects for project templates

    • Workspace Operations

    #### List Workspaces

    GET /motion/v1/workspaces

    User Operations

    #### List Users

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

    Query Parameters:

  • workspaceId (string) - Workspace ID (required if no teamId)
  • teamId (string) - Team ID (required if no workspaceId)

    • Note: You must provide either workspaceId or teamId.

    #### Get Current User

    GET /motion/v1/users/me

    Comment Operations

    #### List Comments

    GET /motion/v1/comments?taskId={taskId}

    Query Parameters:

  • taskId (string, required) - Filter comments by task
  • cursor (string) - Pagination cursor

    • #### Create Comment

    POST /motion/v1/comments
Content-Type: application/json
    {
  "taskId": "TASK_ID",
  "content": "Comment in GitHub Flavored Markdown"
}

    Required Fields:

  • taskId (string) - Task to comment on

    • Optional Fields:

  • content (string) - Comment content in GitHub Flavored Markdown

    • Recurring Task Operations

    #### List Recurring Tasks

    GET /motion/v1/recurring-tasks?workspaceId={workspaceId}

    Query Parameters:

  • workspaceId (string, required) - Filter by workspace
  • cursor (string) - Pagination cursor

    • #### Create Recurring Task

    POST /motion/v1/recurring-tasks
Content-Type: application/json
    {
  "name": "Weekly review",
  "workspaceId": "WORKSPACE_ID",
  "frequency": "weekly"
}

    #### Delete Recurring Task

    DELETE /motion/v1/recurring-tasks/{recurringTaskId}

    Schedule Operations

    #### List Schedules

    GET /motion/v1/schedules

    Status Operations

    #### List Statuses

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

    Query Parameters:

  • workspaceId (string, required) - Filter by workspace

    • Custom Field Operations

    #### List Custom Fields

    GET /motion/v1/custom-fields

    #### Create Custom Field

    POST /motion/v1/custom-fields
Content-Type: application/json
    {
  "name": "Field name",
  "type": "text"
}

    #### Delete Custom Field

    DELETE /motion/v1/custom-fields/{customFieldId}

    #### Add Custom Field to Project

    POST /motion/v1/custom-fields/{customFieldId}/project
Content-Type: application/json
    {
  "projectId": "PROJECT_ID"
}

    #### Add Custom Field to Task

    POST /motion/v1/custom-fields/{customFieldId}/task
Content-Type: application/json
    {
  "taskId": "TASK_ID"
}

    #### Remove Custom Field from Project

    DELETE /motion/v1/custom-fields/{customFieldId}/project

    #### Remove Custom Field from Task

    DELETE /motion/v1/custom-fields/{customFieldId}/task

    Pagination

    Motion uses cursor-based pagination:

    GET /motion/v1/tasks?cursor=CURSOR_VALUE

    Response includes pagination metadata:

    {
  "tasks": [...],
  "meta": {
    "nextCursor": "abc123",
    "pageSize": 20
  }
}

    Use the nextCursor value in subsequent requests to retrieve more results.

    Code Examples

    JavaScript

    const response = await fetch(
  'https://api.maton.ai/motion/v1/tasks',
  {
    headers: {
      'Authorization': Bearer ${process.env.MATON_API_KEY}
    }
  }
);
const data = await response.json();

    Python

    import os
import requests
    response = requests.get(
    'https://api.maton.ai/motion/v1/tasks',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

    Notes

  • All timestamps use ISO 8601 format
  • Task descriptions support GitHub Flavored Markdown
  • Project descriptions accept HTML input
  • Priority values: ASAP, HIGH, MEDIUM, LOW
  • Deadline types for auto-scheduling: HARD, SOFT, NONE
  • Rate limits: 12 req/min (Individual), 120 req/min (Team)
  • IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
  • IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

    • Error Handling

    | Status | Meaning | |--------|---------| | 400 | Missing Motion connection or invalid request | | 401 | Invalid or missing Maton API key | | 429 | Rate limited | | 4xx/5xx | Passthrough error from Motion API |

    Resources

  • Motion API Documentation
  • Motion API Reference
  • Motion Cookbooks
  • Maton Community
  • Maton Support

    • πŸ’‘ Examples

    # List tasks
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

    πŸ“‹ Tips & Best Practices

  • All timestamps use ISO 8601 format
  • Task descriptions support GitHub Flavored Markdown
  • Project descriptions accept HTML input
  • Priority values: ASAP, HIGH, MEDIUM, LOW
  • Deadline types for auto-scheduling: HARD, SOFT, NONE
  • Rate limits: 12 req/min (Individual), 120 req/min (Team)
  • IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
  • IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments