Autotask REST API learnings: task creation, phases, attachments, and update patterns

[asachs01]

Autotask REST API Patterns Discovered During Real-World Usage

These learnings were gathered during a live project setup session (ChSCC Azure Monitoring Migration, Project 299). They should inform MCP server improvements to make task/project management actually work.

---

1. Zone Detection is Critical

The API user's zone MUST be detected via the zone info endpoint before any calls:

GET https://webservices24.autotask.net/ATServicesRest/V1.0/zoneInformation?user=<email>

Returns the correct base URL (e.g., webservices14 not webservices24). Using the wrong zone returns empty responses or 401. The MCP server should auto-detect and cache the zone on first call.

2. Task Creation Requires taskType

taskType is a required field on Tasks but is not exposed in the MCP autotask_create_task tool schema. Valid values:

• 1 = FixedWork
• 2 = FixedDuration

Without it, the API returns: "Value does not reference an existing entity for taskType"

3. Task Endpoint Path is /Projects/{id}/Tasks

Tasks live under projects. The correct creation endpoint is:

POST /V1.0/Projects/{projectID}/Tasks

NOT /V1.0/Tasks (which returns 404).

4. parentTaskID Does NOT Work for Nesting

Setting parentTaskID on task creation silently fails — the field is accepted but not persisted. Autotask uses Phases (not parent-child tasks) for grouping.

5. Phase-Based Task Organization

To nest tasks under phases:

1. Create phases via POST /V1.0/Projects/{id}/Phases (required fields: projectID, title)
2. Assign tasks to phases via PATCH /V1.0/Projects/{id}/Tasks with {"id": <taskID>, "phaseID": <phaseID>}

Note: Phase creation requires going through the project-scoped endpoint. Top-level /V1.0/Phases returns 404 for POST.

6. PATCH Endpoint for Tasks

Task updates use PATCH on the collection endpoint, NOT on the individual task:

• Correct: PATCH /V1.0/Projects/{id}/Tasks with {"id": <taskID>, ...fields...}
• Wrong: PATCH /V1.0/Projects/{id}/Tasks/{taskID} (this was never tested but the collection approach works)

7. Tasks Cannot Be Deleted via API

DELETE /V1.0/Projects/{id}/Tasks/{taskID} returns 405 Method Not Allowed. The only way to "remove" tasks is to set their status to Complete (5) via PATCH. Consider renaming them to indicate deprecation.

8. Ticket Note Creation Returns 500

POST /V1.0/Tickets/{id}/Notes consistently returns 500. May be a field validation issue or an MCP server bug in how it constructs the request body. The noteType and publish picklist values for ticket notes may differ from what the MCP server sends.

9. Project Attachments Work

File attachments to projects work via:

POST /V1.0/Projects/{id}/Attachments

Required fields:

• attachmentType: "FILE_ATTACHMENT"
• parentID: project ID
• parentType: 3 (Project)
• publish: 1 (All Autotask Users)
• title: display name
• fullPath: filename
• contentType: MIME type
• data: base64-encoded file content

10. Task Status Picklist Values

The MCP server's autotask_get_field_info for Tasks.status returns Ticket status values, not Task status values. Task statuses are: 1=New, 5=Complete (confirmed working). The entity type routing in field info lookup appears broken.

---

Recommended MCP Server Changes

1. Auto-detect API zone on initialization and cache it
2. Add taskType parameter to autotask_create_task (default to 1/FixedWork)
3. Fix endpoint path for task creation to use /Projects/{id}/Tasks
4. Add phase management tools: autotask_create_phase, autotask_list_phases
5. Add task-to-phase assignment via PATCH on collection endpoint
6. Add attachment upload tool for projects and tickets
7. Fix autotask_get_field_info entity type routing (Tasks vs Tickets)
8. Fix autotask_create_ticket_note — investigate 500 error
9. Document that tasks cannot be deleted — provide "complete and rename" as workaround
10. Fix PATCH routing — use collection endpoint pattern for updates

API Credentials for Testing

Stored in 1Password (my.1password.com, WYRE vault, "Autotask API" item). Zone: AE02 (webservices14.autotask.net).

[asachs01]

All actionable items from this issue have been addressed in v2.15.1 (PR #48):

• ✅ Task creation endpoint fixed to use /Projects/{id}/Tasks
• ✅ Task updates use collection-level PATCH pattern
• ✅ taskType parameter added (defaults to FixedWork)
• ✅ Phase management tools added (autotask_create_phase, autotask_list_phases)
• ✅ Field info entity mapping fixed (Tasks → ProjectTasks)
• ✅ Ticket note 500 error fixed (missing required field defaults)

Remaining items for future work:

• Zone auto-detection (Feature Request: Add autotask-mcp to Docker MCP Registry #23 scope)
• Attachment upload tools
• Document task deletion limitation in tool descriptions