Motion

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

Reference

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

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

List Workspaces

GET /motion/v1/workspaces

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

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

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}

List Schedules

GET /motion/v1/schedules

List Statuses

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

Query Parameters:

• workspaceId (string, required) - Filter by workspace

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

Resources

• Motion API Documentation
• Motion API Reference
• Motion Cookbooks