asana

# Asana Access the Asana API with managed OAuth authentication. Manage tasks, projects, workspaces, users, and webhooks for work management. ## Quick Start ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks?project=PROJECT_GID') 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/asana/{native-api-path} ``` Replace `{native-api-path}` with the actual Asana API endpoint path. The gateway proxies requests to `app.asana.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`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Asana OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=asana&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 ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'asana'}).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 ```bash 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:** ```json { "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": "asana", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash 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 Asana connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks?project=PROJECT_GID') 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 ### Tasks #### Get Multiple Tasks ```bash GET /asana/api/1.0/tasks ``` Query parameters: - `project` - Project GID to filter tasks - `assignee` - User GID or "me" for assigned tasks - `workspace` - Workspace GID (required if no project specified) - `completed_since` - ISO 8601 date to filter tasks completed after this date - `opt_fields` - Comma-separated list of fields to include **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks?project=1234567890&opt_fields=name,completed,due_on') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "data": [ { "gid": "1234567890", "name": "Review quarterly report", "completed": false, "due_on": "2025-03-15" } ] } ``` #### Get a Task ```bash GET /asana/api/1.0/tasks/{task_gid} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks/1234567890') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Create a Task ```bash POST /asana/api/1.0/tasks Content-Type: application/json { "data": { "name": "New task", "projects": ["PROJECT_GID"], "assignee": "USER_GID", "due_on": "2025-03-20", "notes": "Task description here" } } ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'name': 'Complete API integration', 'projects': ['1234567890'], 'due_on': '2025-03-20'}}).encode() req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/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 a Task ```bash PUT /asana/api/1.0/tasks/{task_gid} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'completed': True}}).encode() req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks/1234567890', data=data, method='PUT') 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 ``` #### Delete a Task ```bash DELETE /asana/api/1.0/tasks/{task_gid} ``` #### Get Tasks from a Project ```bash GET /asana/api/1.0/projects/{project_gid}/tasks ``` #### Get Subtasks ```bash GET /asana/api/1.0/tasks/{task_gid}/subtasks ``` #### Create Subtask ```bash POST /asana/api/1.0/tasks/{task_gid}/subtasks Content-Type: application/json { "data": { "name": "Subtask name", "assignee": "USER_GID", "due_on": "2025-03-20" } } ``` #### Search Tasks (Premium) **Note:** This endpoint requires an Asana Premium subscription. ```bash GET /asana/api/1.0/workspaces/{workspace_gid}/tasks/search ``` Query parameters: - `text` - Text to search for - `assignee.any` - Filter by assignees - `projects.any` - Filter by projects - `completed` - Filter by completion status ### Projects #### Get Multiple Projects ```bash GET /asana/api/1.0/projects ``` Query parameters: - `workspace` - Workspace GID - `team` - Team GID - `opt_fields` - Comma-separated list of fields **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/projects?workspace=1234567890&opt_fields=name,owner,due_date') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "data": [ { "gid": "1234567890", "name": "Q1 Marketing Campaign", "owner": { "gid": "0987654321", "name": "Alice Johnson" }, "due_date": "2025-03-31" } ] } ``` #### Get a Project ```bash GET /asana/api/1.0/projects/{project_gid} ``` #### Create a Project ```bash POST /asana/api/1.0/projects ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'name': 'New Project', 'workspace': '1234567890', 'notes': 'Project description'}}).encode() req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/projects', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')