node-autotask 0.64.1 → 0.66.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/MCP_TOOL_CATALOG.json +35 -15
  3. package/README.md +1 -1
  4. package/capabilities.json +174 -113
  5. package/dist/capabilities-data.js +173 -112
  6. package/dist/capabilities.cjs +4 -4
  7. package/dist/capabilities.js +1 -1
  8. package/dist/{chunk-NWQVMOP5.js → chunk-4HJVHVPE.js} +2 -2
  9. package/dist/{chunk-ENRW25IT.cjs → chunk-FLVMENXG.cjs} +3 -3
  10. package/dist/{chunk-BQNC4RYG.js → chunk-KO36QZXN.js} +418 -414
  11. package/dist/{chunk-C3OLJGY5.js → chunk-L5K2D2MZ.js} +3 -3
  12. package/dist/{chunk-MIKVE6VJ.cjs → chunk-QG3O5G4L.cjs} +175 -179
  13. package/dist/{chunk-SVCTQVTV.js → chunk-T5TI22K5.js} +4 -8
  14. package/dist/{chunk-AGGOZD2J.cjs → chunk-TIFJFCCN.cjs} +423 -419
  15. package/dist/{chunk-7DC524X3.cjs → chunk-XAJ7SBPE.cjs} +31 -31
  16. package/dist/{index-RkTNsoOz.d.ts → index-BZ11hF8H.d.ts} +10 -24
  17. package/dist/{index-B7bZQ34O.d.cts → index-DnisYPlj.d.cts} +10 -24
  18. package/dist/index.cjs +84 -84
  19. package/dist/index.d.cts +2 -2
  20. package/dist/index.d.ts +2 -2
  21. package/dist/index.js +5 -5
  22. package/dist/operations/index.cjs +50 -50
  23. package/dist/operations/index.d.cts +3 -3
  24. package/dist/operations/index.d.ts +3 -3
  25. package/dist/operations/index.js +2 -2
  26. package/dist/pool.cjs +8 -8
  27. package/dist/pool.js +4 -4
  28. package/dist/resources/index.cjs +27 -27
  29. package/dist/resources/index.d.cts +1 -1
  30. package/dist/resources/index.d.ts +1 -1
  31. package/dist/resources/index.js +3 -3
  32. package/docs/API.md +2 -2
  33. package/docs/VENDOR-QUIRKS.md +64 -37
  34. package/package.json +1 -1
package/capabilities.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
- "generatedAt": "2026-11-12T01:38:06.882Z",
2
+ "generatedAt": "2026-11-17T05:04:54.713Z",
3
3
  "groups": {
4
4
  "B": {
5
- "planHash": "c92aaa7dd21259e4e8b545e44cebf4d831e5f68a0c9e41e26af1c2966c84bdef",
6
- "builtAt": "2026-11-12T01:38:06.865Z",
5
+ "planHash": "94052c314d189d4b2fcf6bc842d983d4817c8410109074ed9505b682f4855790",
6
+ "builtAt": "2026-11-17T05:04:54.690Z",
7
7
  "records": [
8
8
  {
9
9
  "id": "appointments.count",
@@ -609,7 +609,7 @@
609
609
  },
610
610
  "metadata": {
611
611
  "purpose": "Update an appointment.",
612
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
612
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
613
613
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
614
614
  "related": [
615
615
  "appointments.get"
@@ -716,7 +716,7 @@
716
716
  },
717
717
  "metadata": {
718
718
  "purpose": "Count billing code records matching a JSON filter.",
719
- "usage": "Unwraps queryCount; returns a plain number. Zone quirk: the unfiltered count/query surface is blind — query with `useType` (1 = general, 3 = internal) + `isActive` filters. A raw caller must pass those filters (the allocation-code-aware createForResource node op was cut).",
719
+ "usage": "Unwraps queryCount; returns a plain number. Visibility caution: an unfiltered billing-code count/query may be inconclusive. Scope with `useType` (1 = general, 3 = internal) and `isActive`, then verify a known code by id.",
720
720
  "preferredWhen": null,
721
721
  "related": [
722
722
  "billing_codes.query"
@@ -726,7 +726,7 @@
726
726
  "surface": "billing_codes.count",
727
727
  "kind": "unfiltered-blind",
728
728
  "authority": "billing_codes.get",
729
- "note": "the UNFILTERED billing_codes count/query surface is blind in this zone. Query with `useType` (1 = general, 3 = internal) + `isActive` filters — filtered queries return real data; a raw caller must pass those filters (the allocation-code-aware createForResource node op was cut). get(id) is the authority."
729
+ "note": "The unfiltered billing_codes count result may be limited by API-user visibility. A zero or empty response is INCONCLUSIVE about tenant inventory or API capability. Narrow the query and verify a known record with billing_codes.get; if that read is not permitted, ask the user for the missing information. Scope allocation codes with useType and isActive."
730
730
  },
731
731
  "untrustedFields": [
732
732
  "description",
@@ -1040,7 +1040,7 @@
1040
1040
  },
1041
1041
  "metadata": {
1042
1042
  "purpose": "Query BillingCode records with a JSON filter.",
1043
- "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Zone quirk: the unfiltered count/query surface is blind — query with `useType` (1 = general, 3 = internal) + `isActive` filters. A raw caller must pass those filters (the allocation-code-aware createForResource node op was cut). Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
1043
+ "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Visibility caution: an unfiltered billing-code count/query may be inconclusive. Scope with `useType` (1 = general, 3 = internal) and `isActive`, then verify a known code by id. Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
1044
1044
  "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
1045
1045
  "related": [
1046
1046
  "billing_codes.resolve"
@@ -1050,7 +1050,7 @@
1050
1050
  "surface": "billing_codes.query",
1051
1051
  "kind": "unfiltered-blind",
1052
1052
  "authority": "billing_codes.get",
1053
- "note": "the UNFILTERED billing_codes count/query surface is blind in this zone. Query with `useType` (1 = general, 3 = internal) + `isActive` filters — filtered queries return real data; a raw caller must pass those filters (the allocation-code-aware createForResource node op was cut). get(id) is the authority."
1053
+ "note": "The unfiltered billing_codes query result may be limited by API-user visibility. A zero or empty response is INCONCLUSIVE about tenant inventory or API capability. Narrow the query and verify a known record with billing_codes.get; if that read is not permitted, ask the user for the missing information. Scope allocation codes with useType and isActive."
1054
1054
  },
1055
1055
  "untrustedFields": [
1056
1056
  "description",
@@ -1990,7 +1990,7 @@
1990
1990
  },
1991
1991
  "metadata": {
1992
1992
  "purpose": "Update a billing item.",
1993
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
1993
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
1994
1994
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
1995
1995
  "related": [
1996
1996
  "billing_items.get"
@@ -3203,7 +3203,7 @@
3203
3203
  },
3204
3204
  "metadata": {
3205
3205
  "purpose": "Update a ChecklistLibrary (reusable checklist definition; container of library steps). Not a Task and not a per-ticket instance.",
3206
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
3206
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
3207
3207
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
3208
3208
  "related": [
3209
3209
  "checklist_libraries.get"
@@ -4992,7 +4992,7 @@
4992
4992
  },
4993
4993
  "metadata": {
4994
4994
  "purpose": "Update a configuration item category.",
4995
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
4995
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
4996
4996
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
4997
4997
  "related": [
4998
4998
  "configuration_item_categories.get"
@@ -6272,7 +6272,7 @@
6272
6272
  },
6273
6273
  "metadata": {
6274
6274
  "purpose": "Update a configuration item type.",
6275
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
6275
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
6276
6276
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
6277
6277
  "related": [
6278
6278
  "configuration_item_types.get"
@@ -7473,7 +7473,7 @@
7473
7473
  },
7474
7474
  "metadata": {
7475
7475
  "purpose": "Update a contact group.",
7476
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
7476
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
7477
7477
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
7478
7478
  "related": [
7479
7479
  "contact_groups.get"
@@ -9240,7 +9240,7 @@
9240
9240
  },
9241
9241
  "metadata": {
9242
9242
  "purpose": "Update a contract exclusion set.",
9243
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
9243
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
9244
9244
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
9245
9245
  "related": [
9246
9246
  "contract_exclusion_sets.get"
@@ -9821,7 +9821,7 @@
9821
9821
  },
9822
9822
  "metadata": {
9823
9823
  "purpose": "Update a country.",
9824
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
9824
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
9825
9825
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
9826
9826
  "related": [
9827
9827
  "countries.get"
@@ -10356,6 +10356,67 @@
10356
10356
  "compact": "CurrencySummary",
10357
10357
  "status": "tested"
10358
10358
  },
10359
+ {
10360
+ "id": "currencies.update",
10361
+ "resource": "currencies",
10362
+ "udfCapable": false,
10363
+ "operation": "update",
10364
+ "kind": "primitive",
10365
+ "endpoint": "PUT|PATCH /V1.0/Currencies",
10366
+ "effect": "write",
10367
+ "flags": [
10368
+ "idempotent"
10369
+ ],
10370
+ "dryRun": true,
10371
+ "envelope": "OperationResultModel",
10372
+ "inputSchema": {
10373
+ "id": {
10374
+ "type": "string | number",
10375
+ "required": true,
10376
+ "description": "The record id (number, or a canonical integer string — ids beyond 2^53 are supported via the string form)."
10377
+ },
10378
+ "data": {
10379
+ "type": "object",
10380
+ "required": true,
10381
+ "description": "The record payload (vendor model fields)."
10382
+ }
10383
+ },
10384
+ "inputSchemaStrict": true,
10385
+ "outputSchema": {
10386
+ "type": "OperationResultModel",
10387
+ "drops": []
10388
+ },
10389
+ "examples": [
10390
+ "await client.currencies.update('example-value', { name: 'example' }, { dryRun: true })"
10391
+ ],
10392
+ "permissions": "unknown",
10393
+ "pagination": {
10394
+ "mode": "none"
10395
+ },
10396
+ "resolution": null,
10397
+ "retry": {
10398
+ "preset": "retry-1849870d"
10399
+ },
10400
+ "errors": {
10401
+ "set": 1
10402
+ },
10403
+ "metadata": {
10404
+ "purpose": "Update a currency, including its exchange rate and display settings.",
10405
+ "usage": "Updates via the documented collection PUT route after merging supplied fields into a fresh record. The vendored specification also lists PATCH; this method sends PUT. No stale-check field is configured for this operation. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
10406
+ "preferredWhen": "Change supported fields on an existing currency; the vendor specification does not define currency create or delete operations.",
10407
+ "related": [
10408
+ "currencies.get"
10409
+ ],
10410
+ "collectionUpdate": true,
10411
+ "untrustedFields": [
10412
+ "description",
10413
+ "name"
10414
+ ],
10415
+ "accountWide": true
10416
+ },
10417
+ "compact": null,
10418
+ "status": "tested"
10419
+ },
10359
10420
  {
10360
10421
  "id": "departments.count",
10361
10422
  "resource": "departments",
@@ -10980,7 +11041,7 @@
10980
11041
  },
10981
11042
  "metadata": {
10982
11043
  "purpose": "Update a department.",
10983
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
11044
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
10984
11045
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
10985
11046
  "related": [
10986
11047
  "departments.get"
@@ -11610,7 +11671,7 @@
11610
11671
  },
11611
11672
  "metadata": {
11612
11673
  "purpose": "Update a domain registrar.",
11613
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
11674
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
11614
11675
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
11615
11676
  "related": [
11616
11677
  "domain_registrars.get"
@@ -13863,7 +13924,7 @@
13863
13924
  },
13864
13925
  "metadata": {
13865
13926
  "purpose": "Update an expense report.",
13866
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
13927
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
13867
13928
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
13868
13929
  "related": [
13869
13930
  "expense_reports.get"
@@ -14503,7 +14564,7 @@
14503
14564
  },
14504
14565
  "metadata": {
14505
14566
  "purpose": "Update a holiday set.",
14506
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
14567
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
14507
14568
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
14508
14569
  "related": [
14509
14570
  "holiday_sets.get"
@@ -15251,7 +15312,7 @@
15251
15312
  },
15252
15313
  "metadata": {
15253
15314
  "purpose": "Create an inventory product.",
15254
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. (the productID reference table is blind (0 rows) for this API user — no valid productID can be read back via the API; provision the referenced record in the Autotask UI first, then retry with the real id.)",
15315
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Use a known valid productID or query products for a readable product. If the API user cannot read the required product, ask an operator for its id or permission to access it before retrying.",
15255
15316
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
15256
15317
  "related": [
15257
15318
  "inventory_products.update"
@@ -15916,7 +15977,7 @@
15916
15977
  },
15917
15978
  "metadata": {
15918
15979
  "purpose": "Update an inventory product.",
15919
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
15980
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
15920
15981
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
15921
15982
  "related": [
15922
15983
  "inventory_products.get"
@@ -17396,7 +17457,7 @@
17396
17457
  },
17397
17458
  "metadata": {
17398
17459
  "purpose": "Update an opportunity category.",
17399
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
17460
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
17400
17461
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
17401
17462
  "related": [
17402
17463
  "opportunity_categories.get"
@@ -17869,7 +17930,7 @@
17869
17930
  },
17870
17931
  "metadata": {
17871
17932
  "purpose": "Update an organizational level association.",
17872
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
17933
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
17873
17934
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
17874
17935
  "related": [
17875
17936
  "organizational_level_associations.get"
@@ -18365,7 +18426,7 @@
18365
18426
  },
18366
18427
  "metadata": {
18367
18428
  "purpose": "Update an organizational level 1.",
18368
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
18429
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
18369
18430
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
18370
18431
  "related": [
18371
18432
  "organizational_level1s.get"
@@ -18865,7 +18926,7 @@
18865
18926
  },
18866
18927
  "metadata": {
18867
18928
  "purpose": "Update an organizational level 2.",
18868
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
18929
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
18869
18930
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
18870
18931
  "related": [
18871
18932
  "organizational_level2s.get"
@@ -20258,7 +20319,7 @@
20258
20319
  },
20259
20320
  "metadata": {
20260
20321
  "purpose": "Update a product.",
20261
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
20322
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
20262
20323
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
20263
20324
  "related": [
20264
20325
  "products.get"
@@ -20793,7 +20854,7 @@
20793
20854
  },
20794
20855
  "metadata": {
20795
20856
  "purpose": "Update a purchase approval.",
20796
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
20857
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
20797
20858
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
20798
20859
  "related": [
20799
20860
  "purchase_approvals.get"
@@ -22436,7 +22497,7 @@
22436
22497
  },
22437
22498
  "metadata": {
22438
22499
  "purpose": "Update a purchase order.",
22439
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
22500
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
22440
22501
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
22441
22502
  "related": [
22442
22503
  "purchase_orders.get"
@@ -26222,7 +26283,7 @@
26222
26283
  },
26223
26284
  "metadata": {
26224
26285
  "purpose": "Update a resource.",
26225
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
26286
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
26226
26287
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
26227
26288
  "related": [
26228
26289
  "resources.get"
@@ -27056,7 +27117,7 @@
27056
27117
  },
27057
27118
  "metadata": {
27058
27119
  "purpose": "Update a role.",
27059
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
27120
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
27060
27121
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
27061
27122
  "related": [
27062
27123
  "roles.get"
@@ -27644,7 +27705,7 @@
27644
27705
  },
27645
27706
  "metadata": {
27646
27707
  "purpose": "Update a sales order.",
27647
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
27708
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
27648
27709
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
27649
27710
  "related": [
27650
27711
  "sales_orders.get"
@@ -30546,7 +30607,7 @@
30546
30607
  },
30547
30608
  "metadata": {
30548
30609
  "purpose": "Update a service call.",
30549
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
30610
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
30550
30611
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
30551
30612
  "related": [
30552
30613
  "service_calls.get"
@@ -31825,7 +31886,7 @@
31825
31886
  },
31826
31887
  "metadata": {
31827
31888
  "purpose": "Update a service.",
31828
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
31889
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
31829
31890
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
31830
31891
  "related": [
31831
31892
  "services.get"
@@ -34919,7 +34980,7 @@
34919
34980
  },
34920
34981
  "metadata": {
34921
34982
  "purpose": "Update a tag group.",
34922
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
34983
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
34923
34984
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
34924
34985
  "related": [
34925
34986
  "tag_groups.get"
@@ -35530,7 +35591,7 @@
35530
35591
  },
35531
35592
  "metadata": {
35532
35593
  "purpose": "Update a tag.",
35533
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
35594
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
35534
35595
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
35535
35596
  "related": [
35536
35597
  "tags.get"
@@ -36023,7 +36084,7 @@
36023
36084
  },
36024
36085
  "metadata": {
36025
36086
  "purpose": "Update a tax region.",
36026
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
36087
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
36027
36088
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
36028
36089
  "related": [
36029
36090
  "tax_regions.get"
@@ -36643,7 +36704,7 @@
36643
36704
  },
36644
36705
  "metadata": {
36645
36706
  "purpose": "Update a ticket category.",
36646
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
36707
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
36647
36708
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
36648
36709
  "related": [
36649
36710
  "ticket_categories.get"
@@ -38876,7 +38937,7 @@
38876
38937
  },
38877
38938
  "metadata": {
38878
38939
  "purpose": "Update a ticket note webhook.",
38879
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
38940
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
38880
38941
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
38881
38942
  "related": [
38882
38943
  "ticket_note_webhooks.get"
@@ -39026,7 +39087,7 @@
39026
39087
  },
39027
39088
  "examples": [
39028
39089
  "await client.timeEntries.create({ resourceID: 2001, dateWorked: '2026-10-03' }, { dryRun: true })",
39029
- "this zone: the low-level escape hatch — posts exactly the given body (resourceID is the only vendor-required field) and lets the vendor linkage/allocation-code gates surface verbatim Resolve the allocation code yourself (billing_codes query with the family + active filter — the unfiltered surface is blind in this zone) or pass a linkage pin (ticketID/taskID/roleID)."
39090
+ "the low-level escape hatch — posts exactly the given body (resourceID is the only vendor-required field) and lets the vendor linkage/allocation-code gates surface verbatim Resolve the allocation code yourself (billing_codes query with the family + active filter — the unfiltered surface is blind) or pass a linkage pin (ticketID/taskID/roleID)."
39030
39091
  ],
39031
39092
  "permissions": "unknown",
39032
39093
  "pagination": {
@@ -39041,7 +39102,7 @@
39041
39102
  },
39042
39103
  "metadata": {
39043
39104
  "purpose": "Create a time entry.",
39044
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed.",
39105
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. On internal-organisation tickets (companyID 0) showOnInvoice must be false — true is refused by the vendor (500 \"This time entry cannot be shown on an Invoice because it is for your internal organization.\"); the vendor stores isNonBillable true on internal-organisation entries (a create that sent false read back true)",
39045
39106
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
39046
39107
  "related": [
39047
39108
  "time_entries.update"
@@ -39194,12 +39255,12 @@
39194
39255
  "set": 8
39195
39256
  },
39196
39257
  "metadata": {
39197
- "purpose": "The ONE posted-state read: a bounded read over the inclusive dateWorked window [from, to] (UTC 'YYYY-MM-DD' days) with the posted/unposted split derived from the billing_items.timeEntryID join — never a postedDate read (this zone's TimeEntry entity has no postedDate; postedDate exist|notExist 500s). Approval is NOT consulted (this zone never populates billingApprovalDateTime yet bills those entries). The no-window form is gone: read with no dateWorked filter goes through time_entries.query.",
39258
+ "purpose": "The ONE posted-state read: a bounded read over the inclusive dateWorked window [from, to] (UTC 'YYYY-MM-DD' days) with the posted/unposted split derived from the billing_items.timeEntryID join — never a postedDate read (the TimeEntry entity has no postedDate; postedDate exist|notExist 500s). Approval is NOT consulted (the vendor never populates billingApprovalDateTime yet bills those entries). The no-window form is gone: read with no dateWorked filter goes through time_entries.query.",
39198
39259
  "usage": "dateWorkedWindow(from, to, opts?): from/to are required inclusive 'YYYY-MM-DD' UTC days (impossible calendar days like 2026-02-31 and from-after-to are refused pre-request, zero wire). opts.state: 'posted' | 'unposted' — client-side narrowing AFTER the join (replaces the old posted boolean and the getPosted/getUnposted state modes); omitted = both. opts.limit 1-500 (default 500 = the hard cap); opts.ticketID / opts.resourceID eq narrowings sent server-side. Returns { items, postedCount, unpostedCount, window { from, to } (wire bounds, second precision), nextCursor, unconfirmed, truncated }: postedCount/unpostedCount split EVERY entry read (before state narrowing) while items is narrowed, so counts cover the returned rows ONLY (at most limit); truncated is true when the entry read has a live next-page cursor or a join page was truncated; unconfirmed entries sit in neither count nor items. Paging: opts.cursor (a previous nextCursor; a cursor whose path is not the TimeEntries continuation is refused RESPONSE_REJECTED; over 2048 chars refused). opts.countOnly: true (with opts.maxVendorCalls integer 1-200, default 30) returns the whole-window totals { window, total, postedCount, unpostedCount, vendorCalls, estimate, budget } instead of rows: one count call sizes the window, every entry page is read ids-only and joined at 250 ids per join, then the window is counted again — over budget BUDGET_EXCEEDED (the estimate named), a truncated join RESOLUTION_TRUNCATED, a distinct-id total equal to neither count INVALID_RESPONSE; no short total is ever returned. 429 and vendor faults propagate typed. Wire: one bounded POST /V1.0/TimeEntries/query (MaxRecords, dateWorked gte/lte + the eq narrowings) plus at most 2 BillingItems join queries (250 ids each). For a window with more rows than the cap, page with cursor or reconcile through time_entries.query with the same dateWorked filter (its 2500-row walk cap).",
39199
39260
  "preferredWhen": null,
39200
39261
  "related": [],
39201
39262
  "passBackCursor": "nextCursor",
39202
- "pointerNote": "this zone's TimeEntry entity exposes NO posted-state field — reads carry no postedDate/postedOnTime and a postedDate exist/notExist filter fails with SERVER_ERROR \"Unable to find postedDate in the TimeEntry Entity\". time_entries.dateWorkedWindow (the one posted-state read — the getPosted/getUnposted/postedWithin pair consolidated into it) therefore sends no postedDate condition at all: the posted/unposted split is derived from billing_items.timeEntryID (an entry is posted when a billing item references it, whether or not billingApprovalDateTime is set — this zone never populates it). If a call still fails, the fault is NOT the old postedDate wall: it is a billing_items join/read fault (typed error — 429 RATE_LIMITED included — propagates, no partial result).",
39263
+ "pointerNote": "time_entries.dateWorkedWindow derives posted state from a billing_items.timeEntryID join instead of filtering on a postedDate field. A matching billing item establishes posted state; the helper does not depend on billingApprovalDateTime. A billing-items read or join fault propagates as a typed error, without returning a partial posted-state result.",
39203
39264
  "untrustedFields": [
39204
39265
  "UDF1",
39205
39266
  "UDF10",
@@ -40198,7 +40259,7 @@
40198
40259
  },
40199
40260
  "metadata": {
40200
40261
  "purpose": "Update a time entry.",
40201
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. ticketID does NOT persist on update: the vendor returns success but keeps the old ticketID (probed live on this zone). To re-parent use time_entries.moveToTicket (create, verify, delete). The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
40262
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. ticketID does NOT persist on update: the vendor returns success but keeps the old ticketID (probed live, 2026-10-21). To re-parent use time_entries.moveToTicket (create, verify, delete). The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
40202
40263
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change. Not for ticketID: the vendor ignores it on update; use time_entries.moveToTicket.",
40203
40264
  "related": [
40204
40265
  "time_entries.get"
@@ -41620,7 +41681,7 @@
41620
41681
  "surface": "user_defined_field_definitions.count",
41621
41682
  "kind": "unfiltered-blind",
41622
41683
  "authority": "user_defined_field_definitions.get",
41623
- "note": "the UNFILTERED user_defined_field_definitions count is blind in this zone: the unfiltered count answers 0 while a filtered count (a single `id gt 0` condition) returns the real total. The unfiltered query is NOT blind (it returns real rows), and a FILTERED count of 0 is a TRUE absence, never a sentinel. An unfiltered count of 0 proves nothing — count with a filter (e.g. `id gt 0`) or page the query; get(id) is the authority for a specific record."
41684
+ "note": "The unfiltered user_defined_field_definitions count can return zero despite existing records. Re-check with an id gt 0 filter or page user_defined_field_definitions.query; the query is not classified blind by this count-only warning. A zero unfiltered count does not prove absence; verify a known record with user_defined_field_definitions.get if permitted."
41624
41685
  },
41625
41686
  "untrustedFields": [
41626
41687
  "description",
@@ -42057,7 +42118,7 @@
42057
42118
  },
42058
42119
  "metadata": {
42059
42120
  "purpose": "Update a UDF definition.",
42060
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. Vendor constraints: `dataType` and `udfType` cannot be changed; `isFieldMapping` is immutable (a mapped field only accepts `isActive`/`sortOrder` updates); a `List` UDF's `defaultValue` is a list item's `valueForDisplay` (set it only after the items exist). The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
42121
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. Vendor constraints: `dataType` and `udfType` cannot be changed; `isFieldMapping` is immutable (a mapped field only accepts `isActive`/`sortOrder` updates); a `List` UDF's `defaultValue` is a list item's `valueForDisplay` (set it only after the items exist). The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
42061
42122
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
42062
42123
  "related": [
42063
42124
  "user_defined_field_definitions.get"
@@ -42134,7 +42195,7 @@
42134
42195
  "surface": "user_defined_field_list_items.count",
42135
42196
  "kind": "unfiltered-blind",
42136
42197
  "authority": "user_defined_field_list_items.get",
42137
- "note": "the UNFILTERED user_defined_field_list_items count is blind in this zone: the unfiltered count answers 0 while a filtered count (a single `id gt 0` condition) returns the real total. The unfiltered query is NOT blind (it returns real rows), and a FILTERED count of 0 is a TRUE absence, never a sentinel. An unfiltered count of 0 proves nothing — count with a filter (e.g. `id gt 0`) or page the query; get(id) is the authority for a specific record."
42198
+ "note": "The unfiltered user_defined_field_list_items count can return zero despite existing records. Re-check with an id gt 0 filter or page user_defined_field_list_items.query; the query is not classified blind by this count-only warning. A zero unfiltered count does not prove absence; verify a known record with user_defined_field_list_items.get if permitted."
42138
42199
  },
42139
42200
  "untrustedFields": [
42140
42201
  "valueForDisplay",
@@ -42725,8 +42786,8 @@
42725
42786
  ]
42726
42787
  },
42727
42788
  "A": {
42728
- "planHash": "c92aaa7dd21259e4e8b545e44cebf4d831e5f68a0c9e41e26af1c2966c84bdef",
42729
- "builtAt": "2026-11-12T01:38:06.866Z",
42789
+ "planHash": "94052c314d189d4b2fcf6bc842d983d4817c8410109074ed9505b682f4855790",
42790
+ "builtAt": "2026-11-17T05:04:54.690Z",
42730
42791
  "records": [
42731
42792
  {
42732
42793
  "id": "companies.count",
@@ -42779,7 +42840,7 @@
42779
42840
  },
42780
42841
  "metadata": {
42781
42842
  "purpose": "Count company records matching a JSON filter.",
42782
- "usage": "Unwraps queryCount; returns a plain number. Zone quirk: count/query return 0/empty for companies not owned by the caller — verify presence with get(id), not count.",
42843
+ "usage": "Unwraps queryCount; returns a plain number. Visibility caution: company count/query may omit records the API user cannot list; an empty result is inconclusive about tenant inventory. Verify a known record with get(id).",
42783
42844
  "preferredWhen": null,
42784
42845
  "related": [
42785
42846
  "companies.query"
@@ -42789,7 +42850,7 @@
42789
42850
  "surface": "companies.count",
42790
42851
  "kind": "unowned-blind",
42791
42852
  "authority": "companies.get",
42792
- "note": "companies count/query return 0/empty for companies not owned by the caller (verified: 0 before AND after a proven live create). A 0/empty result on this surface proves nothing — get(id) is the authority: it returns the record even while count/query are blind."
42853
+ "note": "The companies count result may be limited by API-user visibility. A zero or empty response is INCONCLUSIVE about tenant inventory or API capability. Narrow the query and verify a known record with companies.get; if that read is not permitted, ask the user for the missing information."
42793
42854
  },
42794
42855
  "untrustedFields": [
42795
42856
  "UDF1",
@@ -42846,7 +42907,7 @@
42846
42907
  },
42847
42908
  "examples": [
42848
42909
  "await client.companies.create({ companyName: 'Example', companyType: 1, phone: '1300555001', isActive: true, ownerResourceID: 2001 }, { dryRun: true })",
42849
- "this zone validated: created a company with this body (required: companyName, companyType, phone, ownerResourceID — a non-API-only resource). CompanyModel has NO description field (the vendor silently 200s unknown fields); the create auto-creates a vendor \"Primary Address\" location (UI-only cleanup)."
42910
+ "validated: created a company with this body (required: companyName, companyType, phone, ownerResourceID — a non-API-only resource). CompanyModel has NO description field (the vendor silently 200s unknown fields); the create auto-creates a vendor \"Primary Address\" location (UI-only cleanup)."
42850
42911
  ],
42851
42912
  "permissions": "unknown",
42852
42913
  "pagination": {
@@ -42991,7 +43052,7 @@
42991
43052
  },
42992
43053
  "examples": [
42993
43054
  "await client.companies.fullProfile(1001)",
42994
- "this zone validated: a run served 1001 in exactly 6 wire (1 location; openTickets: 3 — data). args: (company id, optional { contactLimit, noteLimit, ticketLimit, projectLimit — default 50 }). openTickets part: open = status NOT in the tenant-resolved closed set (`tickets.statusSemantics`; ids {5} with source 'picklist' on this zone today, 'assumed' + a disclosing note when the catalog is unreadable); the part's query is always filtered and the tickets surface is blind UNFILTERED (verified: the filtered query returns data), so an empty answer is a TRUE zero — the typed blind part (blind: true + the blindSurface sentinel) only for a blind class that covers this filtered call. Company missing → NOT_FOUND."
43055
+ "Use a known company id. The openTickets query excludes the tenant-resolved closed statuses and discloses any fallback assumption in closedStatus. Empty lists do not establish tenant-wide absence; conservative visibility warnings depend on the applicable filter-aware predicate. A missing company returns NOT_FOUND."
42995
43056
  ],
42996
43057
  "permissions": "unknown",
42997
43058
  "pagination": {
@@ -43006,7 +43067,7 @@
43006
43067
  },
43007
43068
  "metadata": {
43008
43069
  "purpose": "Get everything the node knows about one company in a single call: the company record, its locations, contacts and notes, its open tickets, and its projects — every part separately reported with caps.",
43009
- "usage": "args[0] is the company id (number); args[1] (optional) is the options object { contactLimit?: number (default 50), noteLimit?: number (default 50), ticketLimit?: number (default 50), projectLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name/label siblings — the company row (owner / created-by resource names), the openTickets rows (the same closed-scope ticket-field siblings as tickets.fullContext, incl. the ticket picklist labels), the projects rows (lead / creator resource names + the contract name — project picklists stay OUT of the closed label scope) — + the top-level `names` section; the siblings ride the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads: cache hits are free of the budget, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: exactly 6 reads (companies.get + 5 companyID-filtered queries). With names: true, N added name reads (N = the distinct uncached ids, capped by maxNameReads) + at most ONE fieldCatalog labels read (zero wire on a warm fieldCache). The openTickets part: open = status NOT in the resolved closed set — the closed ids come from the tenant's Tickets status picklist via `tickets.statusSemantics` (one cache-aware field-metadata read, zero wire on a warm cache), falling back to id 5 with `source: 'assumed'` and a part `note` that discloses it; the part carries `closedStatus { closedIds, source, note }` and the always-filtered query applies the resolved leaf (a single `not-eq` for one closed id, `notIn` for several); the tickets count/query surface is blind UNFILTERED on this zone (verified: the FILTERED query returns data), so this always-filtered part degrades to `blind: true` + the typed `blindSurface` sentinel ONLY when the filter-aware `blindStampFor` predicate stamps this call (post-merge P1) — a filtered empty answer is a TRUE zero (the company has no open tickets), and a non-empty answer is data; the flag clears either way. Company missing → NOT_FOUND.",
43070
+ "usage": "args[0] is the company id (number); args[1] (optional) is the options object { contactLimit?: number (default 50), noteLimit?: number (default 50), ticketLimit?: number (default 50), projectLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name/label siblings — the company row (owner / created-by resource names), the openTickets rows (the same closed-scope ticket-field siblings as tickets.fullContext, incl. the ticket picklist labels), the projects rows (lead / creator resource names + the contract name — project picklists stay OUT of the closed label scope) — + the top-level `names` section; the siblings ride the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads: cache hits are free of the budget, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: exactly 6 reads (companies.get + 5 companyID-filtered queries). With names: true, N added name reads (N = the distinct uncached ids, capped by maxNameReads) + at most ONE fieldCatalog labels read (zero wire on a warm fieldCache). The openTickets part: open = status NOT in the resolved closed set — the closed ids come from the tenant's Tickets status picklist via `tickets.statusSemantics` (one cache-aware field-metadata read, zero wire on a warm cache), falling back to id 5 with `source: 'assumed'` and a part `note` that discloses it; the part carries `closedStatus { closedIds, source, note }` and the always-filtered query applies the resolved leaf (a single `not-eq` for one closed id, `notIn` for several); an empty scoped query shows no records returned to this API user, not proven tenant-wide absence. A conservative visibility warning is attached only when its filter-aware predicate covers the call; non-empty rows are returned as data. A missing company returns NOT_FOUND.",
43010
43071
  "preferredWhen": "The single read for 'what do you know about this company' — replaces 6 raw reads + describes with one call. companies.get alone is just the record.",
43011
43072
  "related": [
43012
43073
  "companies.get",
@@ -43016,7 +43077,7 @@
43016
43077
  "tickets.query",
43017
43078
  "projects.query"
43018
43079
  ],
43019
- "args": "args[0] is the company id (number); args[1] (optional) is the options object { contactLimit?: number, noteLimit?: number, ticketLimit?: number, projectLimit?: number } (all default 50), names?: boolean (default false — the opt-in name/label siblings + the `names` section), maxNameReads?: number (default 20, lowerable never raised — the budget of cold wire name reads). 6 bounded reads inside, zero mutating; the openTickets part degrades to a typed blind part (blind: true + blindSurface sentinel) on the blind tickets surface instead of a misleading empty list.",
43080
+ "args": "args[0] is the company id (number); args[1] (optional) is the options object { contactLimit?: number, noteLimit?: number, ticketLimit?: number, projectLimit?: number } (all default 50), names?: boolean (default false — the opt-in name/label siblings + the `names` section), maxNameReads?: number (default 20, lowerable never raised — the budget of cold wire name reads). Bounded reads only, with no mutations. Empty lists reflect the current API-user query result; verify a known id before inferring tenant-wide absence.",
43020
43081
  "untrustedFields": [
43021
43082
  "UDF1",
43022
43083
  "UDF10",
@@ -43622,7 +43683,7 @@
43622
43683
  },
43623
43684
  "metadata": {
43624
43685
  "purpose": "Query Company records with a JSON filter.",
43625
- "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Zone quirk: count/query return 0/empty for companies not owned by the caller — verify presence with get(id), not count. Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
43686
+ "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Visibility caution: company count/query may omit records the API user cannot list; an empty result is inconclusive about tenant inventory. Verify a known record with get(id). Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
43626
43687
  "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
43627
43688
  "related": [
43628
43689
  "companies.resolve"
@@ -43632,7 +43693,7 @@
43632
43693
  "surface": "companies.query",
43633
43694
  "kind": "unowned-blind",
43634
43695
  "authority": "companies.get",
43635
- "note": "companies count/query return 0/empty for companies not owned by the caller (verified: 0 before AND after a proven live create). A 0/empty result on this surface proves nothing — get(id) is the authority: it returns the record even while count/query are blind."
43696
+ "note": "The companies query result may be limited by API-user visibility. A zero or empty response is INCONCLUSIVE about tenant inventory or API capability. Narrow the query and verify a known record with companies.get; if that read is not permitted, ask the user for the missing information."
43636
43697
  },
43637
43698
  "untrustedFields": [
43638
43699
  "UDF1",
@@ -44121,7 +44182,7 @@
44121
44182
  },
44122
44183
  "examples": [
44123
44184
  "await client.companies.unbilledWork(1001, { source: 'posted_uninvoiced', includeParent: true, limit: 50 })",
44124
- "Synthetic shape (no tenant data): args (company id, optional UnbilledWorkOptions). 6(+1) bounded reads, zero mutating — the join rides the company's tickets AND the company's projects' tasks (the vendored time_entries model carries no company field); the billing part rides the billing_join column list; the unposted anti-join + totals + warnings are client-side (zero wire); a filtered empty part is a TRUE zero (the pinned blind surfaces stamp only their blind shape); company missing → NOT_FOUND."
44185
+ "Synthetic shape (no tenant data): args (company id, optional UnbilledWorkOptions). 6(+1) bounded reads, zero mutating — the join rides the company's tickets AND the company's projects' tasks (the vendored time_entries model carries no company field); the billing part rides the billing_join column list; the unposted anti-join + totals + warnings are client-side (zero wire); a filtered empty part reports no rows returned under current API-user visibility, without establishing tenant-wide absence; company missing → NOT_FOUND."
44125
44186
  ],
44126
44187
  "permissions": "unknown",
44127
44188
  "pagination": {
@@ -44136,7 +44197,7 @@
44136
44197
  },
44137
44198
  "metadata": {
44138
44199
  "purpose": "One call for a company's unbilled work: its posted billing items (per source), the time behind them (joined through the company's tickets and tasks — time entries carry no companyID), the per-ticket rollup, the unposted anti-join section, ex-tax totals + hours, and the billing-vs-time warnings",
44139
- "usage": "args[0] is the company id (number); args[1] (optional) is UnbilledWorkOptions { source?: 'posted_uninvoiced' (default — the billing items with no invoiceID (notExist), the uninvoiced mark) | 'invoice' (invoiceID = invoiceId; the invoice record itself is NOT fetched in v1 — the items already carry invoiceID/itemDate/amounts) | 'date_range' (itemDate window — dateFrom + dateTo REQUIRED) | 'tickets' (ticketID in ticketIds; the time-entries part additionally joins those tickets directly), includeParent?: boolean (default true — ONE level only, via company.parentCompanyID; dangling → parent: null, parent parts empty, NOT an error), dateFrom?/dateTo?: string (YYYY-MM-DD — the itemDate window on the billing part in EVERY source, the dateWorked window on the time part; required for date_range), invoiceId?: number | string (required shape for invoice), ticketIds?: (number | string)[] (required non-empty for tickets), includeNotes?: boolean (default false — the note fields EXCLUDED; when true the time part requests summaryNotes and the billing part description, each capped at noteChars with the marker BEFORE the server-side untrusted wrapper), noteChars?: number (default 400, integer >= 1), rollup?: 'ticket' (default — per-ticket rows; the unassigned bucket carries ticketId null) | 'entry' (the capped per-entry list), limit?: number (default 50, clamped 1..500 — the per-part record cap) }. Wire: exactly 6 bounded reads without a parent (company get + tickets + projects + tasks + billing + time queries), 7 with a parent present — zero mutating; includeNotes/noteChars/rollup add ZERO wire (response-side). The join: the company's ticket ids (tickets query, companyID in) + the company's task ids (projects query, companyID in → tasks query, projectID in); the time query is or [taskID in, ticketID in] (the join sets are capped at 300 ids per list — the 8000-char filter cap — with a documented note when truncated); an EMPTY join set skips the time part with status 'skipped' + the honest note (no tasks/tickets to join against is NOT evidence of no time entries). Per part: the capped/hasMore flags + the status 'ok' | 'blind' | 'skipped' (the blind stamp is the filter-aware predicate — a FILTERED empty part is a TRUE zero with the status note, never a sentinel; the pinned this zone unfiltered-blind tickets surface is always queried filtered here). The billing part rides the billing_join column list as its IncludeFields (the join's columns, + id; + description with includeNotes). The client-side folds (zero wire): rollup (billing items by ticketID; time entries by their own ticketID — the vendored TaskModel carries no ticket field, so the entry's own ticketID is the only resolvable ticket link; null → the unassigned bucket), unposted (the fetched entries whose id is in no fetched billing item's timeEntryID), totals { preTax = Σ extendedPrice, hours = Σ hoursWorked, entryCount, totalAmount, taxDollars — surfaced for reconciliation } derived from the SAME folded rows (one source of truth), warnings { noTimeEntry (the billing items whose timeEntryID is empty/0 — capped list + count), hourDelta (the billing items WITH a resolvable time entry where |billed quantity − hoursWorked| > 0 — strict; capped list + count) }. Company missing → NOT_FOUND (zero further wire). Closed opts bag: an unknown key → typed CONFIG_ERROR naming the key + the valid keys (one-round complete problem list, pre-request, zero wire).",
44200
+ "usage": "args[0] is the company id (number); args[1] (optional) is UnbilledWorkOptions { source?: 'posted_uninvoiced' (default — the billing items with no invoiceID (notExist), the uninvoiced mark) | 'invoice' (invoiceID = invoiceId; the invoice record itself is NOT fetched in v1 — the items already carry invoiceID/itemDate/amounts) | 'date_range' (itemDate window — dateFrom + dateTo REQUIRED) | 'tickets' (ticketID in ticketIds; the time-entries part additionally joins those tickets directly), includeParent?: boolean (default true — ONE level only, via company.parentCompanyID; dangling → parent: null, parent parts empty, NOT an error), dateFrom?/dateTo?: string (YYYY-MM-DD — the itemDate window on the billing part in EVERY source, the dateWorked window on the time part; required for date_range), invoiceId?: number | string (required shape for invoice), ticketIds?: (number | string)[] (required non-empty for tickets), includeNotes?: boolean (default false — the note fields EXCLUDED; when true the time part requests summaryNotes and the billing part description, each capped at noteChars with the marker BEFORE the server-side untrusted wrapper), noteChars?: number (default 400, integer >= 1), rollup?: 'ticket' (default — per-ticket rows; the unassigned bucket carries ticketId null) | 'entry' (the capped per-entry list), limit?: number (default 50, clamped 1..500 — the per-part record cap) }. Wire: exactly 6 bounded reads without a parent (company get + tickets + projects + tasks + billing + time queries), 7 with a parent present — zero mutating; includeNotes/noteChars/rollup add ZERO wire (response-side). The join: the company's ticket ids (tickets query, companyID in) + the company's task ids (projects query, companyID in → tasks query, projectID in); the time query is or [taskID in, ticketID in] (the join sets are capped at 300 ids per list — the 8000-char filter cap — with a documented note when truncated); an EMPTY join set skips the time part with status 'skipped' + the honest note (no tasks/tickets to join against is NOT evidence of no time entries). Per part: the capped/hasMore flags + the status 'ok' | 'blind' | 'skipped' (the blind stamp is the filter-aware predicate — a filtered empty part reports no rows returned under current API-user visibility, without establishing tenant-wide absence; unfiltered-blind surfaces do not stamp filtered calls). The billing part rides the billing_join column list as its IncludeFields (the join's columns, + id; + description with includeNotes). The client-side folds (zero wire): rollup (billing items by ticketID; time entries by their own ticketID — the vendored TaskModel carries no ticket field, so the entry's own ticketID is the only resolvable ticket link; null → the unassigned bucket), unposted (the fetched entries whose id is in no fetched billing item's timeEntryID), totals { preTax = Σ extendedPrice, hours = Σ hoursWorked, entryCount, totalAmount, taxDollars — surfaced for reconciliation } derived from the SAME folded rows (one source of truth), warnings { noTimeEntry (the billing items whose timeEntryID is empty/0 — capped list + count), hourDelta (the billing items WITH a resolvable time entry where |billed quantity − hoursWorked| > 0 — strict; capped list + count) }. Company missing → NOT_FOUND (zero further wire). Closed opts bag: an unknown key → typed CONFIG_ERROR naming the key + the valid keys (one-round complete problem list, pre-request, zero wire).",
44140
44201
  "preferredWhen": "For allocation-style questions about one company's posted/uninvoiced work — replaces the multi-call billing×time×ticket hand-join; companies.fullProfile for the general company picture; operations.aggregate for cross-resource existence/totals",
44141
44202
  "related": [
44142
44203
  "companies.fullProfile",
@@ -44239,7 +44300,7 @@
44239
44300
  },
44240
44301
  "metadata": {
44241
44302
  "purpose": "Update a company.",
44242
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. CompanyModel has no `description` field (61 spec properties); the vendor accepts and 200s unknown fields on update with NO state change (receipt) — use documented fields; verify the changed field via get, not the 200. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
44303
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. CompanyModel has no `description` field (61 spec properties); the vendor accepts and 200s unknown fields on update with NO state change (receipt) — use documented fields; verify the changed field via get, not the 200. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
44243
44304
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
44244
44305
  "related": [
44245
44306
  "companies.get"
@@ -47614,7 +47675,7 @@
47614
47675
  },
47615
47676
  "metadata": {
47616
47677
  "purpose": "Update a company webhook.",
47617
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
47678
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
47618
47679
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
47619
47680
  "related": [
47620
47681
  "company_webhooks.get"
@@ -51181,7 +51242,7 @@
51181
51242
  },
51182
51243
  "metadata": {
51183
51244
  "purpose": "Update a configuration item webhook.",
51184
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
51245
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
51185
51246
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
51186
51247
  "related": [
51187
51248
  "configuration_item_webhooks.get"
@@ -51305,7 +51366,7 @@
51305
51366
  },
51306
51367
  "examples": [
51307
51368
  "await client.configurationItems.create({ companyID: 1001, productID: 123, isActive: true }, { dryRun: true })",
51308
- "this zone live wall (probes 500d on types 3/5/6): the body must set productID to an EXISTING Product (123 is illustrative — this zone has none: products.count is 0, no enumerable id) — this create is UNAVAILABLE in tenants without products. The body documents the wall, not a working create."
51369
+ "Illustrative ids only: replace companyID and productID with known tenant records, then preview the create before applying it."
51309
51370
  ],
51310
51371
  "permissions": "unknown",
51311
51372
  "pagination": {
@@ -51320,7 +51381,7 @@
51320
51381
  },
51321
51382
  "metadata": {
51322
51383
  "purpose": "Create a configuration item.",
51323
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Live wall: the body must set productID to an EXISTING Product; products.count is 0 on this zone (blind surface, no enumerable id) — this create is UNAVAILABLE in tenants without products. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
51384
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. productID must reference an existing Product; resolve it from tenant data or ask for a known id. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
51324
51385
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
51325
51386
  "related": [
51326
51387
  "configuration_items.update"
@@ -51933,7 +51994,7 @@
51933
51994
  },
51934
51995
  "examples": [
51935
51996
  "await client.configurationItems.profile(1)",
51936
- "Shape-only: NO CI record exists on this zone (the product wall blocked every create — products.count = 0), so the id is a placeholder and the op is mock-verified. args: (CI id, optional { noteLimit (default 50), relatedLimit (default 50) }). Wire: <=6 reads (get + type + category + 3 item-scoped queries; a dangling type/category FK skips its read). productAssociations is TYPED, never an error: on a tenant without enumerable products the part carries blind: true + the zone-facts note. CI missing → NOT_FOUND."
51997
+ "Replace the illustrative id with a known configuration item (asset/device) id. The profile reads the item and its related records; a missing item returns NOT_FOUND. Product-association rows are returned from the scoped query, without inferring tenant inventory from a product count."
51937
51998
  ],
51938
51999
  "permissions": "unknown",
51939
52000
  "pagination": {
@@ -51948,7 +52009,7 @@
51948
52009
  },
51949
52010
  "metadata": {
51950
52011
  "purpose": "Get the full profile of one configuration item in a single call: the item, its type and category records, its notes, related items and billing-product associations.",
51951
- "usage": "args[0] is the configuration item id (number); args[1] (optional) is the options object { noteLimit?: number (default 50), relatedLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name sibling on the ci row (closed scope: the contract name — the CI row has no issue-listed picklist fields, so no labels) + the top-level `names` section; the sibling rides the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: <=6 reads (get + type + category + 3 item-scoped queries; a dangling type/category FK skips its read). With names: true, N added name reads (N = the distinct uncached FK ids, capped by maxNameReads). productAssociations: the raw association rows (billingProductID FK) + the typed product-wall annotation from the served zone facts (blind: true + note) on tenants without enumerable products (this zone: products.count = 0) — never an error. CI missing → NOT_FOUND. On this zone no CI record exists (the product wall blocked every create) — no CI exists there (the product wall is the boundary), so the op is mock-verified.",
52012
+ "usage": "args[0] is the configuration item id (number); args[1] (optional) is the options object { noteLimit?: number (default 50), relatedLimit?: number (default 50), names?: boolean (default false — ON adds the opt-in name sibling on the ci row (closed scope: the contract name — the CI row has no issue-listed picklist fields, so no labels) + the top-level `names` section; the sibling rides the existing default-on caches (NO new cache)), maxNameReads?: number (default 20 — the budget of COLD wire name reads, lowerable never raised; over-budget ids serve name: null and the names section sets `truncated: true`, never an error) }. Wire: <=6 reads (get + type + category + 3 item-scoped queries; a dangling type/category FK skips its read). With names: true, N added name reads (N = the distinct uncached FK ids, capped by maxNameReads). productAssociations contains the scoped query rows and capped flag, with blind: false on a successful read; a product create requirement does not imply that associations are unreadable. A missing configuration item returns NOT_FOUND.",
51952
52013
  "preferredWhen": "The single read for 'what is this configuration item' — replaces 5-6 raw reads + describes with one call.",
51953
52014
  "related": [
51954
52015
  "configuration_items.get",
@@ -51959,7 +52020,7 @@
51959
52020
  "configuration_item_types.get",
51960
52021
  "configuration_item_categories.get"
51961
52022
  ],
51962
- "args": "args[0] is the configuration item id (number); args[1] (optional) is the options object { noteLimit?: number (default 50), relatedLimit?: number (default 50), names?: boolean (default false — the opt-in contract-name sibling on the ci row + the `names` section), maxNameReads?: number (default 20, lowerable never raised — the budget of cold wire name reads) }. <=6 bounded reads inside, zero mutating; the product-wall part is typed (blind + note from the served zone facts), never an error.",
52023
+ "args": "args[0] is the configuration item id (number); args[1] (optional) is the options object { noteLimit?: number (default 50), relatedLimit?: number (default 50), names?: boolean (default false — the opt-in contract-name sibling on the ci row + the `names` section), maxNameReads?: number (default 20, lowerable never raised — the budget of cold wire name reads) }. <=6 bounded reads inside, zero mutating; product associations are returned from the scoped vendor query without a static inventory or visibility assumption.",
51963
52024
  "untrustedFields": [
51964
52025
  "UDF1",
51965
52026
  "UDF10",
@@ -52354,7 +52415,7 @@
52354
52415
  },
52355
52416
  "metadata": {
52356
52417
  "purpose": "Update a configuration item.",
52357
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
52418
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
52358
52419
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
52359
52420
  "related": [
52360
52421
  "configuration_items.get"
@@ -53072,7 +53133,7 @@
53072
53133
  },
53073
53134
  "metadata": {
53074
53135
  "purpose": "Update a contact webhook.",
53075
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
53136
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
53076
53137
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
53077
53138
  "related": [
53078
53139
  "contact_webhooks.get"
@@ -53205,7 +53266,7 @@
53205
53266
  },
53206
53267
  "examples": [
53207
53268
  "await client.contacts.create(1001, { firstName: 'Jane', lastName: 'Doe', companyID: 1001, isActive: 1 }, { dryRun: true })",
53208
- "this zone validated required set: firstName, lastName, companyID, isActive — isActive is a NUMBER (1/0) in this zone, not a boolean (a JSON boolean 500s at the vendor parse layer). The create is parent-scoped (the company id rides the scoped path + the body)."
53269
+ "validated required set: firstName, lastName, companyID, isActive — isActive is a NUMBER (1/0), not a boolean (a JSON boolean 500s at the vendor parse layer). The create is parent-scoped (the company id rides the scoped path + the body)."
53209
53270
  ],
53210
53271
  "permissions": "unknown",
53211
53272
  "pagination": {
@@ -53220,7 +53281,7 @@
53220
53281
  },
53221
53282
  "metadata": {
53222
53283
  "purpose": "Create a contact. (under a company)",
53223
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. Live-required: firstName, lastName, companyID, isActive — isActive is a NUMBER (1), not a boolean, in this zone; the spec declares no required fields.",
53284
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. Live-required: firstName, lastName, companyID, isActive — isActive is a NUMBER (1), not a boolean; the spec declares no required fields.",
53224
53285
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
53225
53286
  "related": [
53226
53287
  "contacts.update"
@@ -54424,7 +54485,7 @@
54424
54485
  },
54425
54486
  "metadata": {
54426
54487
  "purpose": "Update a contact. (under a company)",
54427
- "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. isActive is a NUMBER (1/0) in this zone — a JSON boolean 500s at the vendor parse layer (ContactModel; LocationModel takes a boolean).",
54488
+ "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. isActive is a NUMBER (1/0) — a JSON boolean 500s at the vendor parse layer (ContactModel; LocationModel takes a boolean).",
54428
54489
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
54429
54490
  "related": [
54430
54491
  "contacts.get"
@@ -56289,7 +56350,7 @@
56289
56350
  },
56290
56351
  "metadata": {
56291
56352
  "purpose": "Create a contract charge.",
56292
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. (the contracts table is blind (0 rows) for this API user — no valid parent id can be read back via the API; provision the parent record in the Autotask UI first, then retry with the real parent id.)",
56353
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. The parentId path parameter must name a valid contracts record. Query the current tenant or read a known parent id; if the API user cannot read the required record, ask for the id. Do not infer API unavailability from an empty list.",
56293
56354
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
56294
56355
  "related": [
56295
56356
  "contract_charges.update"
@@ -64067,7 +64128,7 @@
64067
64128
  ]
64068
64129
  },
64069
64130
  "writeQuirks": {
64070
- "dateConventions": "date convention (live-proven on one reference zone, not universal): startDate and endDate are date-only at 00:00Z; tickets.dueDateTime is a true UTC instant."
64131
+ "dateConventions": "date convention (verify against current field metadata): startDate and endDate are date-only at 00:00Z; tickets.dueDateTime is a true UTC instant."
64071
64132
  }
64072
64133
  },
64073
64134
  "compact": null,
@@ -65154,7 +65215,7 @@
65154
65215
  },
65155
65216
  "metadata": {
65156
65217
  "purpose": "Update a contract.",
65157
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
65218
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
65158
65219
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
65159
65220
  "related": [
65160
65221
  "contracts.get"
@@ -65186,7 +65247,7 @@
65186
65247
  "description"
65187
65248
  ],
65188
65249
  "writeQuirks": {
65189
- "dateConventions": "date convention (live-proven on one reference zone, not universal): startDate and endDate are date-only at 00:00Z; tickets.dueDateTime is a true UTC instant."
65250
+ "dateConventions": "date convention (verify against current field metadata): startDate and endDate are date-only at 00:00Z; tickets.dueDateTime is a true UTC instant."
65190
65251
  }
65191
65252
  },
65192
65253
  "compact": null,
@@ -65845,7 +65906,7 @@
65845
65906
  },
65846
65907
  "metadata": {
65847
65908
  "purpose": "Update an invoice.",
65848
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
65909
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
65849
65910
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
65850
65911
  "related": [
65851
65912
  "invoices.get"
@@ -66637,7 +66698,7 @@
66637
66698
  },
66638
66699
  "metadata": {
66639
66700
  "purpose": "Update an opportunity.",
66640
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
66701
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
66641
66702
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
66642
66703
  "related": [
66643
66704
  "opportunities.get"
@@ -67991,7 +68052,7 @@
67991
68052
  },
67992
68053
  "metadata": {
67993
68054
  "purpose": "Create a project charge.",
67994
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. (the projects table is blind (0 rows) for this API user — no valid parent id can be read back via the API; provision the parent record in the Autotask UI first, then retry with the real parent id.)",
68055
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. The parentId path parameter must name a valid projects record. Query the current tenant or read a known parent id; if the API user cannot read the required record, ask for the id. Do not infer API unavailability from an empty list.",
67995
68056
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
67996
68057
  "related": [
67997
68058
  "project_charges.update"
@@ -69299,7 +69360,7 @@
69299
69360
  },
69300
69361
  "examples": [
69301
69362
  "await client.projects.create({ projectName: 'Example', description: 'Example', companyID: 0, projectType: 2, status: 1, startDateTime: '2026-10-03T00:00:00Z', endDateTime: '2026-10-10T00:00:00Z' }, { dryRun: true })",
69302
- "this zone validated: created a project with this full proven body (companyID 0 = tenant-global; project 8002 was a sample record, never-mutated fixture reference). Per-field minimality was not isolated live — keep the full shape."
69363
+ "validated: created a project with this full proven body (companyID 0 = tenant-global; project 8002 was a sample record, never-mutated fixture reference). Per-field minimality was not isolated live — keep the full shape."
69303
69364
  ],
69304
69365
  "permissions": "unknown",
69305
69366
  "pagination": {
@@ -70121,7 +70182,7 @@
70121
70182
  },
70122
70183
  "metadata": {
70123
70184
  "purpose": "Update a project.",
70124
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
70185
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
70125
70186
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
70126
70187
  "related": [
70127
70188
  "projects.get"
@@ -71384,7 +71445,7 @@
71384
71445
  },
71385
71446
  "metadata": {
71386
71447
  "purpose": "Update a quote location.",
71387
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
71448
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
71388
71449
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
71389
71450
  "related": [
71390
71451
  "quote_locations.get"
@@ -72035,7 +72096,7 @@
72035
72096
  },
72036
72097
  "metadata": {
72037
72098
  "purpose": "Update a quote.",
72038
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
72099
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
72039
72100
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
72040
72101
  "related": [
72041
72102
  "quotes.get"
@@ -72906,7 +72967,7 @@
72906
72967
  },
72907
72968
  "metadata": {
72908
72969
  "purpose": "Update a subscription.",
72909
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
72970
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
72910
72971
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
72911
72972
  "related": [
72912
72973
  "subscriptions.get"
@@ -73592,7 +73653,7 @@
73592
73653
  },
73593
73654
  "examples": [
73594
73655
  "await client.tasks.create(8001, { title: 'Example', projectID: 8001, taskType: 1, status: 1 }, { dryRun: true })",
73595
- "this zone verified: created task 7003 with this body under project 8001 (the DEL-GAP fixture — FK/read only, never mutated). projectID is REQUIRED IN THE BODY (the scoped parent path carries the parent too); taskType is an integer picklist (1/2); a missing required field 500s with a typed field-level error."
73656
+ "verified: created task 7003 with this body under project 8001 (the DEL-GAP fixture — FK/read only, never mutated). projectID is REQUIRED IN THE BODY (the scoped parent path carries the parent too); taskType is an integer picklist (1/2); a missing required field 500s with a typed field-level error."
73596
73657
  ],
73597
73658
  "permissions": "unknown",
73598
73659
  "pagination": {
@@ -77359,7 +77420,7 @@
77359
77420
  },
77360
77421
  "metadata": {
77361
77422
  "purpose": "Update a ticket charge.",
77362
- "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. ticketID does NOT persist on update (success returned, old ticketID kept; probed live on this zone). To re-parent use ticket_charges.moveToTicket (create, verify, delete).",
77423
+ "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. ticketID does NOT persist on update (success returned, old ticketID kept; probed live, 2026-10-21). To re-parent use ticket_charges.moveToTicket (create, verify, delete).",
77363
77424
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change. Not for ticketID: use ticket_charges.moveToTicket.",
77364
77425
  "related": [
77365
77426
  "ticket_charges.get"
@@ -78412,8 +78473,8 @@
78412
78473
  "drops": []
78413
78474
  },
78414
78475
  "examples": [
78415
- "await client.ticketNotes.create(7001, { description: 'Example', noteType: 1, publish: 1 }, { dryRun: true })",
78416
- "this zone validated: created a note under ticket 7001 with this body. publish is an INTEGER picklist (1/2/4), NOT a boolean (a JSON boolean 500s); noteType is an integer; ticketID is NOT in the body (the scoped parent path supplies it); title is optional."
78476
+ "await client.ticketNotes.create(7001, { description: 'Example', noteType: 1, publish: 1, title: 'Example' }, { dryRun: true })",
78477
+ "validated: a title-less note was created under ticket 7001; with a title the create succeeds and without one the vendor refuses (body verbatim: \"Missing Required Field: title.\"); publish is an INTEGER picklist (1/2/4), NOT a boolean (a JSON boolean 500s); noteType is an integer; ticketID is NOT in the body (the scoped parent path supplies it)."
78417
78478
  ],
78418
78479
  "permissions": "unknown",
78419
78480
  "pagination": {
@@ -78428,7 +78489,7 @@
78428
78489
  },
78429
78490
  "metadata": {
78430
78491
  "purpose": "Create a ticket note.",
78431
- "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. publish is an integer picklist (1/2/4) and noteType is an integer — both INT, a JSON boolean 500s at the vendor parse layer. Live-required: description, noteType, publish; ticketID is NOT in the body (the scoped parent path supplies it); title is optional. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78492
+ "usage": "Returns OperationResultModel.itemId (the new id); the full record is not returned — follow up with get where needed. Parent-scoped: parentId is a path parameter. publish is an integer picklist (1/2/4) and noteType is an integer — both INT, a JSON boolean 500s at the vendor parse layer. Live-required: description, noteType, publish, title; ticketID is NOT in the body (the scoped parent path supplies it). A title-less create is refused by the vendor (\"Missing Required Field: title.\"); a create with title succeeded. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78432
78493
  "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
78433
78494
  "related": [
78434
78495
  "ticket_notes.update"
@@ -78888,7 +78949,7 @@
78888
78949
  },
78889
78950
  "metadata": {
78890
78951
  "purpose": "Update a ticket note.",
78891
- "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. Setting ticketID in the body MOVES the note: the parent-scoped update (oldTicketID, noteId, { ticketID: newTicketID }) persists (probed live on this zone). There is no unscoped route (404) and notes cannot be deleted (405), so a note is never moved by create-then-delete. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78952
+ "usage": "Issues PATCH on the collection (swagger documents put+patch there; the node strips the id from the path and the vendor keys the record by the id in the body). Stale check via lastModifiedDate where present. Parent-scoped: parentId + id. Setting ticketID in the body MOVES the note: the parent-scoped update (oldTicketID, noteId, { ticketID: newTicketID }) persists (probed live, 2026-10-21). There is no unscoped route (404) and notes cannot be deleted (405), so a note is never moved by create-then-delete. No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
78892
78953
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
78893
78954
  "related": [
78894
78955
  "ticket_notes.get"
@@ -80121,7 +80182,7 @@
80121
80182
  },
80122
80183
  "metadata": {
80123
80184
  "purpose": "Update a ticket webhook.",
80124
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
80185
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge).",
80125
80186
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
80126
80187
  "related": [
80127
80188
  "ticket_webhooks.get"
@@ -80169,7 +80230,7 @@
80169
80230
  },
80170
80231
  "examples": [
80171
80232
  "await client.tickets.changeStatus(7002, 14, {}, { dryRun: true })",
80172
- "this zone: args (ticket id, targetStatus from the tenant's LIVE status picklist (the entity metadata is the oracle; the values + labels are discoverable with operations.fieldCatalog({ resources: [tickets], fields: [status], labels: true })), optional caller fields, opts). The node validates the status pre-request against the live picklist (the vendor's own validation decides when the metadata is unavailable), merges the current record (one GET) and fills the proven-safe defaults for the fields the target status requires that the record lacks (the per-status map is live-discovered vendor state). current === target → typed NO_CHANGE (zero mutating wire). 7002 = a sample ticket (verified present); dry-run shown — apply mutates the ticket."
80233
+ "args (ticket id, targetStatus from the tenant's LIVE status picklist (the entity metadata is the oracle; the values + labels are discoverable with operations.fieldCatalog({ resources: [tickets], fields: [status], labels: true })), optional caller fields, opts). The node validates the status pre-request against the live picklist (the vendor's own validation decides when the metadata is unavailable), merges the current record (one GET) and fills the proven-safe defaults for the fields the target status requires that the record lacks (the per-status map is live-discovered vendor state). current === target → typed NO_CHANGE (zero mutating wire). 7002 = a sample ticket (verified present); dry-run shown — apply mutates the ticket."
80173
80234
  ],
80174
80235
  "permissions": "unknown",
80175
80236
  "pagination": {
@@ -80277,7 +80338,7 @@
80277
80338
  },
80278
80339
  "metadata": {
80279
80340
  "purpose": "Count ticket records matching a JSON filter.",
80280
- "usage": "Unwraps queryCount; returns a plain number. Zone quirk: count/query return 0/empty on this surface (0 before AND after a proven live create) — verify presence with get(id), not count.",
80341
+ "usage": "Unwraps queryCount; returns a plain number. Visibility caution: the tickets count/query surface may omit records the current API user cannot list. An empty result is inconclusive about tenant inventory; verify a known record with get(id).",
80281
80342
  "preferredWhen": null,
80282
80343
  "related": [
80283
80344
  "tickets.query"
@@ -80287,7 +80348,7 @@
80287
80348
  "surface": "tickets.count",
80288
80349
  "kind": "unfiltered-blind",
80289
80350
  "authority": "tickets.get",
80290
- "note": "the UNFILTERED tickets count/query surface is blind in this zone (verified: 0 before AND after a proven live create). FILTERED queries return data (verified: 3 open tickets via a companyID+status filter) — a filtered empty result is a TRUE absence, never a sentinel. An unfiltered 0/empty result proves nothing — get(id) is the authority."
80351
+ "note": "The unfiltered tickets count result may be limited by API-user visibility. A zero or empty response is INCONCLUSIVE about tenant inventory or API capability. Narrow the query and verify a known record with tickets.get; if that read is not permitted, ask the user for the missing information."
80291
80352
  },
80292
80353
  "untrustedFields": [
80293
80354
  "UDF1",
@@ -80348,7 +80409,7 @@
80348
80409
  },
80349
80410
  "examples": [
80350
80411
  "await client.tickets.create({ title: 'Example', status: 1, priority: 3, companyID: 1001, queueID: 3001 }, { dryRun: true })",
80351
- "this zone validated: created a ticket with exactly this field set (companyID anonymized to the fixture company 1001). A body missing any of title/status/priority/companyID/queueID 500s with a typed field-level error."
80412
+ "validated: created a ticket with exactly this field set (companyID anonymized to the fixture company 1001). A body missing any of title/status/priority/companyID/queueID 500s with a typed field-level error."
80352
80413
  ],
80353
80414
  "permissions": "unknown",
80354
80415
  "pagination": {
@@ -80705,7 +80766,7 @@
80705
80766
  },
80706
80767
  "examples": [
80707
80768
  "await client.tickets.fullContext(7002)",
80708
- "this zone validated: a run served 7002 in 5 wire (ticket + company part + 3 scoped queries; the dangling FK parts were 'absent'; 5 notes; long text capped at the default textLimit and flagged). args: (ticket id, optional { noteLimit (default 50), timeEntryLimit (default 50), includeAttachments (default true — metadata only: ids + names), includeHistories (default false), textLimit (default 500) }). Wire: 8 bounded reads (10 with histories). A missing/dangling FK part is null + 'absent' — a part miss never fails the op; the ticket itself missing → NOT_FOUND."
80769
+ "validated: a run served 7002 in 5 wire (ticket + company part + 3 scoped queries; the dangling FK parts were 'absent'; 5 notes; long text capped at the default textLimit and flagged). args: (ticket id, optional { noteLimit (default 50), timeEntryLimit (default 50), includeAttachments (default true — metadata only: ids + names), includeHistories (default false), textLimit (default 500) }). Wire: 8 bounded reads (10 with histories). A missing/dangling FK part is null + 'absent' — a part miss never fails the op; the ticket itself missing → NOT_FOUND."
80709
80770
  ],
80710
80771
  "permissions": "unknown",
80711
80772
  "pagination": {
@@ -81385,7 +81446,7 @@
81385
81446
  },
81386
81447
  "metadata": {
81387
81448
  "purpose": "Query Ticket records with a JSON filter.",
81388
- "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Zone quirk: count/query return 0/empty on this surface (0 before AND after a proven live create) — verify presence with get(id), not count. Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
81449
+ "usage": "Server-side pagination: one call walks the vendor cursor internally (page 1 POSTs the QueryModel body with MaxRecords = the walk's internal page size (at most 500; the default POST path — `via: 'get'` issues a GET on page 1); later pages POST the SAME body — IncludeFields, MaxRecords and the preserved filter — to the absolute vendor cursor, rebased to the client base URL; the vendor honours IncludeFields on a continuation and ignores MaxRecords there, so a later page carries the vendor's own page size) until the limit is met or the cursor is null; 1000-page guard (hasMore stays true at the guard). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. noteChars: N (integer >= 1) is an opt-in per-field char cap on the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose — the same set the server wraps): each capped value = the first N chars + the explicit marker … [+N chars truncated] (N = chars removed), applied at result-build BEFORE the server-side untrusted wrapper; absent = the raw, untruncated result (zero wire — response-side only). latest: N returns the N highest-id rows (id-descending): the vendor has no sort parameter — this is the only ordering channel, and a date window in `filter` narrows the cost; count-anchored — C ≤ 2500 → one count + a ≤6-page walk of the matching set, C > 2500 → count probes + an id-threshold window (≤64 probes; LATEST_THRESHOLD_UNRESOLVED on budget exhaustion), a blind count → a bounded walk with the blind-surface stamp (LATEST_WINDOW_INCOMPLETE on a truncated walk). Visibility caution: the tickets count/query surface may omit records the current API user cannot list. An empty result is inconclusive about tenant inventory; verify a known record with get(id). Explicit walk.maxRows independently sets the TOTAL returned-row cap (including export-sized walks); the ordinary limit is still validated in 1..2500 and only bounds the internal page size for this form. hasMore and truncated remain true at the page guard or while a cursor or unserved fetched rows remain. Self-resource prefixes are accepted in filter fields and includeFields; dotted UDF names are always refused before metadata or vendor requests, never rewritten to another tenant UDF.",
81389
81450
  "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
81390
81451
  "related": [
81391
81452
  "tickets.resolve"
@@ -81395,7 +81456,7 @@
81395
81456
  "surface": "tickets.query",
81396
81457
  "kind": "unfiltered-blind",
81397
81458
  "authority": "tickets.get",
81398
- "note": "the UNFILTERED tickets count/query surface is blind in this zone (verified: 0 before AND after a proven live create). FILTERED queries return data (verified: 3 open tickets via a companyID+status filter) — a filtered empty result is a TRUE absence, never a sentinel. An unfiltered 0/empty result proves nothing — get(id) is the authority."
81459
+ "note": "The unfiltered tickets query result may be limited by API-user visibility. A zero or empty response is INCONCLUSIVE about tenant inventory or API capability. Narrow the query and verify a known record with tickets.get; if that read is not permitted, ask the user for the missing information."
81399
81460
  },
81400
81461
  "untrustedFields": [
81401
81462
  "UDF1",
@@ -82077,7 +82138,7 @@
82077
82138
  },
82078
82139
  "metadata": {
82079
82140
  "purpose": "Update a ticket.",
82080
- "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET — also the stale-object guard's read) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
82141
+ "usage": "Issues PUT (vendor tolerates PATCH for the same endpoint). Stale check via lastModifiedDate where present. The collection PUT validates the FULL model (vendor V2): a partial body is merged into the current record (one GET; when a stale-check field is configured, the same read also supplies that guard) before the PUT; explicit nulls send null, omitted fields keep the current value. Pass raw: true in the opts bag to send the body as-is (no merge). No delete: the vendor defines no DELETE for this entity (the endpoint 405s; cleanup is UI-only).",
82081
82142
  "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
82082
82143
  "related": [
82083
82144
  "tickets.get"
@@ -82134,8 +82195,8 @@
82134
82195
  ]
82135
82196
  },
82136
82197
  "operations": {
82137
- "planHash": "c92aaa7dd21259e4e8b545e44cebf4d831e5f68a0c9e41e26af1c2966c84bdef",
82138
- "builtAt": "2026-11-12T01:38:06.866Z",
82198
+ "planHash": "94052c314d189d4b2fcf6bc842d983d4817c8410109074ed9505b682f4855790",
82199
+ "builtAt": "2026-11-17T05:04:54.690Z",
82139
82200
  "records": [
82140
82201
  {
82141
82202
  "id": "operations.aggregate",
@@ -82162,7 +82223,7 @@
82162
82223
  "opts": {
82163
82224
  "type": "object",
82164
82225
  "required": false,
82165
- "description": "AggregateOptions — { groupBy?: string[] (vendor field names), sum?: string[] (numeric vendor fields), top?: number (default 25, clamped 1..100 — the group-row cap), limit?: number (total-record cap for the walk modes, default 2500 = the house BOUNDED_QUERY_MAX_LIMIT — the hard max), names?: boolean (absent = the client's labels option — OFF by default; true — group keys gain label siblings, e.g. key.ticketIDName, key.statusLabel — null, never missing, when the field is keyed with a null value, a 0 id or an unresolved value (a picklist 0 is labelled when the picklist defines it); false = raw ids), acknowledgeUnscoped?: boolean (a group/sum with NO filter — absent or empty — walks the whole tenant table and is refused PRE-REQUEST with the typed SCOPE_REQUIRED (zero wire) unless this is true; the count mode is unaffected — one vendor count, no walk) }. NEITHER groupBy nor sum = COUNT mode (one vendor /query/count call — no walk; a 0 on a plan-pinned blind surface is marked blind: true with the sentinel — never a silent absence; a FILTERED 0 on an unfiltered-blind surface is a true zero). The walk modes fold client-side: hasMore/totalScanned carry the truncation honesty (no silent partial sums) and a mid-walk RATE_LIMITED propagates (the partial fold is discarded).",
82226
+ "description": "AggregateOptions — { groupBy?: string[] (vendor field names), sum?: string[] (numeric vendor fields), top?: number (default 25, clamped 1..100 — the group-row cap), limit?: number (total-record cap for the walk modes, default 2500 = the house BOUNDED_QUERY_MAX_LIMIT — the hard max), names?: boolean (absent = the client's labels option — OFF by default; true — group keys gain label siblings, e.g. key.ticketIDName, key.statusLabel — null, never missing, when the field is keyed with a null value, a 0 id or an unresolved value (a picklist 0 is labelled when the picklist defines it); false = raw ids), acknowledgeUnscoped?: boolean (a group/sum with NO filter — absent or empty — walks the whole tenant table and is refused PRE-REQUEST with the typed SCOPE_REQUIRED (zero wire) unless this is true; the count mode is unaffected — one vendor count, no walk) }. NEITHER groupBy nor sum = COUNT mode (one vendor /query/count call — no walk; a 0 on a plan-pinned blind surface is marked blind: true with the sentinel — never a silent absence; a filtered 0 on an unfiltered-blind surface is an unstamped result under current API-user visibility, not proof of tenant-wide absence). The walk modes fold client-side: hasMore/totalScanned carry the truncation honesty (no silent partial sums) and a mid-walk RATE_LIMITED propagates (the partial fold is discarded).",
82166
82227
  "properties": [
82167
82228
  {
82168
82229
  "name": "groupBy",
@@ -82207,7 +82268,7 @@
82207
82268
  "examples": [
82208
82269
  "await invoke(client, 'operations.aggregate', ['billing_items.query', [{ field: 'companyID', op: 'eq', value: 1001 }]])",
82209
82270
  "await invoke(client, 'operations.aggregate', ['time_entries.query', [{ field: 'dateWorked', op: 'gte', value: '2026-09-01' }], { groupBy: ['ticketID'], sum: ['hoursWorked'], top: 10 }])",
82210
- "Synthetic shape (no tenant data): args (invoke form) = the operation (exactly the plan resource's.query op — e.g. billing_items.query), the filter (the query-bag filter grammar — an empty array = the unfiltered call), and the optional AggregateOptions. NEITHER groupBy nor sum = COUNT mode (ONE vendor /query/count — no walk; a 0 on a plan-pinned blind surface is marked blind: true with the sentinel — never a silent absence; a FILTERED 0 on an unfiltered-blind surface is a true zero). Walk modes: page size min(500, limit), ≤ ceil(limit/500) pages + the 1000-page guard; groups/sums cover the returned rows ONLY when hasMore (no silent partial sums). Read op — no dry run."
82271
+ "Synthetic shape (no tenant data): args (invoke form) = the operation (exactly the plan resource's.query op — e.g. billing_items.query), the filter (the query-bag filter grammar — an empty array = the unfiltered call), and the optional AggregateOptions. NEITHER groupBy nor sum = COUNT mode (ONE vendor /query/count — no walk; a 0 on a plan-pinned blind surface is marked blind: true with the sentinel — never a silent absence; a filtered 0 on an unfiltered-blind surface is an unstamped result under current API-user visibility, not proof of tenant-wide absence). Walk modes: page size min(500, limit), ≤ ceil(limit/500) pages + the 1000-page guard; groups/sums cover the returned rows ONLY when hasMore (no silent partial sums). Read op — no dry run."
82211
82272
  ],
82212
82273
  "permissions": "unknown",
82213
82274
  "pagination": {
@@ -82222,14 +82283,14 @@
82222
82283
  },
82223
82284
  "metadata": {
82224
82285
  "purpose": "Fold any query surface into groups/sums/totals in one bounded call — or count it with the vendor count endpoint when no folding is needed — with blind-surface and truncation honesty (caps documented: the walk scans at most 2500 rows and top keeps at most 100 groups — a truncated aggregate is a PARTIAL answer, never a tenant-wide total); date fields bucket via the closed groupBy suffix <field>@month | @week | @year (ISO labels, UTC-anchored). Use it for totals, sums, counts and hours per ticket, resource, company, contract or month (group by any field), e.g. time entries hours grouped by ticket and resource",
82225
- "usage": "args[0] is the operation — EXACTLY <planResourceKey>.query (a plan resource WITH a query row — the registry is the closed set; a special op, a.count row, or an unknown resource is refused pre-request naming autotask_catalog). args[1] is the filter (the query-bag filter grammar: 13 operators; caps 500 OR-conditions / 1 UDF / 8000 chars; field names in vendor casing via operations.fieldCatalog; an empty array = the unfiltered call). args[2] (optional) is AggregateOptions { groupBy?: string[] (vendor field names; a DATE-TYPED field may carry the closed bucket suffix @month | @week | @year — the group key is named by the full spec (e.g. dateWorked@month) and carries the ISO bucket label 2026-09 / 2026-W38 / 2026 read on the UTC calendar — (the API is UTC; date-only value = its UTC day, zoned datetime = its instant, zoneless datetime = a UTC wall time; week = the ISO 8601 week date, Monday start, ISO year); the base validates against the vendored MODEL_FIELD_SETS AND the resource date-typed fields (MODEL_DATE_FIELDS — the vendored model string date/date-time fields) pre-request (zero wire; an unknown suffix or a non-date base is the typed CONFIG_ERROR in the one-round complete problem list); a null/absent value folds into the one null bucket group and a value that parses as no date keeps its raw value as its own group), sum?: string[] (numeric vendor fields), top?: number (default 25, clamped 1..100 — the group-row cap), limit?: number (default 2500 = the house BOUNDED_QUERY_MAX_LIMIT — the hard max) }. Modes: NEITHER groupBy NOR sum → COUNT (ONE POST /V1.0/<Entity>/query/count — the vendor count endpoint; no walk; a 0 on a plan-pinned blind surface is marked blind: true with the typed sentinel — never a silent absence; a FILTERED 0 on an unfiltered-blind surface is a true zero, never a sentinel). groupBy and/or sum → the house bounded walk of <resource>.query (server-side pagination; page size min(500, limit); the 1000-page guard) + the client-side fold (per-group count + the sum fields — non-numeric/absent values contribute 0, documented; top-N groups, descending count, deterministic group-key tie-break). Result: { mode, count?, groups? [{ key, count, sums? }], totalGroups? (distinct groups before top), groupsTruncated? (top dropped groups), totalScanned?, hasMore?, truncated (D6: the walk hit its limit — groups may be incomplete; count mode: false), blind?, blindSurface?, emptyReason? } — when hasMore is true, groups/sums cover the RETURNED rows ONLY (no silent partial sums — the truncation honesty). MANDATORY PARTIAL MARKER: a truncated aggregate (hasMore true OR groupsTruncated true) is a PARTIAL answer — never a tenant-wide total: the walk scans at most `limit` rows (default and hard max 2500 = the house BOUNDED_QUERY_MAX_LIMIT), `top` keeps at most 100 groups (default 25; a larger top is clamped, never raised), and totalScanned stays reported for reasoning (the rows the fold actually scanned; the tenant-wide total is obtainable via <resource>.count with the same filter). For an exact tenant-wide answer narrow the filter (e.g. a dateWorked window) so the set fits the caps, or use the bounded query op (the same <resource>.query op — the autotask_query surface) with the same filter for the exact full set within its 2500-row walk cap; raw REST for the rest. A zero-row walk carries the blindSurface/emptyReason stamps (no silent empty groups); a mid-walk RATE_LIMITED propagates (the partial fold is discarded — the error is the answer). Wire: count = 1 POST; walk ≤ ceil(limit/500) pages + the guard. READ op — no dry-run/confirm interaction. groupBy/sum field names validate against the vendored MODEL_FIELD_SETS pre-request (the complete problem list in one typed error, zero wire; a live-field opt-in is a follow-up, not this op). groupBy and sum accept the query resource’s self-prefix aliases; normalized group names preserve date-bucket suffixes. True parent relation paths are not stripped. Dotted UDF filters are always refused before metadata or vendor requests.",
82286
+ "usage": "args[0] is the operation — EXACTLY <planResourceKey>.query (a plan resource WITH a query row — the registry is the closed set; a special op, a.count row, or an unknown resource is refused pre-request naming autotask_catalog). args[1] is the filter (the query-bag filter grammar: 13 operators; caps 500 OR-conditions / 1 UDF / 8000 chars; field names in vendor casing via operations.fieldCatalog; an empty array = the unfiltered call). args[2] (optional) is AggregateOptions { groupBy?: string[] (vendor field names; a DATE-TYPED field may carry the closed bucket suffix @month | @week | @year — the group key is named by the full spec (e.g. dateWorked@month) and carries the ISO bucket label 2026-09 / 2026-W38 / 2026 read on the UTC calendar — (the API is UTC; date-only value = its UTC day, zoned datetime = its instant, zoneless datetime = a UTC wall time; week = the ISO 8601 week date, Monday start, ISO year); the base validates against the vendored MODEL_FIELD_SETS AND the resource date-typed fields (MODEL_DATE_FIELDS — the vendored model string date/date-time fields) pre-request (zero wire; an unknown suffix or a non-date base is the typed CONFIG_ERROR in the one-round complete problem list); a null/absent value folds into the one null bucket group and a value that parses as no date keeps its raw value as its own group), sum?: string[] (numeric vendor fields), top?: number (default 25, clamped 1..100 — the group-row cap), limit?: number (default 2500 = the house BOUNDED_QUERY_MAX_LIMIT — the hard max) }. Modes: NEITHER groupBy NOR sum → COUNT (ONE POST /V1.0/<Entity>/query/count — the vendor count endpoint; no walk; a 0 on a plan-pinned blind surface is marked blind: true with the typed sentinel — never a silent absence; a filtered 0 on an unfiltered-blind surface is an unstamped result under current API-user visibility, not proof of tenant-wide absence, never a sentinel). groupBy and/or sum → the house bounded walk of <resource>.query (server-side pagination; page size min(500, limit); the 1000-page guard) + the client-side fold (per-group count + the sum fields — non-numeric/absent values contribute 0, documented; top-N groups, descending count, deterministic group-key tie-break). Result: { mode, count?, groups? [{ key, count, sums? }], totalGroups? (distinct groups before top), groupsTruncated? (top dropped groups), totalScanned?, hasMore?, truncated (D6: the walk hit its limit — groups may be incomplete; count mode: false), blind?, blindSurface?, emptyReason? } — when hasMore is true, groups/sums cover the RETURNED rows ONLY (no silent partial sums — the truncation honesty). MANDATORY PARTIAL MARKER: a truncated aggregate (hasMore true OR groupsTruncated true) is a PARTIAL answer — never a tenant-wide total: the walk scans at most `limit` rows (default and hard max 2500 = the house BOUNDED_QUERY_MAX_LIMIT), `top` keeps at most 100 groups (default 25; a larger top is clamped, never raised), and totalScanned stays reported for reasoning (the rows the fold actually scanned; the tenant-wide total is obtainable via <resource>.count with the same filter). For an exact tenant-wide answer narrow the filter (e.g. a dateWorked window) so the set fits the caps, or use the bounded query op (the same <resource>.query op — the autotask_query surface) with the same filter for the exact full set within its 2500-row walk cap; raw REST for the rest. A zero-row walk carries the blindSurface/emptyReason stamps (no silent empty groups); a mid-walk RATE_LIMITED propagates (the partial fold is discarded — the error is the answer). Wire: count = 1 POST; walk ≤ ceil(limit/500) pages + the guard. READ op — no dry-run/confirm interaction. groupBy/sum field names validate against the vendored MODEL_FIELD_SETS pre-request (the complete problem list in one typed error, zero wire; a live-field opt-in is a follow-up, not this op). groupBy and sum accept the query resource’s self-prefix aliases; normalized group names preserve date-bucket suffixes. True parent relation paths are not stripped. Dotted UDF filters are always refused before metadata or vendor requests.",
82226
82287
  "preferredWhen": "For existence checks and totals over any queryable table (count mode is one call vs a 50k-char page); group-by/sum folds the vendor has no endpoint for; a targeted read is cheaper when you need the rows",
82227
82288
  "related": [
82228
82289
  "<dynamic> — the 116 *.query surfaces",
82229
82290
  "operations.fieldCatalog",
82230
82291
  "autotask_catalog"
82231
82292
  ],
82232
- "args": "args[0] is the operation (<planResourceKey>.query ONLY — a special op, a.count row, or an unknown resource is refused naming autotask_catalog); args[1] is the filter (the query-bag filter grammar: 13 operators, caps 500 OR-conditions / 1 UDF / 8000 chars; field names in vendor casing via operations.fieldCatalog; an empty array = the unfiltered call); args[2] (optional) is AggregateOptions { groupBy?: string[] (vendor field names; a DATE-TYPED field may carry the closed bucket suffix @month | @week | @year — the group key is named by the full spec (e.g. dateWorked@month) and carries the ISO bucket label 2026-09 / 2026-W38 / 2026 read on the UTC calendar — (the API is UTC; date-only value = its UTC day, zoned datetime = its instant, zoneless datetime = a UTC wall time; week = the ISO 8601 week date, Monday start, ISO year); the base validates against the vendored MODEL_FIELD_SETS AND the resource date-typed fields (MODEL_DATE_FIELDS — the vendored model string date/date-time fields) pre-request (zero wire; an unknown suffix or a non-date base is the typed CONFIG_ERROR in the one-round complete problem list); a null/absent value folds into the one null bucket group and a value that parses as no date keeps its raw value as its own group), sum?: string[] (numeric vendor fields), top?: number (default 25, clamped 1..100 — the group-row cap), limit?: number (default 2500 = the house BOUNDED_QUERY_MAX_LIMIT — the hard max), acknowledgeUnscoped?: boolean (a group/sum with NO filter — absent or empty — walks the whole tenant table and is refused PRE-REQUEST with the typed SCOPE_REQUIRED (zero wire) unless this is true; the count mode is unaffected — one vendor count, no walk; the narrow remedy is a filter with an id scope: eq/in on an id field) }. NEITHER groupBy nor sum = COUNT mode (one vendor /query/count call — no walk; a 0 on a plan-pinned blind surface is marked blind: true — never a silent absence; a FILTERED 0 on an unfiltered-blind surface is a true zero). The walk modes fold client-side: hasMore/totalScanned = the truncation honesty (no silent partial sums) — a truncated aggregate (hasMore or groupsTruncated true) is a PARTIAL answer, never a tenant-wide total: the walk scans at most `limit` rows (default and hard max 2500) and `top` keeps at most 100 groups (default 25; clamped, never raised); for an exact tenant-wide answer narrow the filter (e.g. a dateWorked window) so the set fits the caps, or use the bounded query op (autotask_query) with the same filter (its 2500-row walk cap); raw REST for the rest. A mid-walk RATE_LIMITED propagates (the partial fold is discarded)."
82293
+ "args": "args[0] is the operation (<planResourceKey>.query ONLY — a special op, a.count row, or an unknown resource is refused naming autotask_catalog); args[1] is the filter (the query-bag filter grammar: 13 operators, caps 500 OR-conditions / 1 UDF / 8000 chars; field names in vendor casing via operations.fieldCatalog; an empty array = the unfiltered call); args[2] (optional) is AggregateOptions { groupBy?: string[] (vendor field names; a DATE-TYPED field may carry the closed bucket suffix @month | @week | @year — the group key is named by the full spec (e.g. dateWorked@month) and carries the ISO bucket label 2026-09 / 2026-W38 / 2026 read on the UTC calendar — (the API is UTC; date-only value = its UTC day, zoned datetime = its instant, zoneless datetime = a UTC wall time; week = the ISO 8601 week date, Monday start, ISO year); the base validates against the vendored MODEL_FIELD_SETS AND the resource date-typed fields (MODEL_DATE_FIELDS — the vendored model string date/date-time fields) pre-request (zero wire; an unknown suffix or a non-date base is the typed CONFIG_ERROR in the one-round complete problem list); a null/absent value folds into the one null bucket group and a value that parses as no date keeps its raw value as its own group), sum?: string[] (numeric vendor fields), top?: number (default 25, clamped 1..100 — the group-row cap), limit?: number (default 2500 = the house BOUNDED_QUERY_MAX_LIMIT — the hard max), acknowledgeUnscoped?: boolean (a group/sum with NO filter — absent or empty — walks the whole tenant table and is refused PRE-REQUEST with the typed SCOPE_REQUIRED (zero wire) unless this is true; the count mode is unaffected — one vendor count, no walk; the narrow remedy is a filter with an id scope: eq/in on an id field) }. NEITHER groupBy nor sum = COUNT mode (one vendor /query/count call — no walk; a 0 on a plan-pinned blind surface is marked blind: true — never a silent absence; a filtered 0 on an unfiltered-blind surface is an unstamped result under current API-user visibility, not proof of tenant-wide absence). The walk modes fold client-side: hasMore/totalScanned = the truncation honesty (no silent partial sums) — a truncated aggregate (hasMore or groupsTruncated true) is a PARTIAL answer, never a tenant-wide total: the walk scans at most `limit` rows (default and hard max 2500) and `top` keeps at most 100 groups (default 25; clamped, never raised); for an exact tenant-wide answer narrow the filter (e.g. a dateWorked window) so the set fits the caps, or use the bounded query op (autotask_query) with the same filter (its 2500-row walk cap); raw REST for the rest. A mid-walk RATE_LIMITED propagates (the partial fold is discarded)."
82233
82294
  },
82234
82295
  "compact": "AggregateResult",
82235
82296
  "status": "tested"
@@ -82368,14 +82429,14 @@
82368
82429
  "set": 17
82369
82430
  },
82370
82431
  "metadata": {
82371
- "purpose": "Answer 'what does the vendor ACTUALLY require to create a record here?' in one ZERO-wire call: the 92 campaign-decoded create entities — the live-proven required-field prefix, the structured blocker (the exact wall class), the exact vendor message text, the remedy, and the delete boundary — instead of rediscovering it one failed write at a time.",
82372
- "usage": "args[0] is the optional opts object: { resources?: string[] (the plan resource keys — narrows the row set; unknown key → typed RESOURCE_UNKNOWN carrying the 92-entity count + a pointer to autotask_catalog), kind?: CreateBlockerKind (narrows to one blocker kind — 'ok' | 'blind-reference' | 'blind-parent' | 'picklist-unexposed' | 'undocumented-ladder' | 'resource-role-pair' | 'delete-absent' | 'non-mutable' | 'unknown'; unknown kind → typed CONFIG_ERROR naming the valid kinds) }. Returns { zone, label, verifiedAt, rows: [{ resource, createOp, parentScoped, liveProvenPrefix (vendor-demand order), unproven, blocker { kind, message, referenceField?, remedy } | null, vendorEvidence (exact vendor text), deleteBoundary { available, note } }], counts: { total: 92, byKind } }. The counts describe the WHOLE pinned catalog (stable, drift-guarded) regardless of the filter; only rows narrows. ZERO vendor wire: the data is the plan-pinned campaign artifact (plan.zoneFacts.resources[<k>].createGuidance, artifact transfer — never a live write).",
82373
- "preferredWhen": "Before writing any create on a resource whose spec lists few/no required fields: check the catalog first (free) — the campaign already paid the discovery cost (461 classified write requests). For the served relationship facts of ONE resource (children + scoped ops + natural keys + the 12 hand-authored zone facts) use operations.relationshipMap.",
82432
+ "purpose": "Read static creation requirements, prior validation findings and unproven input guidance. This is not a live test of current-tenant capability, inventory or permissions.",
82433
+ "usage": "args[0] is optional { resources?: string[], kind?: CreateBlockerKind }. Returns rows and catalog-wide counts; filters narrow rows, not counts. Each row keeps observed requirements, unproven status, diagnostic blocker kind, evidence and delete boundary. Reference-tenant failures do not establish current API-user blindness or impossible creates. Read current field metadata and preview valid inputs.",
82434
+ "preferredWhen": "Consult before a create, together with current field metadata and a governed preview; never substitute static reference-tenant observations for a live permission or inventory check.",
82374
82435
  "related": [
82375
82436
  "operations.relationshipMap",
82376
82437
  "autotask_catalog"
82377
82438
  ],
82378
- "args": "args[0] is the optional opts object: { resources?: string[] (plan keys), kind?: CreateBlockerKind }. Zero wire — the answer is the served, drift-guarded campaign artifact (92 create entities, zone-labelled). Unknown resource → typed RESOURCE_UNKNOWN (count + autotask_catalog pointer); unknown kind → typed CONFIG_ERROR naming the valid kinds."
82439
+ "args": "Optional { resources?: string[], kind?: CreateBlockerKind }. No vendor requests; unknown resources produce RESOURCE_UNKNOWN and invalid blocker kinds produce CONFIG_ERROR."
82379
82440
  },
82380
82441
  "compact": "CreateGuidanceReport",
82381
82442
  "status": "tested"
@@ -82909,7 +82970,7 @@
82909
82970
  },
82910
82971
  "examples": [
82911
82972
  "await invoke(client, 'operations.relationshipMap', ['tickets'])",
82912
- "this zone validated: a run served the tickets entry ZERO wire (its 10 scoped children with scoped-op flags + the unowned-blind stamps). args (invoke form): the plan resource key string. Returns { resource, apiEntity, tier, parent, children [{ resource, parentField, scopedOps { create, query, update, delete }, specialOps }], naturalKeys, blindSurfaces, zoneFacts }. 'What can I attach to a ticket?' → children; 'what does creating a ticket note require?' → relationshipMap('ticket_notes').zoneFacts.createRequiredSet = [description, noteType, publish]. Unknown key → typed RESOURCE_UNKNOWN (carries the resource count + a pointer to autotask_catalog). ZERO vendor wire by construction — the data is the served registry artifact."
82973
+ "Returns SDK relationship coverage and static creation guidance without vendor traffic. Read the current tenant’s records and metadata before inferring visibility or availability."
82913
82974
  ],
82914
82975
  "permissions": "unknown",
82915
82976
  "pagination": {
@@ -82923,14 +82984,14 @@
82923
82984
  "set": 17
82924
82985
  },
82925
82986
  "metadata": {
82926
- "purpose": "Describe one resource's full relationship surface in a single ZERO-wire call: its parent, its children (with the scoped-op presence per child), its natural lookup keys, its pinned blind surfaces, and the zone-verified create required sets + quirks.",
82927
- "usage": "args[0] is the plan resource key (string, e.g. 'tickets'). Returns { resource, apiEntity, tier, workflowResource, parent, children: [{ resource, apiEntity, parentField, parentSegment, scopedOps: { create, query, update, delete }, specialOps, searchCovers }], naturalKeys: { hasSearch, searchCovers, findBy }, blindSurfaces, zoneFacts }. 'What can I attach to a ticket?' → children of 'tickets' (the 10 scoped child resources with their scoped-op flags); 'what does creating a ticket note require?' → relationshipMap('ticket_notes').zoneFacts.createRequiredSet = [description, noteType, publish]. Unknown key → typed RESOURCE_UNKNOWN (carries the resource count + a pointer to autotask_catalog — never a 128-key dump). ZERO vendor wire: the data is the plan-pinned registry artifact (the zone facts are the verified set — the zone label travels with them).",
82928
- "preferredWhen": "The first call when planning any multi-step composition (what exists under this resource, what a create requires, which surfaces are blind in this zone) — zero wire, so it is free to consult before every plan. For a live record, use the resource's read ops.",
82987
+ "purpose": "Describe a resource’s SDK-covered parent/child operations, lookup keys and static create guidance without a vendor call. Current-user visibility and tenant inventory require live reads.",
82988
+ "usage": "args[0] is the resource key. Returns the relationship map, operation coverage and static zoneFacts guidance. The legacy zoneFacts name records prior observations, not a zone capability selector or a current-tenant permission check. Unknown resources produce RESOURCE_UNKNOWN.",
82989
+ "preferredWhen": "Before composing related operations; use live read operations to establish the current tenant’s records and API-user visibility.",
82929
82990
  "related": [
82930
82991
  "operations.resolveAny",
82931
82992
  "autotask_catalog"
82932
82993
  ],
82933
- "args": "args[0] is the plan resource key (string, e.g. 'tickets', 'ticket_notes', 'companies'). Zero wire — the answer is the served, drift-guarded registry artifact (children + scoped ops + natural keys + blind surfaces + zone facts, zone-labelled). Unknown key → typed RESOURCE_UNKNOWN (count + autotask_catalog pointer)."
82994
+ "args": "args[0] is the resource key. No vendor request; query/get and current field metadata establish live visibility and required values."
82934
82995
  },
82935
82996
  "compact": "RelationshipResource",
82936
82997
  "status": "tested"