{"slug":"autotask-api-patterns","title":"Autotask API Patterns","summary":"Autotask REST API fundamentals: header-based authentication, zone detection, the query/filter DSL (14 operators, logical grouping, includes), pagination, rate limits, and CRUD conventions across the 215+ entity PSA.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-21T18:26:34.735557Z","repo":{"url":"https://github.com/WYRE-AI/msp-claude-plugins","stars":46,"forks":26,"license":"Apache-2.0","updatedAt":"2026-09-21T16:51:26Z"},"bodyHtml":"
\n

name: \"Autotask API Patterns\"\ndescription: >\nAutotask REST API fundamentals: header-based authentication, zone\ndetection, the query/filter DSL (14 operators, logical grouping,\nincludes), pagination, rate limits, and CRUD conventions across the\n215+ entity PSA.\nwhen_to_use: >-\nWhen working with authentication, query building, pagination, includes, rate limiting, and error\nhandling in the Autotask REST API. Use when: autotask api, autotask query, autotask\nauthentication, api filter, query builder, autotask pagination, api rate limit, autotask zone,\napi error, or autotask rest.

\n

Autotask API Patterns

\n

Overview

\n

The Autotask REST API provides access to 215+ entities across the PSA. This skill covers authentication, query building, pagination, error handling, and performance optimization patterns.

\n

Anti-triggers

\n\n

Authentication

\n

Header-Based Authentication

\n

Autotask uses header-based authentication (NOT Basic Auth):

\n
GET /v1.0/Tickets\nApiIntegrationCode: YOUR_INTEGRATION_CODE\nUserName: your-api-user@domain.com\nSecret: YOUR_SECRET\nContent-Type: application/json\n
\n

Required Headers:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HeaderDescription
ApiIntegrationCodeYour Autotask integration code
UserNameAPI username (email address)
SecretAPI secret/password
Content-Typeapplication/json
\n

Environment Variables

\n
export AUTOTASK_USERNAME=\"your-api-user@domain.com\"\nexport AUTOTASK_INTEGRATION_CODE=\"YOUR_INTEGRATION_CODE\"\nexport AUTOTASK_SECRET=\"YOUR_SECRET\"\n
\n

Automatic Zone Detection

\n

Autotask operates in multiple zones. The API can automatically detect your zone:

\n
GET https://webservices.autotask.net/atservicesrest/v1.0/ZoneInformation\nUserName: your-api-user@domain.com\n
\n

Response:

\n
{\n  \"url\": \"https://webservices5.autotask.net/atservicesrest\",\n  \"webUrl\": \"https://ww5.autotask.net\"\n}\n
\n

Common Zones:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ZoneAPI URL
webserviceshttps://webservices.autotask.net/atservicesrest
webservices1https://webservices1.autotask.net/atservicesrest
webservices2https://webservices2.autotask.net/atservicesrest
webservices5https://webservices5.autotask.net/atservicesrest
webservices6https://webservices6.autotask.net/atservicesrest
\n

Query Builder

\n

Query Operators

\n

The Autotask API supports 14 query operators:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperatorDescriptionExample
eqEquals{\"field\": \"status\", \"op\": \"eq\", \"value\": 1}
ne / noteqNot equals{\"field\": \"status\", \"op\": \"noteq\", \"value\": 5}
gtGreater than{\"field\": \"priority\", \"op\": \"gt\", \"value\": 2}
gteGreater than or equal{\"field\": \"createDate\", \"op\": \"gte\", \"value\": \"2024-01-01\"}
ltLess than{\"field\": \"priority\", \"op\": \"lt\", \"value\": 3}
lteLess than or equal{\"field\": \"dueDateTime\", \"op\": \"lte\", \"value\": \"2024-02-15T17:00:00Z\"}
containsContains substring{\"field\": \"title\", \"op\": \"contains\", \"value\": \"email\"}
startsWithStarts with{\"field\": \"companyName\", \"op\": \"startsWith\", \"value\": \"Acme\"}
endsWithEnds with{\"field\": \"email\", \"op\": \"endsWith\", \"value\": \"@acme.com\"}
inIn array{\"field\": \"status\", \"op\": \"in\", \"value\": [1, 2, 5]}
notInNot in array{\"field\": \"status\", \"op\": \"notIn\", \"value\": [5, 10]}
isNullIs null{\"field\": \"assignedResourceId\", \"op\": \"isNull\"}
isNotNullIs not null{\"field\": \"dueDateTime\", \"op\": \"isNotNull\"}
betweenBetween range{\"field\": \"createDate\", \"op\": \"between\", \"value\": [\"2024-01-01\", \"2024-01-31\"]}
\n

Date Filtering: \"Today\" Queries

\n

CRITICAL: To filter for records from \"today\", you must use a range — gte today's date AND lt tomorrow's date. Using only today's date (e.g. eq or a single filter on today) returns zero results. \"Today\" in Autotask means: created on or after today's midnight, but before tomorrow's midnight.

\n

Correct — \"tickets created today\":

\n
{\n  \"filter\": [\n    {\"field\": \"createDate\", \"op\": \"gte\", \"value\": \"2026-04-13T00:00:00Z\"},\n    {\"field\": \"createDate\", \"op\": \"lt\", \"value\": \"2026-04-14T00:00:00Z\"}\n  ]\n}\n
\n

Wrong — returns NO results:

\n
{\n  \"filter\": [\n    {\"field\": \"createDate\", \"op\": \"eq\", \"value\": \"2026-04-13\"}\n  ]\n}\n
\n

Always compute \"tomorrow\" dynamically. For example:

\n
const today = new Date();\ntoday.setHours(0, 0, 0, 0);\nconst tomorrow = new Date(today);\ntomorrow.setDate(tomorrow.getDate() + 1);\n\nconst todayISO = today.toISOString(); // \"2026-04-13T00:00:00.000Z\"\nconst tomorrowISO = tomorrow.toISOString(); // \"2026-04-14T00:00:00.000Z\"\n
\n

This pattern applies to all datetime fields (createDate, lastActivityDate, dueDateTime, startDateTime, endDateTime, dateWorked, etc.) across all entities — not just tickets.

\n

Query Structure

\n
POST /v1.0/Tickets/query\nContent-Type: application/json\n
\n
{\n  \"filter\": [\n    {\"field\": \"companyID\", \"op\": \"eq\", \"value\": 12345},\n    {\"field\": \"status\", \"op\": \"noteq\", \"value\": 5}\n  ],\n  \"maxRecords\": 50,\n  \"includeFields\": [\"Company.companyName\", \"AssignedResource.firstName\"]\n}\n
\n

Complex Queries with Logical Grouping

\n

Filters combine with implicit AND. Use \"op\": \"or\" / \"op\": \"and\" with an items array to group or nest conditions:

\n
{\n  \"filter\": [\n    {\"field\": \"companyID\", \"op\": \"eq\", \"value\": 12345},\n    {\n      \"op\": \"or\",\n      \"items\": [\n        {\"field\": \"priority\", \"op\": \"eq\", \"value\": 1},\n        {\"field\": \"status\", \"op\": \"eq\", \"value\": 14}\n      ]\n    }\n  ]\n}\n
\n

See references/api.md for an AND-only example and a nested AND/OR example.

\n

Field Includes

\n

Retrieve related entity fields in a single request:

\n
{\n  \"filter\": [{\"field\": \"id\", \"op\": \"gt\", \"value\": 0}],\n  \"includeFields\": [\n    \"Company.companyName\",\n    \"AssignedResource.firstName\",\n    \"AssignedResource.lastName\"\n  ]\n}\n
\n

See references/api.md for the response shape returned when includes are used.

\n

Pagination

\n

Request Pagination

\n
{\n  \"filter\": [{\"field\": \"id\", \"op\": \"gt\", \"value\": 0}],\n  \"maxRecords\": 100,\n  \"pageNumber\": 1\n}\n
\n

Pagination Fields:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescriptionMax
maxRecordsRecords per page500
pageNumberCurrent page (1-based)-
\n

Response Structure

\n
{\n  \"items\": [...],\n  \"pageDetails\": {\n    \"count\": 100,\n    \"nextPageUrl\": \"/v1.0/Tickets/query?pageNumber=2\",\n    \"prevPageUrl\": null,\n    \"requestCount\": 2847\n  }\n}\n
\n

Page through results by looping while pageDetails.nextPageUrl is non-null. See references/examples.md for a full pagination loop implementation.

\n

Rate Limiting

\n

Autotask API Hard Limits

\n

Autotask enforces two hard limits:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
LimitValueScope
Concurrent threads per endpoint3Per API tracking identifier (your integrationCode)
Total requests per hour10,000Per Autotask tenant database (all integrations combined)
\n

Concurrent thread limit is the most common cause of slowdowns in LLM-driven integrations. When Claude issues several tool calls in parallel (e.g., tickets search + companies search + contacts search), all three may target the Tickets endpoint simultaneously and hit the 3-thread cap.

\n

When using the MCP server or autotask-node SDK, this is handled automatically — excess requests are queued and released as slots free up, so you won't see hard failures, but responses may be slower under load.

\n

Multi-user / shared key risk: The 3-thread limit applies per integrationCode. If multiple users or teams share the same credentials, they compete for the same 3 slots. In a team deployment, give each team their own API user:

\n
Support Team  → integrationCode: SUPPORT_TEAM_CODE  (3 threads, independent)\nProjects Team → integrationCode: PROJECTS_TEAM_CODE (3 threads, independent)\n
\n

Rate Limit Response

\n

When the concurrent thread limit or hourly request limit is exceeded (HTTP 429):

\n
{\n  \"errors\": [\n    {\n      \"message\": \"Rate limit exceeded. Try again in 30 seconds.\"\n    }\n  ]\n}\n
\n

Implement exponential backoff with jitter on 429 responses, honoring Retry-After when present. See references/examples.md for a retry-with-backoff implementation.

\n

Query Different Entity Types in Parallel

\n

To maximize throughput without hitting the per-endpoint thread limit, query different endpoints in parallel rather than the same endpoint multiple times — parallel requests to Tickets + Companies + Contacts each get their own 3-thread budget, while parallel requests to multiple pages of the same endpoint share one budget and queue.

\n

For bulk write operations, batch requests in groups (e.g. 50 at a time) with a short delay between batches to avoid the hourly limit. See references/examples.md for parallel-query and batch-processing code.

\n

Error Handling

\n

HTTP Status Codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CodeMeaningAction
200SuccessProcess response
201CreatedEntity created successfully
400Bad RequestCheck request format/values
401UnauthorizedVerify credentials
403ForbiddenCheck permissions
404Not FoundEntity doesn't exist
409ConflictResource locked/modified
429Rate LimitedImplement backoff
500Server ErrorRetry with backoff
\n

Error Response Format

\n
{\n  \"errors\": [\n    {\n      \"message\": \"The value '999' is not valid for field 'status'.\",\n      \"field\": \"status\",\n      \"value\": 999\n    }\n  ]\n}\n
\n

When a field-level error is returned, cross-reference the field against /v1.0/<Entity>/entityInformation/fields (or /v1.0/Queues for queue IDs) to find valid values. See references/examples.md for a full validation-error handler.

\n

Entity Information

\n

Query field definitions and picklist values before writing to an unfamiliar entity:

\n
GET /v1.0/Tickets/entityInformation/fields\nGET /v1.0/Tickets/entityInformation/userDefinedFields\n
\n

See references/api.md for the full response shape and CRUD (create/read/update/replace/delete) request examples.

\n

Performance Optimization

\n

Select Only Needed Fields

\n
{\n  \"filter\": [{\"field\": \"id\", \"op\": \"gt\", \"value\": 0}],\n  \"fields\": [\"id\", \"title\", \"status\", \"priority\"]\n}\n
\n

Use Efficient Filters

\n

Good - Uses indexed field:

\n
{\"field\": \"companyID\", \"op\": \"eq\", \"value\": 12345}\n
\n

Avoid - Full text search:

\n
{\"field\": \"description\", \"op\": \"contains\", \"value\": \"error\"}\n
\n

Cache Reference Data

\n

Cache slowly-changing data — Queues, Resources, Issue Types, Priorities, Company lists — rather than re-fetching per request. See references/examples.md for a TTL-based cache pattern.

\n

Best Practices

\n
    \n
  1. Detect zone once - Cache the zone URL after initial detection
    2. \n
  2. Use includes - Avoid N+1 queries by including related data
    3. \n
  3. Paginate large results - Never fetch unbounded result sets
    4. \n
  4. Implement retry logic - Handle rate limits and transient errors
    5. \n
  5. Cache reference data - Reduce API calls for static lookups
    6. \n
  6. Select specific fields - Only request fields you need
    7. \n
  7. Use batch operations - Group related operations together
    8. \n
  8. One API key per team - Autotask limits 3 concurrent threads per integrationCode. Each team using the integration should have their own API user so they don't compete for the same thread budget
    9. \n
  9. Parallelize across endpoints, not within - To maximize throughput, query Tickets + Companies + Contacts simultaneously (different endpoints, independent thread budgets) rather than fetching multiple pages of the same endpoint in parallel
    10. \n
\n

Related Skills

\n\n","files":[{"path":"references/api.md","sizeBytes":2668,"isText":true},{"path":"references/examples.md","sizeBytes":3576,"isText":true},{"path":"SKILL.md","sizeBytes":12652,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-21T18:26:58.807694Z","sha256":"C1A0C803DD26659487B9E5CFECD092FCAF8E20D698590683499D0C60301AA97D","sizeBytes":7355},"review":null,"source":{"repositoryUrl":"https://github.com/WYRE-AI/msp-claude-plugins","path":"msp-claude-plugins/kaseya/autotask/skills/api-patterns","license":"Apache-2.0","commit":"147da75a83127bb77f9551efdbf66adf62823c05","subtreeSha":"FBCFEB60833FECAA8BF79A2AE0824E4D97BA73DA49342625A8FDD1698771068B","lastSyncedAt":"2026-09-21T18:26:31.557491Z"},"reviewedAt":"2026-09-21T18:27:50.230212Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/WYRE-AI/msp-claude-plugins/tree/main/msp-claude-plugins/kaseya/autotask/skills/api-patterns"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install wyre-ai-msp-claude-plugins@llmmart"},{"target":"git","command":"git clone https://github.com/WYRE-AI/msp-claude-plugins.git"}]}