Moovila Tools & API Patterns
Overview
Moovila is a project management platform built around PSA-connected
project delivery: projects belong to a customer organization, break into
phases and tasks, carry budget lines, and accumulate time entries from
users (resources). This plugin reaches Moovila's Public API report
endpoints through the WYRE Conduit gateway, which fronts the moovila-mcp
server.
Everything is read-only. Moovila's published Public API spec has 19
endpoints and every one is a GET, so no tool in this plugin can create,
change, or delete anything in Moovila. When a user asks Claude to update a
task, log time, or close a project, say plainly that the connection cannot
do it and point them to the Moovila UI.
Tool surface: 19 tools, all read tier
No Moovila tool is admin-gated in Conduit. All 19 are read tier, so any
Conduit user granted the Moovila connection can call any of them.
| Domain |
List |
Get one |
| Projects |
moovila_projects_list |
moovila_projects_get (projectID) |
| Budgets |
moovila_project_budgets_list |
moovila_project_budgets_get (projectID, returns all of that project's budget lines) |
| Phases |
moovila_phases_list |
moovila_phases_get (phaseID) |
| Tasks |
moovila_tasks_list, moovila_tasks_list_for_project (projectID required) |
moovila_tasks_get (taskID) |
| Time entries |
moovila_time_entries_list |
moovila_time_entries_get (timeEntryID) |
| Users |
moovila_users_list |
moovila_users_get (userID) |
| Products |
moovila_products_list |
moovila_products_get (productID) |
| Labor types |
moovila_labor_types_list |
moovila_labor_types_get (laborTypeID) |
| Resource types (deprecated) |
moovila_resource_types_list |
moovila_resource_types_get (resourceTypeID) |
moovila_resource_types_list and moovila_resource_types_get are
deprecated by Moovila and due to be removed. Use the labor type tools
instead; they return the same record shape.
None of the list tools take a customer, owner, status, or date-range
filter. The only server-side narrowing is lastChangedDate (projects,
budgets, phases, tasks, time entries) and projectID on
moovila_tasks_list_for_project. Every other filter is applied by Claude
after the page comes back.
Connection and authentication
Moovila uses OAuth 2.0 authorization code with refresh tokens, against an
App Registration the MSP creates in its own Moovila tenant. There is no
shared WYRE Moovila app.
- In Moovila, open App Registration (needs the Integrations
Manager permission and a plan that includes the API).
- Create an app for Conduit. Use Conduit's callback URL as the redirect
URL and tick the project, task, user, time entry and lookup table read
permissions.
- In Conduit, open Connections → Moovila, paste the Client ID and
Client Secret Moovila showed you, then sign in to Moovila to approve.
Conduit keeps the client secret and refresh token. On each call it sends
only the short-lived access token to the sidecar as the
X-Moovila-Access-Token header; the sidecar forwards it upstream as a
Bearer token. The plugin ships no .mcp.json (Claude Code reaches Conduit
through wyre-gateway at https://conduit.wyre.ai/v1/mcp), and no
credential lives on the technician's machine.
Moovila's help center says scopes are not enforced against the API, so the
token can read everything the consenting Moovila user can see. Consent
with a dedicated, least-privileged Moovila user, not an owner account.
Paging
Every list tool except the two lookup-table lists pages with offset +
limit.
limit defaults to 20 and accepts 1-100. A value over 100 is rejected,
not silently capped.
- Each call fetches exactly one page. For the next page, pass
offset + the number of records returned.
- Output is capped at 60,000 characters. A page over the cap is cut on a
record boundary and ends with a note giving how many records were shown
and the offset to resume from. Resume from that offset, not from
offset + limit.
- A page with fewer records than
limit, and no truncation note, is the
last page. A full page is never proof of the end.
moovila_labor_types_list and moovila_resource_types_list return the
whole table in one call and take no paging arguments.
Project records are about 2 KB each, so a limit of 100 on
moovila_projects_list usually triggers truncation. Keep the default of
20 for projects and tasks; time entries and users are smaller and page
well at 50-100.
Incremental pulls with lastChangedDate
lastChangedDate returns only records changed since a point in time. It
must be an ISO 8601 date-time with Z or a UTC offset, for example
2026-10-01T00:00:00Z. A zone-less value is rejected. Whether the bound
is inclusive has not been verified against a live tenant, so when exact
edges matter, step back a minute and de-duplicate on id.
It filters on change time, not on business date. A time entry worked in
September but edited in October appears in an October pull. The period
start is not a completeness bound: a task due in the period may not have
changed for months, and a pre-booked time entry may predate its
startTime. When you need every record, pull without lastChangedDate
and filter on startTime (time entries) or dueDate (tasks) yourself.
Use an earlier lastChangedDate only when the tenant confirms nothing
older can fall in the period, and say which bound you used.
IDs and lookups
Every ID is a GUID and is validated before any request is sent; a
non-GUID returns a validation error without calling Moovila.
Nested references come back as { id, name } objects, so most reports
need no second lookup: organization, customer, ownerUser, stage,
status on projects; ownerUser, status, costCode, billingCode on
tasks; user, status, costCode, billingCode on time entries. The
exception is resourceTypeID on users, tasks, time entries and budget
lines: resolve it against moovila_labor_types_list, which returns the
labor type's name, defaultBillingRate, fullyBurdenedCost, and the
workTargetBillable utilization target.
Fields that matter
| Record |
Key fields |
| Project |
name, organization, customer, ownerUser, stage, status, isComplete, isInactive, isTemplate, isDeleted, startDate, dueDate, forecastDate, projectValue, revenueType, rpaxScore |
| ProjectBudget |
projectID, category, costCode, budgetMethod, qty, unitCost, totalBudgetAmount, allocatedCost, unallocatedCost, percentageCommitted, resourceTypeID |
| Task |
projectID, phaseID, name, status, priority, ownerUser, startDate, dueDate, completionDate, isMilestone, percentageComplete, workEstimate, totalBudget, totalActual, remainingBudget, predecessorsComplete, isDeleted |
| TimeEntry |
projectID, taskID, user, status, startTime, endTime, totalHours, billableHours, billable, billRate, payRate, billingCode, costCode, timeEntryType (1 = time entry, 2 = time adjustment), notes |
| User |
displayName, emailAddress, active, jobTitle, supervisor, resourceTypeID, hourlyCost |
| Labor type |
name, category, isActive, defaultBillingRate, fullyBurdenedCost, workTargetBillable, workTargetTask, workTargetMeetings |
Status and stage names are tenant-configured. Read the name on the
object rather than assuming a fixed set of codes.
Fields such as prevailingWageID, excludePrevailingWage,
supervisorNotes, startDistanceToProject, endDistanceToProject and
totalBreakTime are only populated for Moovila Smart Construction
tenants. Empty values on an MSP tenant are expected.
Errors
| Status |
Meaning |
What to do |
| 400 |
Bad request |
Check the arguments, especially lastChangedDate format |
| 401 |
Access token invalid or expired |
Retry once; if it persists, reconnect Moovila in Conduit (token refresh has not yet been verified against a live tenant) |
| 403 |
The consenting Moovila user cannot read this data |
Widen that user's access in Moovila, or reconnect as a user who can see it |
| 404 |
Resource not found |
Re-list to confirm the ID; it may belong to a deleted record |
| 429 |
Rate limited |
If the error says "Retry after N s", wait that long; otherwise back off. Retry once |
| 5xx |
Moovila server error |
Retry later; do not loop |
Moovila documents no rate limits. Keep cross-customer sweeps to one page at
a time and avoid fanning out _get calls per record when the list already
carries the fields you need.
Gotchas
- Templates and deleted records come back in lists. Exclude projects
with
isTemplate or isDeleted true, and tasks with isDeleted true,
before counting anything.
organization versus customer on projects. Both are { id, name }
references. MSP tenants typically populate organization with the
client; check which one a tenant uses on the first page before grouping
by it.
- Time adjustments are rows too.
timeEntryType 2 marks an
adjustment, which can carry negative hours. Include adjustments in
totals; do not treat them as duplicate entries.
moovila_tasks_list_for_project requires projectID. For tasks
across every project, use moovila_tasks_list.
Related Skills
1---2name: moovila-api-patterns3description: >4 The Moovila tool surface as exposed through Conduit: the 19 read-only5 report tools and their tiers, the bring-your-own-client OAuth connection6 and the X-Moovila-Access-Token header Conduit injects, offset/limit7 paging with the 100-record cap and truncation notes, lastChangedDate8 incremental pulls, GUID validation, the record shapes (Project,9 ProjectBudget, Task, TimeEntry, User, labor type), and the error10 vocabulary.11when_to_use: >-12 When calling any Moovila tool, paging through a Moovila list, or13 diagnosing a Moovila connection failure. Use when: moovila api, moovila14 mcp, moovila tools, moovila auth, moovila 401, moovila pagination,15 moovila offset, lastChangedDate, or "can Claude change anything in16 Moovila".17metadata:18 source: https://skillmd.com/skills/wyre-ai/moovila-api-patterns19---2021# Moovila Tools & API Patterns2223## Overview2425Moovila is a project management platform built around PSA-connected26project delivery: projects belong to a customer organization, break into27phases and tasks, carry budget lines, and accumulate time entries from28users (resources). This plugin reaches Moovila's Public API report29endpoints through the WYRE Conduit gateway, which fronts the `moovila-mcp`30server.3132Everything is read-only. Moovila's published Public API spec has 1933endpoints and every one is a `GET`, so no tool in this plugin can create,34change, or delete anything in Moovila. When a user asks Claude to update a35task, log time, or close a project, say plainly that the connection cannot36do it and point them to the Moovila UI.3738## Tool surface: 19 tools, all read tier3940No Moovila tool is admin-gated in Conduit. All 19 are read tier, so any41Conduit user granted the Moovila connection can call any of them.4243| Domain | List | Get one |44|--------|------|---------|45| Projects | `moovila_projects_list` | `moovila_projects_get` (`projectID`) |46| Budgets | `moovila_project_budgets_list` | `moovila_project_budgets_get` (`projectID`, returns all of that project's budget lines) |47| Phases | `moovila_phases_list` | `moovila_phases_get` (`phaseID`) |48| Tasks | `moovila_tasks_list`, `moovila_tasks_list_for_project` (`projectID` required) | `moovila_tasks_get` (`taskID`) |49| Time entries | `moovila_time_entries_list` | `moovila_time_entries_get` (`timeEntryID`) |50| Users | `moovila_users_list` | `moovila_users_get` (`userID`) |51| Products | `moovila_products_list` | `moovila_products_get` (`productID`) |52| Labor types | `moovila_labor_types_list` | `moovila_labor_types_get` (`laborTypeID`) |53| Resource types (deprecated) | `moovila_resource_types_list` | `moovila_resource_types_get` (`resourceTypeID`) |5455`moovila_resource_types_list` and `moovila_resource_types_get` are56deprecated by Moovila and due to be removed. Use the labor type tools57instead; they return the same record shape.5859None of the list tools take a customer, owner, status, or date-range60filter. The only server-side narrowing is `lastChangedDate` (projects,61budgets, phases, tasks, time entries) and `projectID` on62`moovila_tasks_list_for_project`. Every other filter is applied by Claude63after the page comes back.6465## Connection and authentication6667Moovila uses OAuth 2.0 authorization code with refresh tokens, against an68App Registration the MSP creates in its own Moovila tenant. There is no69shared WYRE Moovila app.70711. In Moovila, open **App Registration** (needs the **Integrations72 Manager** permission and a plan that includes the API).732. Create an app for Conduit. Use Conduit's callback URL as the redirect74 URL and tick the project, task, user, time entry and lookup table read75 permissions.763. In Conduit, open **Connections → Moovila**, paste the Client ID and77 Client Secret Moovila showed you, then sign in to Moovila to approve.7879Conduit keeps the client secret and refresh token. On each call it sends80only the short-lived access token to the sidecar as the81`X-Moovila-Access-Token` header; the sidecar forwards it upstream as a82Bearer token. The plugin ships no `.mcp.json` (Claude Code reaches Conduit83through `wyre-gateway` at `https://conduit.wyre.ai/v1/mcp`), and no84credential lives on the technician's machine.8586Moovila's help center says scopes are not enforced against the API, so the87token can read everything the consenting Moovila user can see. Consent88with a dedicated, least-privileged Moovila user, not an owner account.8990## Paging9192Every list tool except the two lookup-table lists pages with `offset` +93`limit`.9495- `limit` defaults to 20 and accepts 1-100. A value over 100 is rejected,96 not silently capped.97- Each call fetches exactly one page. For the next page, pass98 `offset` + the number of records returned.99- Output is capped at 60,000 characters. A page over the cap is cut on a100 record boundary and ends with a note giving how many records were shown101 and the offset to resume from. Resume from that offset, not from102 `offset + limit`.103- A page with fewer records than `limit`, and no truncation note, is the104 last page. A full page is never proof of the end.105- `moovila_labor_types_list` and `moovila_resource_types_list` return the106 whole table in one call and take no paging arguments.107108Project records are about 2 KB each, so a `limit` of 100 on109`moovila_projects_list` usually triggers truncation. Keep the default of11020 for projects and tasks; time entries and users are smaller and page111well at 50-100.112113## Incremental pulls with lastChangedDate114115`lastChangedDate` returns only records changed since a point in time. It116must be an ISO 8601 date-time with `Z` or a UTC offset, for example117`2026-10-01T00:00:00Z`. A zone-less value is rejected. Whether the bound118is inclusive has not been verified against a live tenant, so when exact119edges matter, step back a minute and de-duplicate on `id`.120121It filters on change time, not on business date. A time entry worked in122September but edited in October appears in an October pull. The period123start is not a completeness bound: a task due in the period may not have124changed for months, and a pre-booked time entry may predate its125`startTime`. When you need every record, pull without `lastChangedDate`126and filter on `startTime` (time entries) or `dueDate` (tasks) yourself.127Use an earlier `lastChangedDate` only when the tenant confirms nothing128older can fall in the period, and say which bound you used.129130## IDs and lookups131132Every ID is a GUID and is validated before any request is sent; a133non-GUID returns a validation error without calling Moovila.134135Nested references come back as `{ id, name }` objects, so most reports136need no second lookup: `organization`, `customer`, `ownerUser`, `stage`,137`status` on projects; `ownerUser`, `status`, `costCode`, `billingCode` on138tasks; `user`, `status`, `costCode`, `billingCode` on time entries. The139exception is `resourceTypeID` on users, tasks, time entries and budget140lines: resolve it against `moovila_labor_types_list`, which returns the141labor type's `name`, `defaultBillingRate`, `fullyBurdenedCost`, and the142`workTargetBillable` utilization target.143144## Fields that matter145146| Record | Key fields |147|--------|-----------|148| Project | `name`, `organization`, `customer`, `ownerUser`, `stage`, `status`, `isComplete`, `isInactive`, `isTemplate`, `isDeleted`, `startDate`, `dueDate`, `forecastDate`, `projectValue`, `revenueType`, `rpaxScore` |149| ProjectBudget | `projectID`, `category`, `costCode`, `budgetMethod`, `qty`, `unitCost`, `totalBudgetAmount`, `allocatedCost`, `unallocatedCost`, `percentageCommitted`, `resourceTypeID` |150| Task | `projectID`, `phaseID`, `name`, `status`, `priority`, `ownerUser`, `startDate`, `dueDate`, `completionDate`, `isMilestone`, `percentageComplete`, `workEstimate`, `totalBudget`, `totalActual`, `remainingBudget`, `predecessorsComplete`, `isDeleted` |151| TimeEntry | `projectID`, `taskID`, `user`, `status`, `startTime`, `endTime`, `totalHours`, `billableHours`, `billable`, `billRate`, `payRate`, `billingCode`, `costCode`, `timeEntryType` (1 = time entry, 2 = time adjustment), `notes` |152| User | `displayName`, `emailAddress`, `active`, `jobTitle`, `supervisor`, `resourceTypeID`, `hourlyCost` |153| Labor type | `name`, `category`, `isActive`, `defaultBillingRate`, `fullyBurdenedCost`, `workTargetBillable`, `workTargetTask`, `workTargetMeetings` |154155Status and stage names are tenant-configured. Read the `name` on the156object rather than assuming a fixed set of codes.157158Fields such as `prevailingWageID`, `excludePrevailingWage`,159`supervisorNotes`, `startDistanceToProject`, `endDistanceToProject` and160`totalBreakTime` are only populated for Moovila Smart Construction161tenants. Empty values on an MSP tenant are expected.162163## Errors164165| Status | Meaning | What to do |166|--------|---------|-----------|167| 400 | Bad request | Check the arguments, especially `lastChangedDate` format |168| 401 | Access token invalid or expired | Retry once; if it persists, reconnect Moovila in Conduit (token refresh has not yet been verified against a live tenant) |169| 403 | The consenting Moovila user cannot read this data | Widen that user's access in Moovila, or reconnect as a user who can see it |170| 404 | Resource not found | Re-list to confirm the ID; it may belong to a deleted record |171| 429 | Rate limited | If the error says "Retry after N s", wait that long; otherwise back off. Retry once |172| 5xx | Moovila server error | Retry later; do not loop |173174Moovila documents no rate limits. Keep cross-customer sweeps to one page at175a time and avoid fanning out `_get` calls per record when the list already176carries the fields you need.177178## Gotchas179180- **Templates and deleted records come back in lists.** Exclude projects181 with `isTemplate` or `isDeleted` true, and tasks with `isDeleted` true,182 before counting anything.183- **`organization` versus `customer` on projects.** Both are `{ id, name }`184 references. MSP tenants typically populate `organization` with the185 client; check which one a tenant uses on the first page before grouping186 by it.187- **Time adjustments are rows too.** `timeEntryType` 2 marks an188 adjustment, which can carry negative hours. Include adjustments in189 totals; do not treat them as duplicate entries.190- **`moovila_tasks_list_for_project` requires `projectID`.** For tasks191 across every project, use `moovila_tasks_list`.192193## Related Skills194195- [project-health](../project-health/SKILL.md) - Portfolio status, overdue tasks, and at-risk projects196- [project-profitability](../project-profitability/SKILL.md) - Budget versus actual by project and customer197- [time-reconciliation](../time-reconciliation/SKILL.md) - Billable time review and PSA reconciliation198- [resource-utilization](../resource-utilization/SKILL.md) - Per-technician utilization against labor type targets