universal-mcp 0.1.13rc1__py3-none-any.whl → 0.1.13rc2__py3-none-any.whl

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 (99) hide show
  1. {universal_mcp-0.1.13rc1.dist-info → universal_mcp-0.1.13rc2.dist-info}/METADATA +1 -1
  2. universal_mcp-0.1.13rc2.dist-info/RECORD +38 -0
  3. universal_mcp/applications/ahrefs/README.md +0 -76
  4. universal_mcp/applications/ahrefs/__init__.py +0 -0
  5. universal_mcp/applications/ahrefs/app.py +0 -2291
  6. universal_mcp/applications/cal_com_v2/README.md +0 -175
  7. universal_mcp/applications/cal_com_v2/__init__.py +0 -0
  8. universal_mcp/applications/cal_com_v2/app.py +0 -5390
  9. universal_mcp/applications/calendly/README.md +0 -78
  10. universal_mcp/applications/calendly/__init__.py +0 -0
  11. universal_mcp/applications/calendly/app.py +0 -1195
  12. universal_mcp/applications/clickup/README.md +0 -160
  13. universal_mcp/applications/clickup/__init__.py +0 -0
  14. universal_mcp/applications/clickup/app.py +0 -5009
  15. universal_mcp/applications/coda/README.md +0 -133
  16. universal_mcp/applications/coda/__init__.py +0 -0
  17. universal_mcp/applications/coda/app.py +0 -3671
  18. universal_mcp/applications/curstdata/README.md +0 -50
  19. universal_mcp/applications/curstdata/__init__.py +0 -0
  20. universal_mcp/applications/curstdata/app.py +0 -551
  21. universal_mcp/applications/e2b/README.md +0 -37
  22. universal_mcp/applications/e2b/app.py +0 -65
  23. universal_mcp/applications/elevenlabs/README.md +0 -84
  24. universal_mcp/applications/elevenlabs/__init__.py +0 -0
  25. universal_mcp/applications/elevenlabs/app.py +0 -1402
  26. universal_mcp/applications/falai/README.md +0 -42
  27. universal_mcp/applications/falai/__init__.py +0 -0
  28. universal_mcp/applications/falai/app.py +0 -332
  29. universal_mcp/applications/figma/README.md +0 -74
  30. universal_mcp/applications/figma/__init__.py +0 -0
  31. universal_mcp/applications/figma/app.py +0 -1261
  32. universal_mcp/applications/firecrawl/README.md +0 -45
  33. universal_mcp/applications/firecrawl/app.py +0 -268
  34. universal_mcp/applications/github/README.md +0 -47
  35. universal_mcp/applications/github/app.py +0 -429
  36. universal_mcp/applications/gong/README.md +0 -88
  37. universal_mcp/applications/gong/__init__.py +0 -0
  38. universal_mcp/applications/gong/app.py +0 -2297
  39. universal_mcp/applications/google_calendar/app.py +0 -442
  40. universal_mcp/applications/google_docs/README.md +0 -40
  41. universal_mcp/applications/google_docs/app.py +0 -88
  42. universal_mcp/applications/google_drive/README.md +0 -44
  43. universal_mcp/applications/google_drive/app.py +0 -286
  44. universal_mcp/applications/google_mail/README.md +0 -47
  45. universal_mcp/applications/google_mail/app.py +0 -664
  46. universal_mcp/applications/google_sheet/README.md +0 -42
  47. universal_mcp/applications/google_sheet/app.py +0 -150
  48. universal_mcp/applications/heygen/README.md +0 -69
  49. universal_mcp/applications/heygen/__init__.py +0 -0
  50. universal_mcp/applications/heygen/app.py +0 -956
  51. universal_mcp/applications/mailchimp/README.md +0 -306
  52. universal_mcp/applications/mailchimp/__init__.py +0 -0
  53. universal_mcp/applications/mailchimp/app.py +0 -10937
  54. universal_mcp/applications/markitdown/app.py +0 -44
  55. universal_mcp/applications/neon/README.md +0 -99
  56. universal_mcp/applications/neon/__init__.py +0 -0
  57. universal_mcp/applications/neon/app.py +0 -1924
  58. universal_mcp/applications/notion/README.md +0 -55
  59. universal_mcp/applications/notion/__init__.py +0 -0
  60. universal_mcp/applications/notion/app.py +0 -527
  61. universal_mcp/applications/perplexity/README.md +0 -37
  62. universal_mcp/applications/perplexity/app.py +0 -65
  63. universal_mcp/applications/reddit/README.md +0 -45
  64. universal_mcp/applications/reddit/app.py +0 -379
  65. universal_mcp/applications/replicate/README.md +0 -65
  66. universal_mcp/applications/replicate/__init__.py +0 -0
  67. universal_mcp/applications/replicate/app.py +0 -980
  68. universal_mcp/applications/resend/README.md +0 -38
  69. universal_mcp/applications/resend/app.py +0 -37
  70. universal_mcp/applications/retell_ai/README.md +0 -46
  71. universal_mcp/applications/retell_ai/__init__.py +0 -0
  72. universal_mcp/applications/retell_ai/app.py +0 -333
  73. universal_mcp/applications/rocketlane/README.md +0 -42
  74. universal_mcp/applications/rocketlane/__init__.py +0 -0
  75. universal_mcp/applications/rocketlane/app.py +0 -194
  76. universal_mcp/applications/serpapi/README.md +0 -37
  77. universal_mcp/applications/serpapi/app.py +0 -73
  78. universal_mcp/applications/shortcut/README.md +0 -153
  79. universal_mcp/applications/shortcut/__init__.py +0 -0
  80. universal_mcp/applications/shortcut/app.py +0 -3880
  81. universal_mcp/applications/spotify/README.md +0 -116
  82. universal_mcp/applications/spotify/__init__.py +0 -0
  83. universal_mcp/applications/spotify/app.py +0 -2526
  84. universal_mcp/applications/supabase/README.md +0 -112
  85. universal_mcp/applications/supabase/__init__.py +0 -0
  86. universal_mcp/applications/supabase/app.py +0 -2970
  87. universal_mcp/applications/tavily/README.md +0 -38
  88. universal_mcp/applications/tavily/app.py +0 -51
  89. universal_mcp/applications/wrike/README.md +0 -71
  90. universal_mcp/applications/wrike/__init__.py +0 -0
  91. universal_mcp/applications/wrike/app.py +0 -1372
  92. universal_mcp/applications/youtube/README.md +0 -82
  93. universal_mcp/applications/youtube/__init__.py +0 -0
  94. universal_mcp/applications/youtube/app.py +0 -1428
  95. universal_mcp/applications/zenquotes/README.md +0 -37
  96. universal_mcp/applications/zenquotes/app.py +0 -31
  97. universal_mcp-0.1.13rc1.dist-info/RECORD +0 -132
  98. {universal_mcp-0.1.13rc1.dist-info → universal_mcp-0.1.13rc2.dist-info}/WHEEL +0 -0
  99. {universal_mcp-0.1.13rc1.dist-info → universal_mcp-0.1.13rc2.dist-info}/entry_points.txt +0 -0
@@ -1,3880 +0,0 @@
1
- from typing import Any
2
-
3
- from universal_mcp.applications import APIApplication
4
- from universal_mcp.integrations import Integration
5
-
6
-
7
- class ShortcutApp(APIApplication):
8
- def __init__(self, integration: Integration = None, **kwargs) -> None:
9
- super().__init__(name='shortcut', integration=integration, **kwargs)
10
- self.base_url = "https://api.app.shortcut.com"
11
-
12
- def _get_headers(self) -> dict[str, Any]:
13
- api_key = self.integration.get_credentials().get("api_key")
14
- return {
15
- "Shortcut-Token": f"{api_key}",
16
- "Content-Type": "application/json",
17
- }
18
-
19
- def list_categories(self, ) -> list[Any]:
20
- """
21
- Retrieves a list of categories from the API.
22
-
23
- Returns:
24
- A list of category objects retrieved from the API endpoint.
25
-
26
- Raises:
27
- HTTPError: If the HTTP request returns a non-successful status code.
28
-
29
- Tags:
30
- list, categories, api, get, important
31
- """
32
- url = f"{self.base_url}/api/v3/categories"
33
- query_params = {}
34
- response = self._get(url, params=query_params)
35
- response.raise_for_status()
36
- return response.json()
37
-
38
- def create_category(self, name, color=None, external_id=None, type=None) -> dict[str, Any]:
39
- """
40
- Creates a new category with the specified parameters.
41
-
42
- Args:
43
- name: Required string representing the name of the category.
44
- color: Optional string representing the color of the category.
45
- external_id: Optional identifier for external reference.
46
- type: Optional string indicating the category type.
47
-
48
- Returns:
49
- Dictionary containing the created category details as returned by the API.
50
-
51
- Raises:
52
- ValueError: Raised when the required parameter 'name' is None.
53
- HTTPError: Raised when the HTTP request fails.
54
-
55
- Tags:
56
- create, category, management,
57
- """
58
- if name is None:
59
- raise ValueError("Missing required parameter 'name'")
60
- request_body = {
61
- 'name': name,
62
- 'color': color,
63
- 'external_id': external_id,
64
- 'type': type,
65
- }
66
- request_body = {k: v for k, v in request_body.items() if v is not None}
67
- url = f"{self.base_url}/api/v3/categories"
68
- query_params = {}
69
- response = self._post(url, data=request_body, params=query_params)
70
- response.raise_for_status()
71
- return response.json()
72
-
73
- def get_category(self, category_public_id) -> dict[str, Any]:
74
- """
75
- Fetches a category by its public ID.
76
-
77
- Args:
78
- category_public_id: The public ID of the category to fetch.
79
-
80
- Returns:
81
- A dictionary containing category details.
82
-
83
- Raises:
84
- ValueError: Raised when the required 'category_public_id' is missing.
85
-
86
- Tags:
87
- fetch, category, request,
88
- """
89
- if category_public_id is None:
90
- raise ValueError("Missing required parameter 'category-public-id'")
91
- url = f"{self.base_url}/api/v3/categories/{category_public_id}"
92
- query_params = {}
93
- response = self._get(url, params=query_params)
94
- response.raise_for_status()
95
- return response.json()
96
-
97
- def update_category(self, category_public_id, name=None, color=None, archived=None) -> dict[str, Any]:
98
- """
99
- Updates a category with the specified attributes.
100
-
101
- Args:
102
- category_public_id: The unique public identifier of the category to update.
103
- name: Optional; The new name for the category.
104
- color: Optional; The new color for the category.
105
- archived: Optional; Boolean indicating whether the category should be archived.
106
-
107
- Returns:
108
- A dictionary containing the updated category information.
109
-
110
- Raises:
111
- ValueError: When category_public_id is None.
112
- HTTPError: When the API request fails.
113
-
114
- Tags:
115
- update, category, management,
116
- """
117
- if category_public_id is None:
118
- raise ValueError("Missing required parameter 'category-public-id'")
119
- request_body = {
120
- 'name': name,
121
- 'color': color,
122
- 'archived': archived,
123
- }
124
- request_body = {k: v for k, v in request_body.items() if v is not None}
125
- url = f"{self.base_url}/api/v3/categories/{category_public_id}"
126
- query_params = {}
127
- response = self._put(url, data=request_body, params=query_params)
128
- response.raise_for_status()
129
- return response.json()
130
-
131
- def delete_category(self, category_public_id) -> Any:
132
- """
133
- Deletes a category by its public ID.
134
-
135
- Args:
136
- category_public_id: The public ID of the category to be deleted.
137
-
138
- Returns:
139
- JSON response from the server after deletion.
140
-
141
- Raises:
142
- ValueError: Raised if the 'category_public_id' is None.
143
- requests.HTTPError: Raised if the HTTP request fails (e.g., server errors).
144
-
145
- Tags:
146
- delete, category-management,
147
- """
148
- if category_public_id is None:
149
- raise ValueError("Missing required parameter 'category-public-id'")
150
- url = f"{self.base_url}/api/v3/categories/{category_public_id}"
151
- query_params = {}
152
- response = self._delete(url, params=query_params)
153
- response.raise_for_status()
154
- return response.json()
155
-
156
- def list_category_milestones(self, category_public_id) -> list[Any]:
157
- """
158
- Lists all milestones associated with a specified category.
159
-
160
- Args:
161
- category_public_id: The unique public identifier of the category for which to retrieve milestones.
162
-
163
- Returns:
164
- A list of dictionaries containing milestone data for the specified category.
165
-
166
- Raises:
167
- ValueError: When the required parameter 'category_public_id' is None.
168
- HTTPError: When the API request fails.
169
-
170
- Tags:
171
- list, milestones, category, api, retrieve,
172
- """
173
- if category_public_id is None:
174
- raise ValueError("Missing required parameter 'category-public-id'")
175
- url = f"{self.base_url}/api/v3/categories/{category_public_id}/milestones"
176
- query_params = {}
177
- response = self._get(url, params=query_params)
178
- response.raise_for_status()
179
- return response.json()
180
-
181
- def list_category_objectives(self, category_public_id) -> list[Any]:
182
- """
183
- Fetches and lists objectives for a given category based on its public ID.
184
-
185
- Args:
186
- category_public_id: The public ID of the category for which to retrieve objectives.
187
-
188
- Returns:
189
- A list of objectives for the specified category.
190
-
191
- Raises:
192
- ValueError: Raised if the 'category_public_id' is missing.
193
-
194
- Tags:
195
- list, objectives, category-management,
196
- """
197
- if category_public_id is None:
198
- raise ValueError("Missing required parameter 'category-public-id'")
199
- url = f"{self.base_url}/api/v3/categories/{category_public_id}/objectives"
200
- query_params = {}
201
- response = self._get(url, params=query_params)
202
- response.raise_for_status()
203
- return response.json()
204
-
205
- def list_custom_fields(self, ) -> list[Any]:
206
- """
207
- Retrieves a list of custom fields from the API.
208
-
209
- Returns:
210
- A list of dictionaries containing custom field information.
211
-
212
- Raises:
213
- HTTPError: If the API request fails or returns a non-success status code.
214
-
215
- Tags:
216
- list, custom-fields, api,
217
- """
218
- url = f"{self.base_url}/api/v3/custom-fields"
219
- query_params = {}
220
- response = self._get(url, params=query_params)
221
- response.raise_for_status()
222
- return response.json()
223
-
224
- def get_custom_field(self, custom_field_public_id) -> dict[str, Any]:
225
- """
226
- Retrieves a custom field by its public ID.
227
-
228
- Args:
229
- custom_field_public_id: The public ID of the custom field to retrieve.
230
-
231
- Returns:
232
- A dictionary containing the custom field data.
233
-
234
- Raises:
235
- ValueError: When the required custom_field_public_id parameter is None.
236
- HTTPError: When the API request fails or returns a non-success status code.
237
-
238
- Tags:
239
- get, retrieve, api, custom-field,
240
- """
241
- if custom_field_public_id is None:
242
- raise ValueError("Missing required parameter 'custom-field-public-id'")
243
- url = f"{self.base_url}/api/v3/custom-fields/{custom_field_public_id}"
244
- query_params = {}
245
- response = self._get(url, params=query_params)
246
- response.raise_for_status()
247
- return response.json()
248
-
249
- def update_custom_field(self, custom_field_public_id, enabled=None, name=None, values=None, icon_set_identifier=None, description=None, before_id=None, after_id=None) -> dict[str, Any]:
250
- """
251
- Updates an existing custom field's attributes with the provided values.
252
-
253
- Args:
254
- custom_field_public_id: The public identifier of the custom field to update.
255
- enabled: Optional; whether the custom field should be enabled.
256
- name: Optional; the new name for the custom field.
257
- values: Optional; a list of new values for the custom field, if applicable.
258
- icon_set_identifier: Optional; the identifier for the icon set to associate with the custom field.
259
- description: Optional; a new description for the custom field.
260
- before_id: Optional; if specified, places the field before this custom field ID in display order.
261
- after_id: Optional; if specified, places the field after this custom field ID in display order.
262
-
263
- Returns:
264
- A dictionary containing the updated custom field information as returned by the API.
265
-
266
- Raises:
267
- ValueError: If 'custom_field_public_id' is None.
268
- requests.HTTPError: If the HTTP request fails, e.g., due to network issues or invalid parameters.
269
-
270
- Tags:
271
- update, custom-field, management, api,
272
- """
273
- if custom_field_public_id is None:
274
- raise ValueError("Missing required parameter 'custom-field-public-id'")
275
- request_body = {
276
- 'enabled': enabled,
277
- 'name': name,
278
- 'values': values,
279
- 'icon_set_identifier': icon_set_identifier,
280
- 'description': description,
281
- 'before_id': before_id,
282
- 'after_id': after_id,
283
- }
284
- request_body = {k: v for k, v in request_body.items() if v is not None}
285
- url = f"{self.base_url}/api/v3/custom-fields/{custom_field_public_id}"
286
- query_params = {}
287
- response = self._put(url, data=request_body, params=query_params)
288
- response.raise_for_status()
289
- return response.json()
290
-
291
- def delete_custom_field(self, custom_field_public_id) -> Any:
292
- """
293
- Deletes a custom field specified by its public identifier.
294
-
295
- Args:
296
- custom_field_public_id: The public identifier of the custom field to delete.
297
-
298
- Returns:
299
- A dictionary representing the JSON response from the API after deleting the custom field.
300
-
301
- Raises:
302
- ValueError: If 'custom_field_public_id' is None.
303
- requests.HTTPError: If the HTTP request to delete the custom field fails.
304
-
305
- Tags:
306
- delete, custom-field, management, api,
307
- """
308
- if custom_field_public_id is None:
309
- raise ValueError("Missing required parameter 'custom-field-public-id'")
310
- url = f"{self.base_url}/api/v3/custom-fields/{custom_field_public_id}"
311
- query_params = {}
312
- response = self._delete(url, params=query_params)
313
- response.raise_for_status()
314
- return response.json()
315
-
316
- def list_entity_templates(self, ) -> list[Any]:
317
- """
318
- Retrieves a list of entity templates from an API endpoint.
319
-
320
- Args:
321
- None: This function takes no arguments.
322
-
323
- Returns:
324
- A list of JSON objects representing entity templates.
325
-
326
- Raises:
327
- requests.HTTPError: Raised if the HTTP request returns an unsuccessful status code.
328
-
329
- Tags:
330
- list, entity-templates, api-call, management,
331
- """
332
- url = f"{self.base_url}/api/v3/entity-templates"
333
- query_params = {}
334
- response = self._get(url, params=query_params)
335
- response.raise_for_status()
336
- return response.json()
337
-
338
- def create_entity_template(self, name, story_contents, author_id=None) -> dict[str, Any]:
339
- """
340
- Creates an entity template with the provided name, story contents, and optional author ID.
341
-
342
- Args:
343
- name: Required string representing the name of the entity template.
344
- story_contents: Required object containing the story contents for the entity template.
345
- author_id: Optional string identifying the author of the entity template.
346
-
347
- Returns:
348
- A dictionary containing the created entity template data from the API response.
349
-
350
- Raises:
351
- ValueError: Raised when the required parameters 'name' or 'story_contents' are None.
352
- HTTPError: Raised when the API request fails.
353
-
354
- Tags:
355
- create, template, entity, api,
356
- """
357
- if name is None:
358
- raise ValueError("Missing required parameter 'name'")
359
- if story_contents is None:
360
- raise ValueError("Missing required parameter 'story_contents'")
361
- request_body = {
362
- 'name': name,
363
- 'author_id': author_id,
364
- 'story_contents': story_contents,
365
- }
366
- request_body = {k: v for k, v in request_body.items() if v is not None}
367
- url = f"{self.base_url}/api/v3/entity-templates"
368
- query_params = {}
369
- response = self._post(url, data=request_body, params=query_params)
370
- response.raise_for_status()
371
- return response.json()
372
-
373
- def disable_story_templates(self, ) -> Any:
374
- """
375
- Disables story entity templates by sending a PUT request to the API endpoint.
376
-
377
- Args:
378
- None: This function takes no arguments
379
-
380
- Returns:
381
- The parsed JSON response from the API indicating the result of the disable operation.
382
-
383
- Raises:
384
- HTTPError: If the HTTP request to disable the story templates fails or returns an error status.
385
-
386
- Tags:
387
- disable, story-templates, api, management,
388
- """
389
- url = f"{self.base_url}/api/v3/entity-templates/disable"
390
- query_params = {}
391
- response = self._put(url, data={}, params=query_params)
392
- response.raise_for_status()
393
- return response.json()
394
-
395
- def enable_story_templates(self, ) -> Any:
396
- """
397
- Enables story templates by making a PUT request to the entity-templates endpoint.
398
-
399
- Returns:
400
- The JSON response from enabling story templates.
401
-
402
- Raises:
403
- requests.HTTPError: Raised if the HTTP request returns an unsuccessful status code.
404
-
405
- Tags:
406
- enable, templates, management, http-put,
407
- """
408
- url = f"{self.base_url}/api/v3/entity-templates/enable"
409
- query_params = {}
410
- response = self._put(url, data={}, params=query_params)
411
- response.raise_for_status()
412
- return response.json()
413
-
414
- def get_entity_template(self, entity_template_public_id) -> dict[str, Any]:
415
- """
416
- Retrieves a specific entity template by its public ID.
417
-
418
- Args:
419
- entity_template_public_id: The public identifier of the entity template to retrieve.
420
-
421
- Returns:
422
- A dictionary containing the entity template data.
423
-
424
- Raises:
425
- ValueError: Raised when the required entity_template_public_id parameter is None.
426
- HTTPError: Raised when the HTTP request fails.
427
-
428
- Tags:
429
- get, retrieve, entity, template, api,
430
- """
431
- if entity_template_public_id is None:
432
- raise ValueError("Missing required parameter 'entity-template-public-id'")
433
- url = f"{self.base_url}/api/v3/entity-templates/{entity_template_public_id}"
434
- query_params = {}
435
- response = self._get(url, params=query_params)
436
- response.raise_for_status()
437
- return response.json()
438
-
439
- def update_entity_template(self, entity_template_public_id, name=None, story_contents=None) -> dict[str, Any]:
440
- """
441
- Updates an entity template using the provided public ID, optionally setting its name and story contents.
442
-
443
- Args:
444
- entity_template_public_id: The public ID of the entity template to be updated
445
- name: Optional name for the entity template
446
- story_contents: Optional story contents for the entity template
447
-
448
- Returns:
449
- A dictionary containing the updated entity template details
450
-
451
- Raises:
452
- ValueError: Raised when the required 'entity_template_public_id' parameter is missing.
453
-
454
- Tags:
455
- update, entity-template, management,
456
- """
457
- if entity_template_public_id is None:
458
- raise ValueError("Missing required parameter 'entity-template-public-id'")
459
- request_body = {
460
- 'name': name,
461
- 'story_contents': story_contents,
462
- }
463
- request_body = {k: v for k, v in request_body.items() if v is not None}
464
- url = f"{self.base_url}/api/v3/entity-templates/{entity_template_public_id}"
465
- query_params = {}
466
- response = self._put(url, data=request_body, params=query_params)
467
- response.raise_for_status()
468
- return response.json()
469
-
470
- def delete_entity_template(self, entity_template_public_id) -> Any:
471
- """
472
- Deletes an entity template by its public ID.
473
-
474
- Args:
475
- entity_template_public_id: The public ID of the entity template to delete.
476
-
477
- Returns:
478
- The JSON response from the server after deletion.
479
-
480
- Raises:
481
- ValueError: Raised if the entity template public ID is missing.
482
-
483
- Tags:
484
- delete, entity-management,
485
- """
486
- if entity_template_public_id is None:
487
- raise ValueError("Missing required parameter 'entity-template-public-id'")
488
- url = f"{self.base_url}/api/v3/entity-templates/{entity_template_public_id}"
489
- query_params = {}
490
- response = self._delete(url, params=query_params)
491
- response.raise_for_status()
492
- return response.json()
493
-
494
- def get_epic_workflow(self, ) -> dict[str, Any]:
495
- """
496
- Retrieves the epic workflow configuration from the API.
497
-
498
- Returns:
499
- A dictionary containing the epic workflow configuration data from the API response.
500
-
501
- Raises:
502
- HTTPError: Raised when the API request fails, as triggered by raise_for_status().
503
-
504
- Tags:
505
- get, retrieve, api, workflow, epic, configuration,
506
- """
507
- url = f"{self.base_url}/api/v3/epic-workflow"
508
- query_params = {}
509
- response = self._get(url, params=query_params)
510
- response.raise_for_status()
511
- return response.json()
512
-
513
- def list_epics(self, includes_description=None) -> list[Any]:
514
- """
515
- Fetches a list of epics from the API.
516
-
517
- Args:
518
- includes_description: Optional flag to include the description of epics in the response. Defaults to None.
519
-
520
- Returns:
521
- A list of epics.
522
-
523
- Raises:
524
- requests.exceptions.HTTPError: Raised if the HTTP request returns an unsuccessful status code.
525
-
526
- Tags:
527
- list, epics, async-job, management, important
528
- """
529
- url = f"{self.base_url}/api/v3/epics"
530
- query_params = {k: v for k, v in [('includes_description', includes_description)] if v is not None}
531
- response = self._get(url, params=query_params)
532
- response.raise_for_status()
533
- return response.json()
534
-
535
- def create_epic(self, name, description=None, labels=None, completed_at_override=None, objective_ids=None, planned_start_date=None, state=None, milestone_id=None, requested_by_id=None, epic_state_id=None, started_at_override=None, group_id=None, updated_at=None, follower_ids=None, group_ids=None, owner_ids=None, external_id=None, deadline=None, created_at=None) -> dict[str, Any]:
536
- """
537
- Creates a new epic in the project management system with the specified properties.
538
-
539
- Args:
540
- name: The name of the epic. Required parameter.
541
- description: A detailed description of the epic.
542
- labels: Tags or categories associated with the epic.
543
- completed_at_override: Custom completion date for the epic.
544
- objective_ids: List of objective IDs associated with this epic.
545
- planned_start_date: The date when work on the epic is planned to start.
546
- state: Current state of the epic (e.g., 'in_progress', 'completed').
547
- milestone_id: ID of the milestone associated with this epic.
548
- requested_by_id: ID of the user who requested the epic.
549
- epic_state_id: ID representing the custom workflow state of the epic.
550
- started_at_override: Custom start date for the epic.
551
- group_id: ID of the primary group associated with the epic.
552
- updated_at: Timestamp when the epic was last updated.
553
- follower_ids: List of user IDs following this epic.
554
- group_ids: List of group IDs associated with this epic.
555
- owner_ids: List of user IDs who own this epic.
556
- external_id: External identifier for integration with other systems.
557
- deadline: Due date for the epic completion.
558
- created_at: Timestamp when the epic was created.
559
-
560
- Returns:
561
- A dictionary containing the created epic data as returned by the API.
562
-
563
- Raises:
564
- ValueError: Raised when the required parameter 'name' is not provided.
565
- HTTPError: Raised when the API request fails.
566
-
567
- Tags:
568
- create, epic, project-management, api,
569
- """
570
- if name is None:
571
- raise ValueError("Missing required parameter 'name'")
572
- request_body = {
573
- 'description': description,
574
- 'labels': labels,
575
- 'completed_at_override': completed_at_override,
576
- 'objective_ids': objective_ids,
577
- 'name': name,
578
- 'planned_start_date': planned_start_date,
579
- 'state': state,
580
- 'milestone_id': milestone_id,
581
- 'requested_by_id': requested_by_id,
582
- 'epic_state_id': epic_state_id,
583
- 'started_at_override': started_at_override,
584
- 'group_id': group_id,
585
- 'updated_at': updated_at,
586
- 'follower_ids': follower_ids,
587
- 'group_ids': group_ids,
588
- 'owner_ids': owner_ids,
589
- 'external_id': external_id,
590
- 'deadline': deadline,
591
- 'created_at': created_at,
592
- }
593
- request_body = {k: v for k, v in request_body.items() if v is not None}
594
- url = f"{self.base_url}/api/v3/epics"
595
- query_params = {}
596
- response = self._post(url, data=request_body, params=query_params)
597
- response.raise_for_status()
598
- return response.json()
599
-
600
- def get_epic(self, epic_public_id) -> dict[str, Any]:
601
- """
602
- Fetches an epic by its public ID
603
-
604
- Args:
605
- epic_public_id: The public ID of the epic to retrieve
606
-
607
- Returns:
608
- A dictionary containing the details of the retrieved epic
609
-
610
- Raises:
611
- ValueError: Raised if the epic_public_id is missing
612
-
613
- Tags:
614
- fetch, epic, management,
615
- """
616
- if epic_public_id is None:
617
- raise ValueError("Missing required parameter 'epic-public-id'")
618
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}"
619
- query_params = {}
620
- response = self._get(url, params=query_params)
621
- response.raise_for_status()
622
- return response.json()
623
-
624
- def update_epic(self, epic_public_id, description=None, archived=None, labels=None, completed_at_override=None, objective_ids=None, name=None, planned_start_date=None, state=None, milestone_id=None, requested_by_id=None, epic_state_id=None, started_at_override=None, group_id=None, follower_ids=None, group_ids=None, owner_ids=None, external_id=None, before_id=None, after_id=None, deadline=None) -> dict[str, Any]:
625
- """
626
- Updates an epic with the provided details.
627
-
628
- Args:
629
- epic_public_id: The public ID of the epic to be updated.
630
- description: Optional description of the epic.
631
- archived: Optional flag indicating if the epic is archived.
632
- labels: Optional list of labels for the epic.
633
- completed_at_override: Optional override date for when the epic was completed.
634
- objective_ids: Optional list of objective IDs.
635
- name: Optional new name for the epic.
636
- planned_start_date: Optional planned start date.
637
- state: Optional state of the epic (e.g., 'to-do', 'in-progress', 'done').
638
- milestone_id: Optional ID of a milestone associated with the epic.
639
- requested_by_id: Optional ID of the user who requested the epic.
640
- epic_state_id: Optional ID of the epic state.
641
- started_at_override: Optional override date for when the epic started.
642
- group_id: Optional ID of a group associated with the epic.
643
- follower_ids: Optional list of follower IDs.
644
- group_ids: Optional list of group IDs.
645
- owner_ids: Optional list of owner IDs.
646
- external_id: Optional external ID for the epic.
647
- before_id: Optional placement parameter indicating where the epic should be placed relative to other epics.
648
- after_id: Optional placement parameter for ordering the epic.
649
- deadline: Optional deadline for the epic.
650
-
651
- Returns:
652
- A dictionary containing the updated epic details.
653
-
654
- Raises:
655
- ValueError: Raised if the required 'epic_public_id' parameter is missing.
656
- requests.exceptions.HTTPError: Raised if there are issues with the HTTP request.
657
-
658
- Tags:
659
- update, epic, management, , async-job
660
- """
661
- if epic_public_id is None:
662
- raise ValueError("Missing required parameter 'epic-public-id'")
663
- request_body = {
664
- 'description': description,
665
- 'archived': archived,
666
- 'labels': labels,
667
- 'completed_at_override': completed_at_override,
668
- 'objective_ids': objective_ids,
669
- 'name': name,
670
- 'planned_start_date': planned_start_date,
671
- 'state': state,
672
- 'milestone_id': milestone_id,
673
- 'requested_by_id': requested_by_id,
674
- 'epic_state_id': epic_state_id,
675
- 'started_at_override': started_at_override,
676
- 'group_id': group_id,
677
- 'follower_ids': follower_ids,
678
- 'group_ids': group_ids,
679
- 'owner_ids': owner_ids,
680
- 'external_id': external_id,
681
- 'before_id': before_id,
682
- 'after_id': after_id,
683
- 'deadline': deadline,
684
- }
685
- request_body = {k: v for k, v in request_body.items() if v is not None}
686
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}"
687
- query_params = {}
688
- response = self._put(url, data=request_body, params=query_params)
689
- response.raise_for_status()
690
- return response.json()
691
-
692
- def delete_epic(self, epic_public_id) -> Any:
693
- """
694
- Deletes an epic by its public ID.
695
-
696
- Args:
697
- epic_public_id: The public identifier of the epic to be deleted.
698
-
699
- Returns:
700
- The JSON response from the API after successfully deleting the epic.
701
-
702
- Raises:
703
- ValueError: When the required parameter 'epic-public-id' is None.
704
- HTTPError: When the HTTP request returns an unsuccessful status code.
705
-
706
- Tags:
707
- delete, epic, api, management,
708
- """
709
- if epic_public_id is None:
710
- raise ValueError("Missing required parameter 'epic-public-id'")
711
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}"
712
- query_params = {}
713
- response = self._delete(url, params=query_params)
714
- response.raise_for_status()
715
- return response.json()
716
-
717
- def list_epic_comments(self, epic_public_id) -> list[Any]:
718
- """
719
- Retrieves a list of comments for a specified epic.
720
-
721
- Args:
722
- epic_public_id: The public identifier of the epic whose comments are to be retrieved.
723
-
724
- Returns:
725
- A list of comment objects associated with the specified epic.
726
-
727
- Raises:
728
- ValueError: When the required epic_public_id parameter is None.
729
- HTTPError: When the HTTP request to retrieve comments fails.
730
-
731
- Tags:
732
- list, retrieve, comments, epic, api
733
- """
734
- if epic_public_id is None:
735
- raise ValueError("Missing required parameter 'epic-public-id'")
736
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/comments"
737
- query_params = {}
738
- response = self._get(url, params=query_params)
739
- response.raise_for_status()
740
- return response.json()
741
-
742
- def create_epic_comment(self, epic_public_id, text, author_id=None, created_at=None, updated_at=None, external_id=None) -> dict[str, Any]:
743
- """
744
- Creates a comment on an epic with the specified details.
745
-
746
- Args:
747
- epic_public_id: The public identifier of the epic to which the comment will be added.
748
- text: The content of the comment to be created.
749
- author_id: Optional. The identifier of the author creating the comment.
750
- created_at: Optional. The timestamp when the comment was created.
751
- updated_at: Optional. The timestamp when the comment was last updated.
752
- external_id: Optional. An external identifier for the comment.
753
-
754
- Returns:
755
- A dictionary containing the created comment's details.
756
-
757
- Raises:
758
- ValueError: Raised when either epic_public_id or text is None.
759
-
760
- Tags:
761
- create, comment, epic, api,
762
- """
763
- if epic_public_id is None:
764
- raise ValueError("Missing required parameter 'epic-public-id'")
765
- if text is None:
766
- raise ValueError("Missing required parameter 'text'")
767
- request_body = {
768
- 'text': text,
769
- 'author_id': author_id,
770
- 'created_at': created_at,
771
- 'updated_at': updated_at,
772
- 'external_id': external_id,
773
- }
774
- request_body = {k: v for k, v in request_body.items() if v is not None}
775
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/comments"
776
- query_params = {}
777
- response = self._post(url, data=request_body, params=query_params)
778
- response.raise_for_status()
779
- return response.json()
780
-
781
- def get_epic_comment(self, epic_public_id, comment_public_id) -> dict[str, Any]:
782
- """
783
- Retrieves a specific comment from an epic by their respective public IDs.
784
-
785
- Args:
786
- epic_public_id: The public identifier of the epic containing the comment.
787
- comment_public_id: The public identifier of the comment to retrieve.
788
-
789
- Returns:
790
- A dictionary containing the comment data from the API response.
791
-
792
- Raises:
793
- ValueError: When either epic_public_id or comment_public_id is None.
794
- HTTPError: When the API request fails.
795
-
796
- Tags:
797
- get, retrieve, epic, comment, api
798
- """
799
- if epic_public_id is None:
800
- raise ValueError("Missing required parameter 'epic-public-id'")
801
- if comment_public_id is None:
802
- raise ValueError("Missing required parameter 'comment-public-id'")
803
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/comments/{comment_public_id}"
804
- query_params = {}
805
- response = self._get(url, params=query_params)
806
- response.raise_for_status()
807
- return response.json()
808
-
809
- def update_epic_comment(self, epic_public_id, comment_public_id, text) -> dict[str, Any]:
810
- """
811
- Updates the text of an existing comment on a specified epic.
812
-
813
- Args:
814
- epic_public_id: str. The public identifier of the epic containing the comment to update.
815
- comment_public_id: str. The public identifier of the comment to update.
816
- text: str. The new text content for the comment.
817
-
818
- Returns:
819
- dict[str, Any]: A dictionary representing the updated comment resource as returned by the API.
820
-
821
- Raises:
822
- ValueError: Raised if any of the required parameters ('epic_public_id', 'comment_public_id', or 'text') are None.
823
- HTTPError: Raised if the HTTP request to update the comment fails (non-2xx response).
824
-
825
- Tags:
826
- update, comment, epic, management, api,
827
- """
828
- if epic_public_id is None:
829
- raise ValueError("Missing required parameter 'epic-public-id'")
830
- if comment_public_id is None:
831
- raise ValueError("Missing required parameter 'comment-public-id'")
832
- if text is None:
833
- raise ValueError("Missing required parameter 'text'")
834
- request_body = {
835
- 'text': text,
836
- }
837
- request_body = {k: v for k, v in request_body.items() if v is not None}
838
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/comments/{comment_public_id}"
839
- query_params = {}
840
- response = self._put(url, data=request_body, params=query_params)
841
- response.raise_for_status()
842
- return response.json()
843
-
844
- def create_epic_comment_comment(self, epic_public_id, comment_public_id, text, author_id=None, created_at=None, updated_at=None, external_id=None) -> dict[str, Any]:
845
- """
846
- Creates a reply to an existing comment on a specified epic, sending the reply to the backend API and returning the created comment data.
847
-
848
- Args:
849
- epic_public_id: str. The public identifier for the epic (required).
850
- comment_public_id: str. The public identifier for the parent comment being replied to (required).
851
- text: str. The content of the reply comment (required).
852
- author_id: Optional[str]. The public identifier for the author of the reply.
853
- created_at: Optional[str]. The creation timestamp of the comment, in ISO 8601 format.
854
- updated_at: Optional[str]. The last updated timestamp of the comment, in ISO 8601 format.
855
- external_id: Optional[str]. An external system identifier for the comment.
856
-
857
- Returns:
858
- dict[str, Any]: The created comment object as returned by the API.
859
-
860
- Raises:
861
- ValueError: If any of 'epic_public_id', 'comment_public_id', or 'text' is None.
862
- requests.HTTPError: If the API response status indicates an HTTP error.
863
-
864
- Tags:
865
- create, comment, epic, reply, api,
866
- """
867
- if epic_public_id is None:
868
- raise ValueError("Missing required parameter 'epic-public-id'")
869
- if comment_public_id is None:
870
- raise ValueError("Missing required parameter 'comment-public-id'")
871
- if text is None:
872
- raise ValueError("Missing required parameter 'text'")
873
- request_body = {
874
- 'text': text,
875
- 'author_id': author_id,
876
- 'created_at': created_at,
877
- 'updated_at': updated_at,
878
- 'external_id': external_id,
879
- }
880
- request_body = {k: v for k, v in request_body.items() if v is not None}
881
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/comments/{comment_public_id}"
882
- query_params = {}
883
- response = self._post(url, data=request_body, params=query_params)
884
- response.raise_for_status()
885
- return response.json()
886
-
887
- def delete_epic_comment(self, epic_public_id, comment_public_id) -> Any:
888
- """
889
- Deletes a specific comment from an epic using its public identifiers.
890
-
891
- Args:
892
- epic_public_id: The public identifier of the epic containing the comment to delete.
893
- comment_public_id: The public identifier of the comment to be deleted.
894
-
895
- Returns:
896
- The server's response as a parsed JSON object, typically containing details of the deletion result.
897
-
898
- Raises:
899
- ValueError: Raised if either 'epic_public_id' or 'comment_public_id' is None.
900
- requests.HTTPError: Raised if the HTTP request to delete the comment fails.
901
-
902
- Tags:
903
- delete, comment-management, epic, api,
904
- """
905
- if epic_public_id is None:
906
- raise ValueError("Missing required parameter 'epic-public-id'")
907
- if comment_public_id is None:
908
- raise ValueError("Missing required parameter 'comment-public-id'")
909
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/comments/{comment_public_id}"
910
- query_params = {}
911
- response = self._delete(url, params=query_params)
912
- response.raise_for_status()
913
- return response.json()
914
-
915
- def list_epic_stories(self, epic_public_id, includes_description=None) -> list[Any]:
916
- """
917
- Retrieves a list of stories associated with a specific epic.
918
-
919
- Args:
920
- epic_public_id: The unique identifier of the epic whose stories are to be retrieved.
921
- includes_description: Boolean flag indicating whether to include story descriptions in the response. If None, descriptions are not included.
922
-
923
- Returns:
924
- A list of story objects associated with the specified epic, with each story represented as a dictionary.
925
-
926
- Raises:
927
- ValueError: Raised when the required parameter 'epic_public_id' is None.
928
- HTTPError: Raised when the HTTP request to the API endpoint fails.
929
-
930
- Tags:
931
- list, retrieve, epic, stories, management,
932
- """
933
- if epic_public_id is None:
934
- raise ValueError("Missing required parameter 'epic-public-id'")
935
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/stories"
936
- query_params = {k: v for k, v in [('includes_description', includes_description)] if v is not None}
937
- response = self._get(url, params=query_params)
938
- response.raise_for_status()
939
- return response.json()
940
-
941
- def unlink_productboard_from_epic(self, epic_public_id) -> Any:
942
- """
943
- Unlinks a ProductBoard integration from an epic in the system.
944
-
945
- Args:
946
- epic_public_id: The public identifier of the epic to unlink from ProductBoard.
947
-
948
- Returns:
949
- JSON response containing the result of the unlink operation.
950
-
951
- Raises:
952
- ValueError: Raised when the required epic_public_id parameter is None.
953
- HTTPError: Raised when the API request fails or returns an error status code.
954
-
955
- Tags:
956
- unlink, epic, productboard, integration, api
957
- """
958
- if epic_public_id is None:
959
- raise ValueError("Missing required parameter 'epic-public-id'")
960
- url = f"{self.base_url}/api/v3/epics/{epic_public_id}/unlink-productboard"
961
- query_params = {}
962
- response = self._post(url, data={}, params=query_params)
963
- response.raise_for_status()
964
- return response.json()
965
-
966
- def get_external_link_stories(self, external_link) -> list[Any]:
967
- """
968
- Retrieves stories associated with an external link.
969
-
970
- Args:
971
- external_link: The URL of the external link to query for associated stories. Must not be None.
972
-
973
- Returns:
974
- A list of story objects associated with the provided external link.
975
-
976
- Raises:
977
- ValueError: Raised when the 'external_link' parameter is None.
978
- HTTPError: Raised when the HTTP request fails (via raise_for_status()).
979
-
980
- Tags:
981
- retrieve, stories, external-link, api, get, query,
982
- """
983
- if external_link is None:
984
- raise ValueError("Missing required parameter 'external_link'")
985
- url = f"{self.base_url}/api/v3/external-link/stories"
986
- query_params = {k: v for k, v in [('external_link', external_link)] if v is not None}
987
- response = self._get(url, params=query_params)
988
- response.raise_for_status()
989
- return response.json()
990
-
991
- def list_files(self, ) -> list[Any]:
992
- """
993
- Retrieves a list of files from the remote API endpoint.
994
-
995
- Args:
996
- None: This function takes no arguments
997
-
998
- Returns:
999
- A list containing file objects deserialized from the API response.
1000
-
1001
- Raises:
1002
- requests.HTTPError: If the HTTP request returns an unsuccessful status code.
1003
-
1004
- Tags:
1005
- list, files, api,
1006
- """
1007
- url = f"{self.base_url}/api/v3/files"
1008
- query_params = {}
1009
- response = self._get(url, params=query_params)
1010
- response.raise_for_status()
1011
- return response.json()
1012
-
1013
- def get_file(self, file_public_id) -> dict[str, Any]:
1014
- """
1015
- Retrieves a file based on its public ID, returning a dictionary containing file information.
1016
-
1017
- Args:
1018
- file_public_id: The public ID of the file to retrieve; must be a string.
1019
-
1020
- Returns:
1021
- A dictionary containing file information retrieved from the API.
1022
-
1023
- Raises:
1024
- ValueError: Raised if the 'file_public_id' parameter is missing.
1025
-
1026
- Tags:
1027
- fetch, management,
1028
- """
1029
- if file_public_id is None:
1030
- raise ValueError("Missing required parameter 'file-public-id'")
1031
- url = f"{self.base_url}/api/v3/files/{file_public_id}"
1032
- query_params = {}
1033
- response = self._get(url, params=query_params)
1034
- response.raise_for_status()
1035
- return response.json()
1036
-
1037
- def update_file(self, file_public_id, description=None, created_at=None, updated_at=None, name=None, uploader_id=None, external_id=None) -> dict[str, Any]:
1038
- """
1039
- Updates metadata for a file identified by its public ID.
1040
-
1041
- Args:
1042
- file_public_id: The public ID of the file to update. Must not be None.
1043
- description: Optional. New description for the file.
1044
- created_at: Optional. New creation timestamp for the file.
1045
- updated_at: Optional. New update timestamp for the file.
1046
- name: Optional. New name for the file.
1047
- uploader_id: Optional. ID of the user who uploaded the file.
1048
- external_id: Optional. External identifier for the file.
1049
-
1050
- Returns:
1051
- Dictionary containing the updated file information from the API response.
1052
-
1053
- Raises:
1054
- ValueError: Raised when file_public_id is None.
1055
- HTTPError: Raised when the API request fails.
1056
-
1057
- Tags:
1058
- update, file, api, metadata,
1059
- """
1060
- if file_public_id is None:
1061
- raise ValueError("Missing required parameter 'file-public-id'")
1062
- request_body = {
1063
- 'description': description,
1064
- 'created_at': created_at,
1065
- 'updated_at': updated_at,
1066
- 'name': name,
1067
- 'uploader_id': uploader_id,
1068
- 'external_id': external_id,
1069
- }
1070
- request_body = {k: v for k, v in request_body.items() if v is not None}
1071
- url = f"{self.base_url}/api/v3/files/{file_public_id}"
1072
- query_params = {}
1073
- response = self._put(url, data=request_body, params=query_params)
1074
- response.raise_for_status()
1075
- return response.json()
1076
-
1077
- def delete_file(self, file_public_id) -> Any:
1078
- """
1079
- Deletes a file identified by a public ID from the server.
1080
-
1081
- Args:
1082
- file_public_id: String representing the unique public identifier of the file to be deleted.
1083
-
1084
- Returns:
1085
- JSON representation of the server's response after deletion.
1086
-
1087
- Raises:
1088
- ValueError: Raised when file_public_id is None, as it's a required parameter.
1089
- HTTPError: Raised when the server returns an error status code.
1090
-
1091
- Tags:
1092
- delete, file, management,
1093
- """
1094
- if file_public_id is None:
1095
- raise ValueError("Missing required parameter 'file-public-id'")
1096
- url = f"{self.base_url}/api/v3/files/{file_public_id}"
1097
- query_params = {}
1098
- response = self._delete(url, params=query_params)
1099
- response.raise_for_status()
1100
- return response.json()
1101
-
1102
- def list_groups(self, ) -> list[Any]:
1103
- """
1104
- Retrieves a list of all groups from the API.
1105
-
1106
- Returns:
1107
- A list of dictionaries containing group information from the API response.
1108
-
1109
- Raises:
1110
- HTTPError: If the HTTP request returns an unsuccessful status code.
1111
-
1112
- Tags:
1113
- list, groups, api, get,
1114
- """
1115
- url = f"{self.base_url}/api/v3/groups"
1116
- query_params = {}
1117
- response = self._get(url, params=query_params)
1118
- response.raise_for_status()
1119
- return response.json()
1120
-
1121
- def create_group(self, name, mention_name, description=None, member_ids=None, workflow_ids=None, color=None, color_key=None, display_icon_id=None) -> dict[str, Any]:
1122
- """
1123
- Creates a new group with the specified configuration and returns the group's details.
1124
-
1125
- Args:
1126
- name: str. The display name of the group. This parameter is required.
1127
- mention_name: str. The mention identifier for the group (e.g., @groupname). This parameter is required.
1128
- description: Optional[str]. A description of the group.
1129
- member_ids: Optional[list[str]]. A list of user IDs to be added as group members.
1130
- workflow_ids: Optional[list[str]]. A list of workflow IDs to associate with the group.
1131
- color: Optional[str]. The display color for the group in hexadecimal or named format.
1132
- color_key: Optional[str]. A predefined key representing the group's color.
1133
- display_icon_id: Optional[str]. The ID of the icon to be displayed for the group.
1134
-
1135
- Returns:
1136
- dict[str, Any]: A dictionary containing the details of the newly created group as returned by the backend API.
1137
-
1138
- Raises:
1139
- ValueError: Raised if the required parameters 'name' or 'mention_name' are missing.
1140
- requests.HTTPError: Raised if the HTTP request to create the group fails (non-2xx status code).
1141
-
1142
- Tags:
1143
- create, group, management, api,
1144
- """
1145
- if name is None:
1146
- raise ValueError("Missing required parameter 'name'")
1147
- if mention_name is None:
1148
- raise ValueError("Missing required parameter 'mention_name'")
1149
- request_body = {
1150
- 'description': description,
1151
- 'member_ids': member_ids,
1152
- 'workflow_ids': workflow_ids,
1153
- 'name': name,
1154
- 'mention_name': mention_name,
1155
- 'color': color,
1156
- 'color_key': color_key,
1157
- 'display_icon_id': display_icon_id,
1158
- }
1159
- request_body = {k: v for k, v in request_body.items() if v is not None}
1160
- url = f"{self.base_url}/api/v3/groups"
1161
- query_params = {}
1162
- response = self._post(url, data=request_body, params=query_params)
1163
- response.raise_for_status()
1164
- return response.json()
1165
-
1166
- def get_group(self, group_public_id) -> dict[str, Any]:
1167
- """
1168
- Retrieves information about a specific group using its public ID.
1169
-
1170
- Args:
1171
- group_public_id: The public identifier of the group to retrieve.
1172
-
1173
- Returns:
1174
- A dictionary containing the group's information from the API response.
1175
-
1176
- Raises:
1177
- ValueError: When the required parameter 'group_public_id' is None.
1178
- HTTPError: When the API request fails or returns an error status code.
1179
-
1180
- Tags:
1181
- get, retrieve, group, api,
1182
- """
1183
- if group_public_id is None:
1184
- raise ValueError("Missing required parameter 'group-public-id'")
1185
- url = f"{self.base_url}/api/v3/groups/{group_public_id}"
1186
- query_params = {}
1187
- response = self._get(url, params=query_params)
1188
- response.raise_for_status()
1189
- return response.json()
1190
-
1191
- def update_group(self, group_public_id, description=None, archived=None, color=None, display_icon_id=None, mention_name=None, name=None, color_key=None, member_ids=None, workflow_ids=None) -> dict[str, Any]:
1192
- """
1193
- Updates the properties of an existing group by its public ID.
1194
-
1195
- Args:
1196
- group_public_id: str. The unique public identifier of the group to update.
1197
- description: str or None. The new description for the group.
1198
- archived: bool or None. Whether the group should be archived.
1199
- color: str or None. The new color for the group.
1200
- display_icon_id: str or None. Identifier of the display icon for the group.
1201
- mention_name: str or None. The mention name for the group.
1202
- name: str or None. The new name for the group.
1203
- color_key: str or None. The color key for the group.
1204
- member_ids: list[str] or None. List of member IDs to assign to the group.
1205
- workflow_ids: list[str] or None. List of workflow IDs to associate with the group.
1206
-
1207
- Returns:
1208
- dict[str, Any]: The updated group data as returned by the API.
1209
-
1210
- Raises:
1211
- ValueError: If 'group_public_id' is not provided.
1212
- requests.HTTPError: If the HTTP request to update the group fails.
1213
-
1214
- Tags:
1215
- update, management, group, api,
1216
- """
1217
- if group_public_id is None:
1218
- raise ValueError("Missing required parameter 'group-public-id'")
1219
- request_body = {
1220
- 'description': description,
1221
- 'archived': archived,
1222
- 'color': color,
1223
- 'display_icon_id': display_icon_id,
1224
- 'mention_name': mention_name,
1225
- 'name': name,
1226
- 'color_key': color_key,
1227
- 'member_ids': member_ids,
1228
- 'workflow_ids': workflow_ids,
1229
- }
1230
- request_body = {k: v for k, v in request_body.items() if v is not None}
1231
- url = f"{self.base_url}/api/v3/groups/{group_public_id}"
1232
- query_params = {}
1233
- response = self._put(url, data=request_body, params=query_params)
1234
- response.raise_for_status()
1235
- return response.json()
1236
-
1237
- def list_group_stories(self, group_public_id, limit=None, offset=None) -> list[Any]:
1238
- """
1239
- Retrieves a list of stories from a specific group.
1240
-
1241
- Args:
1242
- group_public_id: The public identifier of the group to retrieve stories from.
1243
- limit: The maximum number of stories to return. If None, returns all available stories.
1244
- offset: The number of stories to skip before starting to collect the result set. If None, starts from the beginning.
1245
-
1246
- Returns:
1247
- A list of story objects in JSON format.
1248
-
1249
- Raises:
1250
- ValueError: When the required parameter 'group_public_id' is None.
1251
- HTTPError: When the HTTP request fails or returns an error status code.
1252
-
1253
- Tags:
1254
- list, retrieve, stories, group, api,
1255
- """
1256
- if group_public_id is None:
1257
- raise ValueError("Missing required parameter 'group-public-id'")
1258
- url = f"{self.base_url}/api/v3/groups/{group_public_id}/stories"
1259
- query_params = {k: v for k, v in [('limit', limit), ('offset', offset)] if v is not None}
1260
- response = self._get(url, params=query_params)
1261
- response.raise_for_status()
1262
- return response.json()
1263
-
1264
- def list_iterations(self, ) -> list[Any]:
1265
- """
1266
- Lists all available iterations from the API.
1267
-
1268
- Args:
1269
- None: This function takes no parameters.
1270
-
1271
- Returns:
1272
- A list of iteration objects retrieved from the API endpoint.
1273
-
1274
- Raises:
1275
- HTTPError: Raised when the HTTP request fails due to an error status code.
1276
-
1277
- Tags:
1278
- list, iterations, api, retrieve,
1279
- """
1280
- url = f"{self.base_url}/api/v3/iterations"
1281
- query_params = {}
1282
- response = self._get(url, params=query_params)
1283
- response.raise_for_status()
1284
- return response.json()
1285
-
1286
- def create_iteration(self, name, start_date, end_date, follower_ids=None, group_ids=None, labels=None, description=None) -> dict[str, Any]:
1287
- """
1288
- Creates a new iteration with the specified details and returns the server's response as a dictionary.
1289
-
1290
- Args:
1291
- name: str. The name of the iteration to create. Required.
1292
- start_date: str. The starting date of the iteration in ISO format. Required.
1293
- end_date: str. The ending date of the iteration in ISO format. Required.
1294
- follower_ids: Optional[list[str]]. List of user IDs to assign as followers for the iteration.
1295
- group_ids: Optional[list[str]]. List of group IDs associated with the iteration.
1296
- labels: Optional[list[str]]. List of labels to tag the iteration.
1297
- description: Optional[str]. Additional description for the iteration.
1298
-
1299
- Returns:
1300
- dict[str, Any]: The JSON response from the server containing details of the created iteration.
1301
-
1302
- Raises:
1303
- ValueError: If any required parameter ('name', 'start_date', 'end_date') is missing.
1304
- requests.HTTPError: If the HTTP request to create the iteration fails (non-2xx response).
1305
-
1306
- Tags:
1307
- create, iteration, api, management,
1308
- """
1309
- if name is None:
1310
- raise ValueError("Missing required parameter 'name'")
1311
- if start_date is None:
1312
- raise ValueError("Missing required parameter 'start_date'")
1313
- if end_date is None:
1314
- raise ValueError("Missing required parameter 'end_date'")
1315
- request_body = {
1316
- 'follower_ids': follower_ids,
1317
- 'group_ids': group_ids,
1318
- 'labels': labels,
1319
- 'description': description,
1320
- 'name': name,
1321
- 'start_date': start_date,
1322
- 'end_date': end_date,
1323
- }
1324
- request_body = {k: v for k, v in request_body.items() if v is not None}
1325
- url = f"{self.base_url}/api/v3/iterations"
1326
- query_params = {}
1327
- response = self._post(url, data=request_body, params=query_params)
1328
- response.raise_for_status()
1329
- return response.json()
1330
-
1331
- def disable_iterations(self, ) -> Any:
1332
- """
1333
- Disables iterations by making a PUT request to the iterations API endpoint.
1334
-
1335
- Returns:
1336
- JSON response from the server after disabling iterations.
1337
-
1338
- Raises:
1339
- HTTPError: Raised when the HTTP request returns an unsuccessful status code.
1340
-
1341
- Tags:
1342
- disable, iterations, api, management,
1343
- """
1344
- url = f"{self.base_url}/api/v3/iterations/disable"
1345
- query_params = {}
1346
- response = self._put(url, data={}, params=query_params)
1347
- response.raise_for_status()
1348
- return response.json()
1349
-
1350
- def enable_iterations(self, ) -> Any:
1351
- """
1352
- Enable iterations for the API service.
1353
-
1354
- Returns:
1355
- JSON response from the API containing the result of enabling iterations.
1356
-
1357
- Raises:
1358
- HTTPError: Raised when the HTTP request returns an unsuccessful status code.
1359
-
1360
- Tags:
1361
- enable, iterations, api, management,
1362
- """
1363
- url = f"{self.base_url}/api/v3/iterations/enable"
1364
- query_params = {}
1365
- response = self._put(url, data={}, params=query_params)
1366
- response.raise_for_status()
1367
- return response.json()
1368
-
1369
- def get_iteration(self, iteration_public_id) -> dict[str, Any]:
1370
- """
1371
- Retrieves iteration details using the specified public ID.
1372
-
1373
- Args:
1374
- iteration_public_id: The public ID of the iteration to retrieve.
1375
-
1376
- Returns:
1377
- A dictionary containing the iteration details from the API response.
1378
-
1379
- Raises:
1380
- ValueError: Raised when the required parameter 'iteration-public-id' is None.
1381
- HTTPError: Raised when the API request fails (via raise_for_status()).
1382
-
1383
- Tags:
1384
- get, retrieve, iteration, api,
1385
- """
1386
- if iteration_public_id is None:
1387
- raise ValueError("Missing required parameter 'iteration-public-id'")
1388
- url = f"{self.base_url}/api/v3/iterations/{iteration_public_id}"
1389
- query_params = {}
1390
- response = self._get(url, params=query_params)
1391
- response.raise_for_status()
1392
- return response.json()
1393
-
1394
- def update_iteration(self, iteration_public_id, follower_ids=None, group_ids=None, labels=None, description=None, name=None, start_date=None, end_date=None) -> dict[str, Any]:
1395
- """
1396
- Updates an existing iteration with the provided attributes.
1397
-
1398
- Args:
1399
- iteration_public_id: The unique identifier for the iteration to be updated.
1400
- follower_ids: Optional list of user IDs to follow the iteration.
1401
- group_ids: Optional list of group IDs associated with the iteration.
1402
- labels: Optional list of labels to apply to the iteration.
1403
- description: Optional text describing the iteration.
1404
- name: Optional name for the iteration.
1405
- start_date: Optional start date for the iteration.
1406
- end_date: Optional end date for the iteration.
1407
-
1408
- Returns:
1409
- A dictionary containing the updated iteration data.
1410
-
1411
- Raises:
1412
- ValueError: When the required parameter 'iteration_public_id' is None.
1413
- HTTPError: When the API request fails.
1414
-
1415
- Tags:
1416
- update, iteration, management,
1417
- """
1418
- if iteration_public_id is None:
1419
- raise ValueError("Missing required parameter 'iteration-public-id'")
1420
- request_body = {
1421
- 'follower_ids': follower_ids,
1422
- 'group_ids': group_ids,
1423
- 'labels': labels,
1424
- 'description': description,
1425
- 'name': name,
1426
- 'start_date': start_date,
1427
- 'end_date': end_date,
1428
- }
1429
- request_body = {k: v for k, v in request_body.items() if v is not None}
1430
- url = f"{self.base_url}/api/v3/iterations/{iteration_public_id}"
1431
- query_params = {}
1432
- response = self._put(url, data=request_body, params=query_params)
1433
- response.raise_for_status()
1434
- return response.json()
1435
-
1436
- def delete_iteration(self, iteration_public_id) -> Any:
1437
- """
1438
- Deletes a specific iteration identified by its public ID.
1439
-
1440
- Args:
1441
- iteration_public_id: String representing the public ID of the iteration to be deleted.
1442
-
1443
- Returns:
1444
- JSON response from the API containing information about the deleted iteration.
1445
-
1446
- Raises:
1447
- ValueError: Raised when the required 'iteration_public_id' parameter is None.
1448
- HTTPError: Raised when the API request fails or returns an error status code.
1449
-
1450
- Tags:
1451
- delete, management, api, iteration,
1452
- """
1453
- if iteration_public_id is None:
1454
- raise ValueError("Missing required parameter 'iteration-public-id'")
1455
- url = f"{self.base_url}/api/v3/iterations/{iteration_public_id}"
1456
- query_params = {}
1457
- response = self._delete(url, params=query_params)
1458
- response.raise_for_status()
1459
- return response.json()
1460
-
1461
- def list_iteration_stories(self, iteration_public_id, includes_description=None) -> list[Any]:
1462
- """
1463
- Retrieves a list of stories for a specified iteration, optionally including their descriptions.
1464
-
1465
- Args:
1466
- iteration_public_id: str. The public identifier of the iteration whose stories are to be listed.
1467
- includes_description: Optional[bool]. Whether to include story descriptions in the response. If None, descriptions are not included.
1468
-
1469
- Returns:
1470
- list[Any]: A list containing story data dictionaries for the specified iteration.
1471
-
1472
- Raises:
1473
- ValueError: Raised if 'iteration_public_id' is None.
1474
- HTTPError: Raised if the HTTP request returns an unsuccessful status code.
1475
-
1476
- Tags:
1477
- list, stories, iteration, api,
1478
- """
1479
- if iteration_public_id is None:
1480
- raise ValueError("Missing required parameter 'iteration-public-id'")
1481
- url = f"{self.base_url}/api/v3/iterations/{iteration_public_id}/stories"
1482
- query_params = {k: v for k, v in [('includes_description', includes_description)] if v is not None}
1483
- response = self._get(url, params=query_params)
1484
- response.raise_for_status()
1485
- return response.json()
1486
-
1487
- def get_key_result(self, key_result_public_id) -> dict[str, Any]:
1488
- """
1489
- Retrieves detailed information for a specific key result using its public identifier.
1490
-
1491
- Args:
1492
- key_result_public_id: The public identifier (str) of the key result to retrieve.
1493
-
1494
- Returns:
1495
- A dictionary containing the key result's data as returned by the API.
1496
-
1497
- Raises:
1498
- ValueError: If the key_result_public_id parameter is None.
1499
- requests.exceptions.HTTPError: If the underlying HTTP request fails or returns a bad status code.
1500
-
1501
- Tags:
1502
- get, key-result, api, management,
1503
- """
1504
- if key_result_public_id is None:
1505
- raise ValueError("Missing required parameter 'key-result-public-id'")
1506
- url = f"{self.base_url}/api/v3/key-results/{key_result_public_id}"
1507
- query_params = {}
1508
- response = self._get(url, params=query_params)
1509
- response.raise_for_status()
1510
- return response.json()
1511
-
1512
- def update_key_result(self, key_result_public_id, name=None, initial_observed_value=None, observed_value=None, target_value=None) -> dict[str, Any]:
1513
- """
1514
- Updates a key result with the provided details.
1515
-
1516
- Args:
1517
- key_result_public_id: The public ID of the key result to update.
1518
- name: Optional new name for the key result.
1519
- initial_observed_value: Optional new initial observed value for the key result.
1520
- observed_value: Optional new observed value for the key result.
1521
- target_value: Optional new target value for the key result.
1522
-
1523
- Returns:
1524
- A dictionary containing the details of the updated key result.
1525
-
1526
- Raises:
1527
- ValueError: Raised if the 'key_result_public_id' parameter is missing.
1528
-
1529
- Tags:
1530
- update, management,
1531
- """
1532
- if key_result_public_id is None:
1533
- raise ValueError("Missing required parameter 'key-result-public-id'")
1534
- request_body = {
1535
- 'name': name,
1536
- 'initial_observed_value': initial_observed_value,
1537
- 'observed_value': observed_value,
1538
- 'target_value': target_value,
1539
- }
1540
- request_body = {k: v for k, v in request_body.items() if v is not None}
1541
- url = f"{self.base_url}/api/v3/key-results/{key_result_public_id}"
1542
- query_params = {}
1543
- response = self._put(url, data=request_body, params=query_params)
1544
- response.raise_for_status()
1545
- return response.json()
1546
-
1547
- def list_labels(self, slim=None) -> list[Any]:
1548
- """
1549
- Fetches a list of labels from the API.
1550
-
1551
- Args:
1552
- slim: Boolean flag that when set to True returns a simplified version of labels. If None, the default API behavior is used.
1553
-
1554
- Returns:
1555
- A list of label objects (dictionaries) containing label information returned by the API.
1556
-
1557
- Raises:
1558
- HTTPError: Raised when the API request fails or returns an error status code.
1559
-
1560
- Tags:
1561
- list, fetch, labels, api, data-retrieval,
1562
- """
1563
- url = f"{self.base_url}/api/v3/labels"
1564
- query_params = {k: v for k, v in [('slim', slim)] if v is not None}
1565
- response = self._get(url, params=query_params)
1566
- response.raise_for_status()
1567
- return response.json()
1568
-
1569
- def create_label(self, name, description=None, color=None, external_id=None) -> dict[str, Any]:
1570
- """
1571
- Creates a new label with the specified attributes.
1572
-
1573
- Args:
1574
- name: The name of the label (required).
1575
- description: Optional description of the label.
1576
- color: Optional color specification for the label.
1577
- external_id: Optional external identifier for the label.
1578
-
1579
- Returns:
1580
- A dictionary containing the created label's data as returned by the API.
1581
-
1582
- Raises:
1583
- ValueError: Raised when the required 'name' parameter is None.
1584
- HTTPError: Raised when the API request fails.
1585
-
1586
- Tags:
1587
- create, label, management,
1588
- """
1589
- if name is None:
1590
- raise ValueError("Missing required parameter 'name'")
1591
- request_body = {
1592
- 'name': name,
1593
- 'description': description,
1594
- 'color': color,
1595
- 'external_id': external_id,
1596
- }
1597
- request_body = {k: v for k, v in request_body.items() if v is not None}
1598
- url = f"{self.base_url}/api/v3/labels"
1599
- query_params = {}
1600
- response = self._post(url, data=request_body, params=query_params)
1601
- response.raise_for_status()
1602
- return response.json()
1603
-
1604
- def get_label(self, label_public_id) -> dict[str, Any]:
1605
- """
1606
- Retrieves a label's details from the API using its public identifier.
1607
-
1608
- Args:
1609
- label_public_id: str. The public identifier of the label to retrieve.
1610
-
1611
- Returns:
1612
- dict[str, Any]: A dictionary containing label details as returned by the API.
1613
-
1614
- Raises:
1615
- ValueError: If 'label_public_id' is None.
1616
- requests.HTTPError: If the HTTP request to the API fails or returns an error response.
1617
-
1618
- Tags:
1619
- get, label, fetch, api, management,
1620
- """
1621
- if label_public_id is None:
1622
- raise ValueError("Missing required parameter 'label-public-id'")
1623
- url = f"{self.base_url}/api/v3/labels/{label_public_id}"
1624
- query_params = {}
1625
- response = self._get(url, params=query_params)
1626
- response.raise_for_status()
1627
- return response.json()
1628
-
1629
- def update_label(self, label_public_id, name=None, description=None, color=None, archived=None) -> dict[str, Any]:
1630
- """
1631
- Updates a label with the specified information.
1632
-
1633
- Args:
1634
- label_public_id: The public ID of the label to update.
1635
- name: Optional. The new name for the label.
1636
- description: Optional. The new description for the label.
1637
- color: Optional. The new color for the label.
1638
- archived: Optional. Boolean indicating whether the label should be archived.
1639
-
1640
- Returns:
1641
- A dictionary containing the updated label information.
1642
-
1643
- Raises:
1644
- ValueError: If label_public_id is None.
1645
- HTTPError: If the request to update the label fails.
1646
-
1647
- Tags:
1648
- update, label, management,
1649
- """
1650
- if label_public_id is None:
1651
- raise ValueError("Missing required parameter 'label-public-id'")
1652
- request_body = {
1653
- 'name': name,
1654
- 'description': description,
1655
- 'color': color,
1656
- 'archived': archived,
1657
- }
1658
- request_body = {k: v for k, v in request_body.items() if v is not None}
1659
- url = f"{self.base_url}/api/v3/labels/{label_public_id}"
1660
- query_params = {}
1661
- response = self._put(url, data=request_body, params=query_params)
1662
- response.raise_for_status()
1663
- return response.json()
1664
-
1665
- def delete_label(self, label_public_id) -> Any:
1666
- """
1667
- Deletes a label identified by its public ID via an HTTP DELETE request.
1668
-
1669
- Args:
1670
- label_public_id: The public unique identifier of the label to be deleted.
1671
-
1672
- Returns:
1673
- The parsed JSON response from the API after deleting the label.
1674
-
1675
- Raises:
1676
- ValueError: If 'label_public_id' is None.
1677
- HTTPError: If the HTTP request to delete the label fails (e.g., network issues, 4xx/5xx response from the server).
1678
-
1679
- Tags:
1680
- delete, label-management, api,
1681
- """
1682
- if label_public_id is None:
1683
- raise ValueError("Missing required parameter 'label-public-id'")
1684
- url = f"{self.base_url}/api/v3/labels/{label_public_id}"
1685
- query_params = {}
1686
- response = self._delete(url, params=query_params)
1687
- response.raise_for_status()
1688
- return response.json()
1689
-
1690
- def list_label_epics(self, label_public_id) -> list[Any]:
1691
- """
1692
- Retrieves a list of epics associated with a specific label.
1693
-
1694
- Args:
1695
- label_public_id: The unique identifier of the label whose associated epics are to be retrieved.
1696
-
1697
- Returns:
1698
- A list of epic objects associated with the specified label.
1699
-
1700
- Raises:
1701
- ValueError: Raised when the required parameter 'label_public_id' is None.
1702
- HTTPError: Raised when the API request fails.
1703
-
1704
- Tags:
1705
- list, retrieve, epics, label, api
1706
- """
1707
- if label_public_id is None:
1708
- raise ValueError("Missing required parameter 'label-public-id'")
1709
- url = f"{self.base_url}/api/v3/labels/{label_public_id}/epics"
1710
- query_params = {}
1711
- response = self._get(url, params=query_params)
1712
- response.raise_for_status()
1713
- return response.json()
1714
-
1715
- def list_label_stories(self, label_public_id, includes_description=None) -> list[Any]:
1716
- """
1717
- Retrieves a list of stories associated with a specific label.
1718
-
1719
- Args:
1720
- label_public_id: The public identifier of the label whose stories are to be retrieved.
1721
- includes_description: Optional flag to include story descriptions in the response.
1722
-
1723
- Returns:
1724
- A list of story objects associated with the specified label.
1725
-
1726
- Raises:
1727
- ValueError: Raised when the required parameter 'label_public_id' is None.
1728
- HTTPError: Raised when the HTTP request to the API fails.
1729
-
1730
- Tags:
1731
- list, stories, labels, retrieve, api,
1732
- """
1733
- if label_public_id is None:
1734
- raise ValueError("Missing required parameter 'label-public-id'")
1735
- url = f"{self.base_url}/api/v3/labels/{label_public_id}/stories"
1736
- query_params = {k: v for k, v in [('includes_description', includes_description)] if v is not None}
1737
- response = self._get(url, params=query_params)
1738
- response.raise_for_status()
1739
- return response.json()
1740
-
1741
- def list_linked_files(self, ) -> list[Any]:
1742
- """
1743
- Retrieve a list of all linked files.
1744
-
1745
- Returns:
1746
- A list of dictionaries, where each dictionary contains information about a linked file.
1747
-
1748
- Raises:
1749
- HTTPError: Raised when the HTTP request returns an unsuccessful status code.
1750
-
1751
- Tags:
1752
- list, linked-files, api, get,
1753
- """
1754
- url = f"{self.base_url}/api/v3/linked-files"
1755
- query_params = {}
1756
- response = self._get(url, params=query_params)
1757
- response.raise_for_status()
1758
- return response.json()
1759
-
1760
- def create_linked_file(self, name, type, url, description=None, story_id=None, thumbnail_url=None, size=None, uploader_id=None, content_type=None) -> dict[str, Any]:
1761
- """
1762
- Creates a linked file with the specified attributes.
1763
-
1764
- Args:
1765
- name: The name of the linked file (required).
1766
- type: The type of the linked file (required).
1767
- url: The URL of the linked file (required).
1768
- description: Optional description of the linked file.
1769
- story_id: Optional ID of the story this file is linked to.
1770
- thumbnail_url: Optional URL for the thumbnail of the linked file.
1771
- size: Optional size of the linked file.
1772
- uploader_id: Optional ID of the user who uploaded the file.
1773
- content_type: Optional content type of the linked file.
1774
-
1775
- Returns:
1776
- Dictionary containing the created linked file information.
1777
-
1778
- Raises:
1779
- ValueError: Raised when required parameters 'name', 'type', or 'url' are None.
1780
- HTTPError: Raised when the HTTP request fails.
1781
-
1782
- Tags:
1783
- create, file, linked, api,
1784
- """
1785
- if name is None:
1786
- raise ValueError("Missing required parameter 'name'")
1787
- if type is None:
1788
- raise ValueError("Missing required parameter 'type'")
1789
- if url is None:
1790
- raise ValueError("Missing required parameter 'url'")
1791
- request_body = {
1792
- 'description': description,
1793
- 'story_id': story_id,
1794
- 'name': name,
1795
- 'thumbnail_url': thumbnail_url,
1796
- 'type': type,
1797
- 'size': size,
1798
- 'uploader_id': uploader_id,
1799
- 'content_type': content_type,
1800
- 'url': url,
1801
- }
1802
- request_body = {k: v for k, v in request_body.items() if v is not None}
1803
- url = f"{self.base_url}/api/v3/linked-files"
1804
- query_params = {}
1805
- response = self._post(url, data=request_body, params=query_params)
1806
- response.raise_for_status()
1807
- return response.json()
1808
-
1809
- def get_linked_file(self, linked_file_public_id) -> dict[str, Any]:
1810
- """
1811
- Fetches details for a linked file by its public identifier.
1812
-
1813
- Args:
1814
- linked_file_public_id: The public identifier (string) of the linked file to retrieve.
1815
-
1816
- Returns:
1817
- A dictionary containing metadata and details of the requested linked file.
1818
-
1819
- Raises:
1820
- ValueError: If 'linked_file_public_id' is None.
1821
- HTTPError: If the HTTP request to fetch the linked file fails.
1822
-
1823
- Tags:
1824
- fetch, linked-files, api, http,
1825
- """
1826
- if linked_file_public_id is None:
1827
- raise ValueError("Missing required parameter 'linked-file-public-id'")
1828
- url = f"{self.base_url}/api/v3/linked-files/{linked_file_public_id}"
1829
- query_params = {}
1830
- response = self._get(url, params=query_params)
1831
- response.raise_for_status()
1832
- return response.json()
1833
-
1834
- def update_linked_file(self, linked_file_public_id, description=None, story_id=None, name=None, thumbnail_url=None, type=None, size=None, uploader_id=None, url=None) -> dict[str, Any]:
1835
- """
1836
- Updates a linked file with the specified parameters.
1837
-
1838
- Args:
1839
- linked_file_public_id: The unique identifier of the linked file to update. Required.
1840
- description: Optional new description for the linked file.
1841
- story_id: Optional story ID to associate with the linked file.
1842
- name: Optional new name for the linked file.
1843
- thumbnail_url: Optional URL for the linked file's thumbnail image.
1844
- type: Optional type classification for the linked file.
1845
- size: Optional size specification for the linked file.
1846
- uploader_id: Optional ID of the user who uploaded the file.
1847
- url: Optional URL where the linked file can be accessed.
1848
-
1849
- Returns:
1850
- A dictionary containing the updated linked file data.
1851
-
1852
- Raises:
1853
- ValueError: Raised when the required parameter 'linked-file-public-id' is None.
1854
- HTTPError: Raised when the API request fails.
1855
-
1856
- Tags:
1857
- update, file, api, linked-file, management,
1858
- """
1859
- if linked_file_public_id is None:
1860
- raise ValueError("Missing required parameter 'linked-file-public-id'")
1861
- request_body = {
1862
- 'description': description,
1863
- 'story_id': story_id,
1864
- 'name': name,
1865
- 'thumbnail_url': thumbnail_url,
1866
- 'type': type,
1867
- 'size': size,
1868
- 'uploader_id': uploader_id,
1869
- 'url': url,
1870
- }
1871
- request_body = {k: v for k, v in request_body.items() if v is not None}
1872
- url = f"{self.base_url}/api/v3/linked-files/{linked_file_public_id}"
1873
- query_params = {}
1874
- response = self._put(url, data=request_body, params=query_params)
1875
- response.raise_for_status()
1876
- return response.json()
1877
-
1878
- def delete_linked_file(self, linked_file_public_id) -> Any:
1879
- """
1880
- Deletes a linked file by its public ID using the API.
1881
-
1882
- Args:
1883
- linked_file_public_id: The public identifier of the linked file to be deleted.
1884
-
1885
- Returns:
1886
- The JSON response from the API as returned by the DELETE operation.
1887
-
1888
- Raises:
1889
- ValueError: If 'linked_file_public_id' is None.
1890
- requests.HTTPError: If the HTTP request to delete the linked file fails.
1891
-
1892
- Tags:
1893
- delete, linked-file, api, management,
1894
- """
1895
- if linked_file_public_id is None:
1896
- raise ValueError("Missing required parameter 'linked-file-public-id'")
1897
- url = f"{self.base_url}/api/v3/linked-files/{linked_file_public_id}"
1898
- query_params = {}
1899
- response = self._delete(url, params=query_params)
1900
- response.raise_for_status()
1901
- return response.json()
1902
-
1903
- def get_current_member_info(self, ) -> dict[str, Any]:
1904
- """
1905
- Retrieves information about the current authenticated member.
1906
-
1907
- Returns:
1908
- A dictionary containing information about the current member.
1909
-
1910
- Raises:
1911
- HTTPError: When the API request fails or returns a non-successful status code.
1912
-
1913
- Tags:
1914
- get, retrieve, member, information, api,
1915
- """
1916
- url = f"{self.base_url}/api/v3/member"
1917
- query_params = {}
1918
- response = self._get(url, params=query_params)
1919
- response.raise_for_status()
1920
- return response.json()
1921
-
1922
- def list_milestones(self, ) -> list[Any]:
1923
- """
1924
- Lists milestones by fetching them from a specified API endpoint.
1925
-
1926
- Args:
1927
- None: This function takes no parameters.
1928
-
1929
- Returns:
1930
- A list of milestones in JSON format.
1931
-
1932
- Raises:
1933
- requests.exceptions.HTTPError: Raised when the HTTP request returns a status code indicating a client or server error.
1934
-
1935
- Tags:
1936
- list, api,
1937
- """
1938
- url = f"{self.base_url}/api/v3/milestones"
1939
- query_params = {}
1940
- response = self._get(url, params=query_params)
1941
- response.raise_for_status()
1942
- return response.json()
1943
-
1944
- def create_milestone(self, name, description=None, state=None, started_at_override=None, completed_at_override=None, categories=None) -> dict[str, Any]:
1945
- """
1946
- Creates a new milestone with the specified parameters.
1947
-
1948
- Args:
1949
- name: Required string representing the name of the milestone.
1950
- description: Optional string describing the milestone.
1951
- state: Optional string indicating the current state of the milestone.
1952
- started_at_override: Optional datetime or string representing when the milestone was started.
1953
- completed_at_override: Optional datetime or string representing when the milestone was completed.
1954
- categories: Optional list or array of categories to associate with the milestone.
1955
-
1956
- Returns:
1957
- A dictionary containing the created milestone data as returned by the API.
1958
-
1959
- Raises:
1960
- ValueError: Raised when the required 'name' parameter is not provided or is None.
1961
- HTTPError: Raised when the API request fails.
1962
-
1963
- Tags:
1964
- create, milestone, management,
1965
- """
1966
- if name is None:
1967
- raise ValueError("Missing required parameter 'name'")
1968
- request_body = {
1969
- 'name': name,
1970
- 'description': description,
1971
- 'state': state,
1972
- 'started_at_override': started_at_override,
1973
- 'completed_at_override': completed_at_override,
1974
- 'categories': categories,
1975
- }
1976
- request_body = {k: v for k, v in request_body.items() if v is not None}
1977
- url = f"{self.base_url}/api/v3/milestones"
1978
- query_params = {}
1979
- response = self._post(url, data=request_body, params=query_params)
1980
- response.raise_for_status()
1981
- return response.json()
1982
-
1983
- def get_milestone(self, milestone_public_id) -> dict[str, Any]:
1984
- """
1985
- Retrieves a milestone resource by its public identifier.
1986
-
1987
- Args:
1988
- milestone_public_id: The public identifier of the milestone to retrieve.
1989
-
1990
- Returns:
1991
- A dictionary containing the milestone details as returned by the API.
1992
-
1993
- Raises:
1994
- ValueError: If 'milestone_public_id' is None.
1995
- HTTPError: If the HTTP request to the API fails or returns an unsuccessful status code.
1996
-
1997
- Tags:
1998
- get, milestone, api, fetch,
1999
- """
2000
- if milestone_public_id is None:
2001
- raise ValueError("Missing required parameter 'milestone-public-id'")
2002
- url = f"{self.base_url}/api/v3/milestones/{milestone_public_id}"
2003
- query_params = {}
2004
- response = self._get(url, params=query_params)
2005
- response.raise_for_status()
2006
- return response.json()
2007
-
2008
- def update_milestone(self, milestone_public_id, description=None, archived=None, completed_at_override=None, name=None, state=None, started_at_override=None, categories=None, before_id=None, after_id=None) -> dict[str, Any]:
2009
- """
2010
- Updates the properties of an existing milestone with the given parameters.
2011
-
2012
- Args:
2013
- milestone_public_id: str. The unique public identifier of the milestone to update.
2014
- description: str, optional. The new description for the milestone.
2015
- archived: bool, optional. Whether to archive the milestone.
2016
- completed_at_override: str or datetime, optional. Override value for the milestone's completion timestamp.
2017
- name: str, optional. The new name for the milestone.
2018
- state: str, optional. The new state of the milestone.
2019
- started_at_override: str or datetime, optional. Override value for the milestone's start timestamp.
2020
- categories: list or None, optional. A list of categories to associate with the milestone.
2021
- before_id: str, optional. Insert this milestone before the specified milestone ID.
2022
- after_id: str, optional. Insert this milestone after the specified milestone ID.
2023
-
2024
- Returns:
2025
- dict. The updated milestone data as returned by the API.
2026
-
2027
- Raises:
2028
- ValueError: If 'milestone_public_id' is not provided.
2029
- requests.HTTPError: If the API request fails or returns an error status.
2030
-
2031
- Tags:
2032
- update, milestone-management, api,
2033
- """
2034
- if milestone_public_id is None:
2035
- raise ValueError("Missing required parameter 'milestone-public-id'")
2036
- request_body = {
2037
- 'description': description,
2038
- 'archived': archived,
2039
- 'completed_at_override': completed_at_override,
2040
- 'name': name,
2041
- 'state': state,
2042
- 'started_at_override': started_at_override,
2043
- 'categories': categories,
2044
- 'before_id': before_id,
2045
- 'after_id': after_id,
2046
- }
2047
- request_body = {k: v for k, v in request_body.items() if v is not None}
2048
- url = f"{self.base_url}/api/v3/milestones/{milestone_public_id}"
2049
- query_params = {}
2050
- response = self._put(url, data=request_body, params=query_params)
2051
- response.raise_for_status()
2052
- return response.json()
2053
-
2054
- def delete_milestone(self, milestone_public_id) -> Any:
2055
- """
2056
- Deletes a milestone by its public ID.
2057
-
2058
- Args:
2059
- milestone_public_id: The public ID of the milestone to be deleted.
2060
-
2061
- Returns:
2062
- The JSON response from the API after successful deletion.
2063
-
2064
- Raises:
2065
- ValueError: Raised when the milestone_public_id parameter is None.
2066
- HTTPError: Raised when the API request fails (via raise_for_status()).
2067
-
2068
- Tags:
2069
- delete, milestone, api,
2070
- """
2071
- if milestone_public_id is None:
2072
- raise ValueError("Missing required parameter 'milestone-public-id'")
2073
- url = f"{self.base_url}/api/v3/milestones/{milestone_public_id}"
2074
- query_params = {}
2075
- response = self._delete(url, params=query_params)
2076
- response.raise_for_status()
2077
- return response.json()
2078
-
2079
- def list_milestone_epics(self, milestone_public_id) -> list[Any]:
2080
- """
2081
- Retrieves a list of epics associated with a specified milestone.
2082
-
2083
- Args:
2084
- milestone_public_id: The public identifier of the milestone whose epics are to be listed.
2085
-
2086
- Returns:
2087
- A list containing the epics related to the given milestone.
2088
-
2089
- Raises:
2090
- ValueError: If 'milestone_public_id' is None.
2091
- requests.HTTPError: If the HTTP request to fetch epics fails with a client or server error.
2092
-
2093
- Tags:
2094
- list, epics, milestone, management,
2095
- """
2096
- if milestone_public_id is None:
2097
- raise ValueError("Missing required parameter 'milestone-public-id'")
2098
- url = f"{self.base_url}/api/v3/milestones/{milestone_public_id}/epics"
2099
- query_params = {}
2100
- response = self._get(url, params=query_params)
2101
- response.raise_for_status()
2102
- return response.json()
2103
-
2104
- def list_objectives(self, ) -> list[Any]:
2105
- """
2106
- Retrieves a list of all objectives from the API endpoint.
2107
-
2108
- Args:
2109
- None: This function takes no arguments
2110
-
2111
- Returns:
2112
- A list containing the objectives returned by the API. Each item in the list represents an objective as parsed from the JSON response.
2113
-
2114
- Raises:
2115
- requests.HTTPError: If the HTTP request to the API fails or returns a non-success status code.
2116
-
2117
- Tags:
2118
- list, objectives, api, management,
2119
- """
2120
- url = f"{self.base_url}/api/v3/objectives"
2121
- query_params = {}
2122
- response = self._get(url, params=query_params)
2123
- response.raise_for_status()
2124
- return response.json()
2125
-
2126
- def create_objective(self, name, description=None, state=None, started_at_override=None, completed_at_override=None, categories=None) -> dict[str, Any]:
2127
- """
2128
- Creates a new objective resource with the specified attributes and returns the created objective's data.
2129
-
2130
- Args:
2131
- name: str. The name of the objective. This parameter is required.
2132
- description: Optional[str]. A short description of the objective.
2133
- state: Optional[str]. The current state of the objective.
2134
- started_at_override: Optional[Any]. An override value for the start timestamp of the objective.
2135
- completed_at_override: Optional[Any]. An override value for the completion timestamp of the objective.
2136
- categories: Optional[Any]. Categories to associate with the objective.
2137
-
2138
- Returns:
2139
- dict[str, Any]: A dictionary containing the data of the newly created objective as returned by the API.
2140
-
2141
- Raises:
2142
- ValueError: Raised if the required parameter 'name' is missing.
2143
- requests.HTTPError: Raised if the HTTP request to the API fails or returns a non-success status code.
2144
-
2145
- Tags:
2146
- create, objective, api, management,
2147
- """
2148
- if name is None:
2149
- raise ValueError("Missing required parameter 'name'")
2150
- request_body = {
2151
- 'name': name,
2152
- 'description': description,
2153
- 'state': state,
2154
- 'started_at_override': started_at_override,
2155
- 'completed_at_override': completed_at_override,
2156
- 'categories': categories,
2157
- }
2158
- request_body = {k: v for k, v in request_body.items() if v is not None}
2159
- url = f"{self.base_url}/api/v3/objectives"
2160
- query_params = {}
2161
- response = self._post(url, data=request_body, params=query_params)
2162
- response.raise_for_status()
2163
- return response.json()
2164
-
2165
- def get_objective(self, objective_public_id) -> dict[str, Any]:
2166
- """
2167
- Retrieves an objective by its public ID from the API.
2168
-
2169
- Args:
2170
- objective_public_id: The unique public identifier of the objective to retrieve.
2171
-
2172
- Returns:
2173
- A dictionary containing the objective data retrieved from the API.
2174
-
2175
- Raises:
2176
- ValueError: When the objective_public_id parameter is None.
2177
- HTTPError: When the API request fails or returns an error status code.
2178
-
2179
- Tags:
2180
- get, retrieve, objective, api,
2181
- """
2182
- if objective_public_id is None:
2183
- raise ValueError("Missing required parameter 'objective-public-id'")
2184
- url = f"{self.base_url}/api/v3/objectives/{objective_public_id}"
2185
- query_params = {}
2186
- response = self._get(url, params=query_params)
2187
- response.raise_for_status()
2188
- return response.json()
2189
-
2190
- def update_objective(self, objective_public_id, description=None, archived=None, completed_at_override=None, name=None, state=None, started_at_override=None, categories=None, before_id=None, after_id=None) -> dict[str, Any]:
2191
- """
2192
- Updates an objective by its public ID with new values for fields such as description, archived status, completion and start timestamps, name, state, categories, and relative ordering.
2193
-
2194
- Args:
2195
- objective_public_id: str. The unique identifier of the objective to update. Required.
2196
- description: str | None. The new description for the objective. Optional.
2197
- archived: bool | None. Whether the objective is archived. Optional.
2198
- completed_at_override: str | None. A custom completion timestamp for the objective, in ISO 8601 format. Optional.
2199
- name: str | None. The new name of the objective. Optional.
2200
- state: str | None. The new state of the objective. Optional.
2201
- started_at_override: str | None. A custom start timestamp for the objective, in ISO 8601 format. Optional.
2202
- categories: list[str] | None. A list of category names to associate with the objective. Optional.
2203
- before_id: str | None. The public ID of another objective to place this one before. Optional.
2204
- after_id: str | None. The public ID of another objective to place this one after. Optional.
2205
-
2206
- Returns:
2207
- dict[str, Any]: The updated objective as returned by the API.
2208
-
2209
- Raises:
2210
- ValueError: If 'objective_public_id' is None.
2211
- requests.HTTPError: If the API responds with an error status code.
2212
-
2213
- Tags:
2214
- update, objective, api, management,
2215
- """
2216
- if objective_public_id is None:
2217
- raise ValueError("Missing required parameter 'objective-public-id'")
2218
- request_body = {
2219
- 'description': description,
2220
- 'archived': archived,
2221
- 'completed_at_override': completed_at_override,
2222
- 'name': name,
2223
- 'state': state,
2224
- 'started_at_override': started_at_override,
2225
- 'categories': categories,
2226
- 'before_id': before_id,
2227
- 'after_id': after_id,
2228
- }
2229
- request_body = {k: v for k, v in request_body.items() if v is not None}
2230
- url = f"{self.base_url}/api/v3/objectives/{objective_public_id}"
2231
- query_params = {}
2232
- response = self._put(url, data=request_body, params=query_params)
2233
- response.raise_for_status()
2234
- return response.json()
2235
-
2236
- def delete_objective(self, objective_public_id) -> Any:
2237
- """
2238
- Deletes an objective by its public ID using an HTTP DELETE request.
2239
-
2240
- Args:
2241
- objective_public_id: The public identifier of the objective to delete.
2242
-
2243
- Returns:
2244
- The JSON-decoded response from the API if the deletion is successful.
2245
-
2246
- Raises:
2247
- ValueError: If 'objective_public_id' is None.
2248
- requests.HTTPError: If the HTTP DELETE request returns an unsuccessful status code.
2249
-
2250
- Tags:
2251
- delete, objectives, api, http,
2252
- """
2253
- if objective_public_id is None:
2254
- raise ValueError("Missing required parameter 'objective-public-id'")
2255
- url = f"{self.base_url}/api/v3/objectives/{objective_public_id}"
2256
- query_params = {}
2257
- response = self._delete(url, params=query_params)
2258
- response.raise_for_status()
2259
- return response.json()
2260
-
2261
- def list_objective_epics(self, objective_public_id) -> list[Any]:
2262
- """
2263
- Retrieves a list of epics associated with a specific objective.
2264
-
2265
- Args:
2266
- objective_public_id: The unique public identifier of the objective for which to list epics. Cannot be None.
2267
-
2268
- Returns:
2269
- A list of epic objects associated with the specified objective, parsed from the JSON response.
2270
-
2271
- Raises:
2272
- ValueError: Raised when the required parameter 'objective_public_id' is None.
2273
- HTTPError: Raised when the HTTP request fails or returns an error status code.
2274
-
2275
- Tags:
2276
- list, retrieve, epics, objectives, api,
2277
- """
2278
- if objective_public_id is None:
2279
- raise ValueError("Missing required parameter 'objective-public-id'")
2280
- url = f"{self.base_url}/api/v3/objectives/{objective_public_id}/epics"
2281
- query_params = {}
2282
- response = self._get(url, params=query_params)
2283
- response.raise_for_status()
2284
- return response.json()
2285
-
2286
- def list_projects(self, ) -> list[Any]:
2287
- """
2288
- Retrieves and lists all available projects from the API.
2289
-
2290
- Returns:
2291
- A list of all projects retrieved from the API.
2292
-
2293
- Raises:
2294
- requests.exceptions.HTTPError: Raised if there is a 4xx or 5xx status response from the server.
2295
-
2296
- Tags:
2297
- list, projects, , api-call
2298
- """
2299
- url = f"{self.base_url}/api/v3/projects"
2300
- query_params = {}
2301
- response = self._get(url, params=query_params)
2302
- response.raise_for_status()
2303
- return response.json()
2304
-
2305
- def create_project(self, name, team_id, description=None, color=None, start_time=None, updated_at=None, follower_ids=None, external_id=None, iteration_length=None, abbreviation=None, created_at=None) -> dict[str, Any]:
2306
- """
2307
- Creates a new project with the specified parameters.
2308
-
2309
- Args:
2310
- name: Required. The name of the project.
2311
- team_id: Required. The ID of the team the project belongs to.
2312
- description: Optional. The description of the project.
2313
- color: Optional. The color associated with the project.
2314
- start_time: Optional. The start time of the project.
2315
- updated_at: Optional. The timestamp when the project was last updated.
2316
- follower_ids: Optional. List of IDs of users following the project.
2317
- external_id: Optional. An external identifier for the project.
2318
- iteration_length: Optional. The length of iteration for the project.
2319
- abbreviation: Optional. A short abbreviation for the project.
2320
- created_at: Optional. The timestamp when the project was created.
2321
-
2322
- Returns:
2323
- A dictionary containing the created project's information.
2324
-
2325
- Raises:
2326
- ValueError: Raised when the required parameters 'name' or 'team_id' are not provided.
2327
-
2328
- Tags:
2329
- create, project, management,
2330
- """
2331
- if name is None:
2332
- raise ValueError("Missing required parameter 'name'")
2333
- if team_id is None:
2334
- raise ValueError("Missing required parameter 'team_id'")
2335
- request_body = {
2336
- 'description': description,
2337
- 'color': color,
2338
- 'name': name,
2339
- 'start_time': start_time,
2340
- 'updated_at': updated_at,
2341
- 'follower_ids': follower_ids,
2342
- 'external_id': external_id,
2343
- 'team_id': team_id,
2344
- 'iteration_length': iteration_length,
2345
- 'abbreviation': abbreviation,
2346
- 'created_at': created_at,
2347
- }
2348
- request_body = {k: v for k, v in request_body.items() if v is not None}
2349
- url = f"{self.base_url}/api/v3/projects"
2350
- query_params = {}
2351
- response = self._post(url, data=request_body, params=query_params)
2352
- response.raise_for_status()
2353
- return response.json()
2354
-
2355
- def get_project(self, project_public_id) -> dict[str, Any]:
2356
- """
2357
- Retrieves project information by its public ID.
2358
-
2359
- Args:
2360
- project_public_id: The public identifier of the project to retrieve
2361
-
2362
- Returns:
2363
- A dictionary containing project information retrieved from the API
2364
-
2365
- Raises:
2366
- ValueError: When the required project_public_id parameter is None
2367
- HTTPError: When the HTTP request fails (via raise_for_status)
2368
-
2369
- Tags:
2370
- get, retrieve, project, api,
2371
- """
2372
- if project_public_id is None:
2373
- raise ValueError("Missing required parameter 'project-public-id'")
2374
- url = f"{self.base_url}/api/v3/projects/{project_public_id}"
2375
- query_params = {}
2376
- response = self._get(url, params=query_params)
2377
- response.raise_for_status()
2378
- return response.json()
2379
-
2380
- def update_project(self, project_public_id, description=None, archived=None, days_to_thermometer=None, color=None, name=None, follower_ids=None, show_thermometer=None, team_id=None, abbreviation=None) -> dict[str, Any]:
2381
- """
2382
- Updates a project with the provided parameters.
2383
-
2384
- Args:
2385
- project_public_id: The unique identifier of the project to update.
2386
- description: Optional. New description for the project.
2387
- archived: Optional. Boolean indicating whether the project should be archived.
2388
- days_to_thermometer: Optional. Number of days for the thermometer display.
2389
- color: Optional. Color code for the project.
2390
- name: Optional. New name for the project.
2391
- follower_ids: Optional. List of user IDs who follow this project.
2392
- show_thermometer: Optional. Boolean indicating whether to show the thermometer.
2393
- team_id: Optional. ID of the team associated with this project.
2394
- abbreviation: Optional. Short form abbreviation for the project.
2395
-
2396
- Returns:
2397
- A dictionary containing the updated project information.
2398
-
2399
- Raises:
2400
- ValueError: When project_public_id is None.
2401
- HTTPError: When the API request fails.
2402
-
2403
- Tags:
2404
- update, project, management,
2405
- """
2406
- if project_public_id is None:
2407
- raise ValueError("Missing required parameter 'project-public-id'")
2408
- request_body = {
2409
- 'description': description,
2410
- 'archived': archived,
2411
- 'days_to_thermometer': days_to_thermometer,
2412
- 'color': color,
2413
- 'name': name,
2414
- 'follower_ids': follower_ids,
2415
- 'show_thermometer': show_thermometer,
2416
- 'team_id': team_id,
2417
- 'abbreviation': abbreviation,
2418
- }
2419
- request_body = {k: v for k, v in request_body.items() if v is not None}
2420
- url = f"{self.base_url}/api/v3/projects/{project_public_id}"
2421
- query_params = {}
2422
- response = self._put(url, data=request_body, params=query_params)
2423
- response.raise_for_status()
2424
- return response.json()
2425
-
2426
- def delete_project(self, project_public_id) -> Any:
2427
- """
2428
- Deletes a project using its public ID.
2429
-
2430
- Args:
2431
- project_public_id: The unique public identifier of the project to be deleted.
2432
-
2433
- Returns:
2434
- The JSON response from the API after successful deletion.
2435
-
2436
- Raises:
2437
- ValueError: Raised when the required project_public_id parameter is None.
2438
- HTTPError: Raised when the API request fails (via raise_for_status()).
2439
-
2440
- Tags:
2441
- delete, project, management,
2442
- """
2443
- if project_public_id is None:
2444
- raise ValueError("Missing required parameter 'project-public-id'")
2445
- url = f"{self.base_url}/api/v3/projects/{project_public_id}"
2446
- query_params = {}
2447
- response = self._delete(url, params=query_params)
2448
- response.raise_for_status()
2449
- return response.json()
2450
-
2451
- def list_stories(self, project_public_id, includes_description=None) -> list[Any]:
2452
- """
2453
- Retrieves a list of stories for a specific project, with optional inclusion of story descriptions.
2454
-
2455
- Args:
2456
- project_public_id: The public identifier of the project to list stories for.
2457
- includes_description: Optional; If provided and truthy, includes the description of each story in the response.
2458
-
2459
- Returns:
2460
- A list of story objects for the specified project, as returned by the API.
2461
-
2462
- Raises:
2463
- ValueError: Raised if 'project_public_id' is not provided (None).
2464
- HTTPError: Raised if the HTTP request to the stories API endpoint fails.
2465
-
2466
- Tags:
2467
- list, stories, project, api,
2468
- """
2469
- if project_public_id is None:
2470
- raise ValueError("Missing required parameter 'project-public-id'")
2471
- url = f"{self.base_url}/api/v3/projects/{project_public_id}/stories"
2472
- query_params = {k: v for k, v in [('includes_description', includes_description)] if v is not None}
2473
- response = self._get(url, params=query_params)
2474
- response.raise_for_status()
2475
- return response.json()
2476
-
2477
- def list_repositories(self, ) -> list[Any]:
2478
- """
2479
- Lists all repositories from the API.
2480
-
2481
- Returns:
2482
- A list of repository objects containing repository metadata.
2483
-
2484
- Raises:
2485
- HTTPError: If the HTTP request fails or returns an error status code.
2486
-
2487
- Tags:
2488
- list, repositories, api, get,
2489
- """
2490
- url = f"{self.base_url}/api/v3/repositories"
2491
- query_params = {}
2492
- response = self._get(url, params=query_params)
2493
- response.raise_for_status()
2494
- return response.json()
2495
-
2496
- def get_repository(self, repo_public_id) -> dict[str, Any]:
2497
- """
2498
- Retrieves detailed information about a repository by its public ID.
2499
-
2500
- Args:
2501
- repo_public_id: String representing the public ID of the repository to retrieve.
2502
-
2503
- Returns:
2504
- Dictionary containing repository information with string keys and values of various types.
2505
-
2506
- Raises:
2507
- ValueError: When the required repo_public_id parameter is None.
2508
- HTTPError: When the API request fails (via raise_for_status()).
2509
-
2510
- Tags:
2511
- retrieve, repository, api, get,
2512
- """
2513
- if repo_public_id is None:
2514
- raise ValueError("Missing required parameter 'repo-public-id'")
2515
- url = f"{self.base_url}/api/v3/repositories/{repo_public_id}"
2516
- query_params = {}
2517
- response = self._get(url, params=query_params)
2518
- response.raise_for_status()
2519
- return response.json()
2520
-
2521
- def search(self, query, page_size=None, detail=None, next=None, entity_types=None) -> dict[str, Any]:
2522
- """
2523
- Performs a search operation based on the provided query string and optional parameters like page size and entity types.
2524
-
2525
- Args:
2526
- query: The search query string. This is a required parameter.
2527
- page_size: The number of results to return per page.
2528
- detail: Optional detail parameter for search.
2529
- next: The next page token for pagination.
2530
- entity_types: List of entity types to filter results by.
2531
-
2532
- Returns:
2533
- A JSON response from the search query as a dictionary.
2534
-
2535
- Raises:
2536
- ValueError: Raised if the 'query' parameter is missing.
2537
-
2538
- Tags:
2539
- search, management,
2540
- """
2541
- if query is None:
2542
- raise ValueError("Missing required parameter 'query'")
2543
- url = f"{self.base_url}/api/v3/search"
2544
- query_params = {k: v for k, v in [('query', query), ('page_size', page_size), ('detail', detail), ('next', next), ('entity_types', entity_types)] if v is not None}
2545
- response = self._get(url, params=query_params)
2546
- response.raise_for_status()
2547
- return response.json()
2548
-
2549
- def search_epics(self, query, page_size=None, detail=None, next=None, entity_types=None) -> dict[str, Any]:
2550
- """
2551
- Searches for epics based on the provided query parameters.
2552
-
2553
- Args:
2554
- query: String containing the search query for epics.
2555
- page_size: Optional integer specifying the number of results to return per page.
2556
- detail: Optional parameter determining the level of detail in the response.
2557
- next: Optional parameter for pagination, used to fetch the next page of results.
2558
- entity_types: Optional parameter to filter results by specific entity types.
2559
-
2560
- Returns:
2561
- A dictionary containing the search results with various metadata and epic information.
2562
-
2563
- Raises:
2564
- ValueError: Raised when the required 'query' parameter is None.
2565
- HTTPError: Raised when the HTTP request fails (via raise_for_status()).
2566
-
2567
- Tags:
2568
- search, epics, pagination, api,
2569
- """
2570
- if query is None:
2571
- raise ValueError("Missing required parameter 'query'")
2572
- url = f"{self.base_url}/api/v3/search/epics"
2573
- query_params = {k: v for k, v in [('query', query), ('page_size', page_size), ('detail', detail), ('next', next), ('entity_types', entity_types)] if v is not None}
2574
- response = self._get(url, params=query_params)
2575
- response.raise_for_status()
2576
- return response.json()
2577
-
2578
- def search_iterations(self, query, page_size=None, detail=None, next=None, entity_types=None) -> dict[str, Any]:
2579
- """
2580
- Searches for iterations based on a query and additional parameters.
2581
-
2582
- Args:
2583
- query: The search query string to find iterations. Required parameter.
2584
- page_size: The number of results to return per page. Optional parameter.
2585
- detail: The level of detail to include in the results. Optional parameter.
2586
- next: Token for pagination to get the next page of results. Optional parameter.
2587
- entity_types: Filter results by specific entity types. Optional parameter.
2588
-
2589
- Returns:
2590
- A dictionary containing the search results including iteration data and pagination information.
2591
-
2592
- Raises:
2593
- ValueError: Raised when the required 'query' parameter is None.
2594
- HTTPError: Raised when the HTTP request fails.
2595
-
2596
- Tags:
2597
- search, iterations, pagination,
2598
- """
2599
- if query is None:
2600
- raise ValueError("Missing required parameter 'query'")
2601
- url = f"{self.base_url}/api/v3/search/iterations"
2602
- query_params = {k: v for k, v in [('query', query), ('page_size', page_size), ('detail', detail), ('next', next), ('entity_types', entity_types)] if v is not None}
2603
- response = self._get(url, params=query_params)
2604
- response.raise_for_status()
2605
- return response.json()
2606
-
2607
- def search_milestones(self, query, page_size=None, detail=None, next=None, entity_types=None) -> dict[str, Any]:
2608
- """
2609
- Searches for milestones matching the provided query and returns the results as a dictionary.
2610
-
2611
- Args:
2612
- query: str. The search query used to match milestones. Required.
2613
- page_size: Optional[int]. The maximum number of results to return per page.
2614
- detail: Optional[str]. The level of detail to include in the results.
2615
- next: Optional[str]. A token to retrieve the next page of results.
2616
- entity_types: Optional[str|list[str]]. Filter milestones by specific entity types.
2617
-
2618
- Returns:
2619
- dict[str, Any]: A dictionary containing the search results for milestones.
2620
-
2621
- Raises:
2622
- ValueError: If the 'query' parameter is None.
2623
- requests.HTTPError: If the HTTP request to the milestones API fails.
2624
-
2625
- Tags:
2626
- search, milestones, api, async-job, management,
2627
- """
2628
- if query is None:
2629
- raise ValueError("Missing required parameter 'query'")
2630
- url = f"{self.base_url}/api/v3/search/milestones"
2631
- query_params = {k: v for k, v in [('query', query), ('page_size', page_size), ('detail', detail), ('next', next), ('entity_types', entity_types)] if v is not None}
2632
- response = self._get(url, params=query_params)
2633
- response.raise_for_status()
2634
- return response.json()
2635
-
2636
- def search_objectives(self, query, page_size=None, detail=None, next=None, entity_types=None) -> dict[str, Any]:
2637
- """
2638
- Searches for objectives based on the specified query and returns the search results.
2639
-
2640
- Args:
2641
- query: str. The search string to query objectives. This parameter is required.
2642
- page_size: Optional[int]. The maximum number of results to return per page.
2643
- detail: Optional[bool]. Whether to include detailed information in the results.
2644
- next: Optional[str]. A token to retrieve the next page of results.
2645
- entity_types: Optional[list[str] or str]. Specifies the types of entities to include in the search.
2646
-
2647
- Returns:
2648
- dict[str, Any]: A dictionary containing the search results for objectives.
2649
-
2650
- Raises:
2651
- ValueError: Raised if the required 'query' parameter is missing.
2652
- HTTPError: Raised if the HTTP request to the search API returns an unsuccessful status code.
2653
-
2654
- Tags:
2655
- search, objectives, api,
2656
- """
2657
- if query is None:
2658
- raise ValueError("Missing required parameter 'query'")
2659
- url = f"{self.base_url}/api/v3/search/objectives"
2660
- query_params = {k: v for k, v in [('query', query), ('page_size', page_size), ('detail', detail), ('next', next), ('entity_types', entity_types)] if v is not None}
2661
- response = self._get(url, params=query_params)
2662
- response.raise_for_status()
2663
- return response.json()
2664
-
2665
- def search_stories(self, query, page_size=None, detail=None, next=None, entity_types=None) -> dict[str, Any]:
2666
- """
2667
- Searches for stories matching the given query and optional filters, returning paginated results from the stories API.
2668
-
2669
- Args:
2670
- query: str. The search query string to filter stories. Required.
2671
- page_size: Optional[int]. Maximum number of stories to return per page. Defaults to API settings if not provided.
2672
- detail: Optional[Any]. Specifies the level of detail to include in the returned stories.
2673
- next: Optional[str]. A token for fetching the next page of results.
2674
- entity_types: Optional[Any]. Filter stories by specific entity types.
2675
-
2676
- Returns:
2677
- dict[str, Any]: Parsed JSON response containing search results and pagination data.
2678
-
2679
- Raises:
2680
- ValueError: If the required parameter 'query' is not provided.
2681
- requests.HTTPError: If the HTTP request to the stories API fails with a non-success status code.
2682
-
2683
- Tags:
2684
- search, stories, api,
2685
- """
2686
- if query is None:
2687
- raise ValueError("Missing required parameter 'query'")
2688
- url = f"{self.base_url}/api/v3/search/stories"
2689
- query_params = {k: v for k, v in [('query', query), ('page_size', page_size), ('detail', detail), ('next', next), ('entity_types', entity_types)] if v is not None}
2690
- response = self._get(url, params=query_params)
2691
- response.raise_for_status()
2692
- return response.json()
2693
-
2694
- def create_story(self, name, description=None, archived=None, story_links=None, labels=None, story_type=None, custom_fields=None, move_to=None, file_ids=None, source_task_id=None, completed_at_override=None, comments=None, epic_id=None, story_template_id=None, external_links=None, sub_tasks=None, requested_by_id=None, iteration_id=None, tasks=None, started_at_override=None, group_id=None, workflow_state_id=None, updated_at=None, follower_ids=None, owner_ids=None, external_id=None, estimate=None, project_id=None, linked_file_ids=None, deadline=None, created_at=None) -> dict[str, Any]:
2695
- """
2696
- Creates a new story with the specified attributes and returns the created story's data.
2697
-
2698
- Args:
2699
- name: str. The name or title of the story. This parameter is required.
2700
- description: Optional[str]. The description or details of the story.
2701
- archived: Optional[bool]. Indicates if the story is archived.
2702
- story_links: Optional[list]. List of linked stories or references.
2703
- labels: Optional[list]. List of label IDs or names to associate with the story.
2704
- story_type: Optional[str]. The type of story (e.g., feature, bug, chore).
2705
- custom_fields: Optional[dict]. Dictionary of custom field values for the story.
2706
- move_to: Optional[str]. The workflow state to move the story to upon creation.
2707
- file_ids: Optional[list]. IDs of files attached to the story.
2708
- source_task_id: Optional[str]. The ID of the source task if the story is created from a task.
2709
- completed_at_override: Optional[str]. Datetime string to override the completed timestamp.
2710
- comments: Optional[list]. List of comments to add to the story upon creation.
2711
- epic_id: Optional[str]. The ID of the epic to associate with the story.
2712
- story_template_id: Optional[str]. The ID of the story template to use.
2713
- external_links: Optional[list]. List of external links to associate with the story.
2714
- sub_tasks: Optional[list]. List of sub-tasks for the story.
2715
- requested_by_id: Optional[str]. ID of the user who requested the story.
2716
- iteration_id: Optional[str]. The ID of the iteration associated with the story.
2717
- tasks: Optional[list]. List of tasks linked to the story.
2718
- started_at_override: Optional[str]. Datetime string to override the started timestamp.
2719
- group_id: Optional[str]. The ID of the group associated with the story.
2720
- workflow_state_id: Optional[str]. The workflow state ID for the story.
2721
- updated_at: Optional[str]. Datetime string to override the updated timestamp.
2722
- follower_ids: Optional[list]. IDs of users following the story.
2723
- owner_ids: Optional[list]. IDs of users owning the story.
2724
- external_id: Optional[str]. External reference ID for the story.
2725
- estimate: Optional[int]. Estimated effort or points for the story.
2726
- project_id: Optional[str]. The ID of the project this story belongs to.
2727
- linked_file_ids: Optional[list]. IDs of files linked to the story.
2728
- deadline: Optional[str]. Deadline datetime for the story.
2729
- created_at: Optional[str]. Datetime string to override the created timestamp.
2730
-
2731
- Returns:
2732
- dict[str, Any]: A dictionary representing the created story's data as returned by the API.
2733
-
2734
- Raises:
2735
- ValueError: If the required parameter 'name' is not provided.
2736
- requests.HTTPError: If the API request fails or returns an error response.
2737
-
2738
- Tags:
2739
- create, story, api, management,
2740
- """
2741
- if name is None:
2742
- raise ValueError("Missing required parameter 'name'")
2743
- request_body = {
2744
- 'description': description,
2745
- 'archived': archived,
2746
- 'story_links': story_links,
2747
- 'labels': labels,
2748
- 'story_type': story_type,
2749
- 'custom_fields': custom_fields,
2750
- 'move_to': move_to,
2751
- 'file_ids': file_ids,
2752
- 'source_task_id': source_task_id,
2753
- 'completed_at_override': completed_at_override,
2754
- 'name': name,
2755
- 'comments': comments,
2756
- 'epic_id': epic_id,
2757
- 'story_template_id': story_template_id,
2758
- 'external_links': external_links,
2759
- 'sub_tasks': sub_tasks,
2760
- 'requested_by_id': requested_by_id,
2761
- 'iteration_id': iteration_id,
2762
- 'tasks': tasks,
2763
- 'started_at_override': started_at_override,
2764
- 'group_id': group_id,
2765
- 'workflow_state_id': workflow_state_id,
2766
- 'updated_at': updated_at,
2767
- 'follower_ids': follower_ids,
2768
- 'owner_ids': owner_ids,
2769
- 'external_id': external_id,
2770
- 'estimate': estimate,
2771
- 'project_id': project_id,
2772
- 'linked_file_ids': linked_file_ids,
2773
- 'deadline': deadline,
2774
- 'created_at': created_at,
2775
- }
2776
- request_body = {k: v for k, v in request_body.items() if v is not None}
2777
- url = f"{self.base_url}/api/v3/stories"
2778
- query_params = {}
2779
- response = self._post(url, data=request_body, params=query_params)
2780
- response.raise_for_status()
2781
- return response.json()
2782
-
2783
- def update_multiple_stories(self, story_ids, archived=None, story_type=None, move_to=None, follower_ids_add=None, epic_id=None, external_links=None, follower_ids_remove=None, requested_by_id=None, iteration_id=None, custom_fields_remove=None, labels_add=None, group_id=None, workflow_state_id=None, before_id=None, estimate=None, after_id=None, owner_ids_remove=None, custom_fields_add=None, project_id=None, labels_remove=None, deadline=None, owner_ids_add=None) -> list[Any]:
2784
- """
2785
- Updates multiple stories in bulk with various fields and configuration changes.
2786
-
2787
- Args:
2788
- story_ids: List of story IDs to update. Must not be None.
2789
- archived: Whether to archive the stories (optional).
2790
- story_type: The type to assign to the stories (optional).
2791
- move_to: Identifier to move stories to a different grouping, such as a workflow state (optional).
2792
- follower_ids_add: List of follower IDs to add to the stories (optional).
2793
- epic_id: Epic ID to associate the stories with (optional).
2794
- external_links: List of external links to add to the stories (optional).
2795
- follower_ids_remove: List of follower IDs to remove from the stories (optional).
2796
- requested_by_id: ID of the user making the request (optional).
2797
- iteration_id: Iteration ID to move the stories into (optional).
2798
- custom_fields_remove: Custom field IDs to remove from the stories (optional).
2799
- labels_add: List of label IDs to add to the stories (optional).
2800
- group_id: Group ID to associate with the stories (optional).
2801
- workflow_state_id: Workflow state ID to move the stories to (optional).
2802
- before_id: ID of the story that the updated stories should be placed before (optional).
2803
- estimate: Estimate value to set on the stories (optional).
2804
- after_id: ID of the story that the updated stories should be placed after (optional).
2805
- owner_ids_remove: List of owner IDs to remove from the stories (optional).
2806
- custom_fields_add: Custom field values to add to the stories (optional).
2807
- project_id: Project ID to associate the stories with (optional).
2808
- labels_remove: List of label IDs to remove from the stories (optional).
2809
- deadline: Deadline datetime to set for the stories (optional).
2810
- owner_ids_add: List of owner IDs to add to the stories (optional).
2811
-
2812
- Returns:
2813
- A list of story objects representing the updated stories.
2814
-
2815
- Raises:
2816
- ValueError: If 'story_ids' is None.
2817
- requests.HTTPError: If the HTTP request to update the stories fails.
2818
-
2819
- Tags:
2820
- update, stories, bulk, management, api,
2821
- """
2822
- if story_ids is None:
2823
- raise ValueError("Missing required parameter 'story_ids'")
2824
- request_body = {
2825
- 'archived': archived,
2826
- 'story_ids': story_ids,
2827
- 'story_type': story_type,
2828
- 'move_to': move_to,
2829
- 'follower_ids_add': follower_ids_add,
2830
- 'epic_id': epic_id,
2831
- 'external_links': external_links,
2832
- 'follower_ids_remove': follower_ids_remove,
2833
- 'requested_by_id': requested_by_id,
2834
- 'iteration_id': iteration_id,
2835
- 'custom_fields_remove': custom_fields_remove,
2836
- 'labels_add': labels_add,
2837
- 'group_id': group_id,
2838
- 'workflow_state_id': workflow_state_id,
2839
- 'before_id': before_id,
2840
- 'estimate': estimate,
2841
- 'after_id': after_id,
2842
- 'owner_ids_remove': owner_ids_remove,
2843
- 'custom_fields_add': custom_fields_add,
2844
- 'project_id': project_id,
2845
- 'labels_remove': labels_remove,
2846
- 'deadline': deadline,
2847
- 'owner_ids_add': owner_ids_add,
2848
- }
2849
- request_body = {k: v for k, v in request_body.items() if v is not None}
2850
- url = f"{self.base_url}/api/v3/stories/bulk"
2851
- query_params = {}
2852
- response = self._put(url, data=request_body, params=query_params)
2853
- response.raise_for_status()
2854
- return response.json()
2855
-
2856
- def create_multiple_stories(self, stories) -> list[Any]:
2857
- """
2858
- Creates multiple stories in bulk using the API.
2859
-
2860
- Args:
2861
- stories: A list of story objects to be created in bulk.
2862
-
2863
- Returns:
2864
- A list containing the created stories' data as returned by the API.
2865
-
2866
- Raises:
2867
- ValueError: Raised when the required 'stories' parameter is None.
2868
- HTTPError: Raised when the API request fails with a non-2xx status code.
2869
-
2870
- Tags:
2871
- create, bulk, stories, api,
2872
- """
2873
- if stories is None:
2874
- raise ValueError("Missing required parameter 'stories'")
2875
- request_body = {
2876
- 'stories': stories,
2877
- }
2878
- request_body = {k: v for k, v in request_body.items() if v is not None}
2879
- url = f"{self.base_url}/api/v3/stories/bulk"
2880
- query_params = {}
2881
- response = self._post(url, data=request_body, params=query_params)
2882
- response.raise_for_status()
2883
- return response.json()
2884
-
2885
- def create_story_from_template(self, story_template_id, description=None, archived=None, story_links=None, labels=None, external_links_add=None, story_type=None, custom_fields=None, move_to=None, file_ids=None, source_task_id=None, completed_at_override=None, name=None, file_ids_add=None, file_ids_remove=None, comments=None, follower_ids_add=None, epic_id=None, external_links=None, follower_ids_remove=None, sub_tasks=None, linked_file_ids_remove=None, requested_by_id=None, iteration_id=None, custom_fields_remove=None, tasks=None, started_at_override=None, labels_add=None, group_id=None, workflow_state_id=None, updated_at=None, follower_ids=None, owner_ids=None, external_id=None, estimate=None, owner_ids_remove=None, custom_fields_add=None, project_id=None, linked_file_ids_add=None, linked_file_ids=None, labels_remove=None, deadline=None, owner_ids_add=None, created_at=None, external_links_remove=None) -> dict[str, Any]:
2886
- """
2887
- Creates a new story from an existing story template.
2888
-
2889
- Args:
2890
- story_template_id: The ID of the story template to use as a base for the new story. Required.
2891
- description: The description of the story.
2892
- archived: Whether the story is archived or not.
2893
- story_links: Links to other stories.
2894
- labels: Labels to associate with the story.
2895
- external_links_add: External links to add to the story.
2896
- story_type: The type of the story.
2897
- custom_fields: Custom fields for the story.
2898
- move_to: Position to move the story to.
2899
- file_ids: IDs of files attached to the story.
2900
- source_task_id: ID of the source task.
2901
- completed_at_override: Override for the completion date.
2902
- name: The name of the story.
2903
- file_ids_add: File IDs to add to the story.
2904
- file_ids_remove: File IDs to remove from the story.
2905
- comments: Comments on the story.
2906
- follower_ids_add: IDs of followers to add to the story.
2907
- epic_id: ID of the epic this story belongs to.
2908
- external_links: External links associated with the story.
2909
- follower_ids_remove: IDs of followers to remove from the story.
2910
- sub_tasks: Sub-tasks of the story.
2911
- linked_file_ids_remove: IDs of linked files to remove.
2912
- requested_by_id: ID of the user who requested the story.
2913
- iteration_id: ID of the iteration this story belongs to.
2914
- custom_fields_remove: Custom fields to remove from the story.
2915
- tasks: Tasks associated with the story.
2916
- started_at_override: Override for the start date.
2917
- labels_add: Labels to add to the story.
2918
- group_id: ID of the group this story belongs to.
2919
- workflow_state_id: ID of the workflow state for this story.
2920
- updated_at: Timestamp of when the story was last updated.
2921
- follower_ids: IDs of users following this story.
2922
- owner_ids: IDs of the story owners.
2923
- external_id: External identifier for the story.
2924
- estimate: Estimate value for the story.
2925
- owner_ids_remove: IDs of owners to remove from the story.
2926
- custom_fields_add: Custom fields to add to the story.
2927
- project_id: ID of the project this story belongs to.
2928
- linked_file_ids_add: IDs of linked files to add.
2929
- linked_file_ids: IDs of files linked to the story.
2930
- labels_remove: Labels to remove from the story.
2931
- deadline: Deadline for the story.
2932
- owner_ids_add: IDs of owners to add to the story.
2933
- created_at: Timestamp of when the story was created.
2934
- external_links_remove: External links to remove from the story.
2935
-
2936
- Returns:
2937
- A dictionary containing the created story data.
2938
-
2939
- Raises:
2940
- ValueError: Raised when the required parameter 'story_template_id' is None.
2941
-
2942
- Tags:
2943
- create, template, story,
2944
- """
2945
- if story_template_id is None:
2946
- raise ValueError("Missing required parameter 'story_template_id'")
2947
- request_body = {
2948
- 'description': description,
2949
- 'archived': archived,
2950
- 'story_links': story_links,
2951
- 'labels': labels,
2952
- 'external_links_add': external_links_add,
2953
- 'story_type': story_type,
2954
- 'custom_fields': custom_fields,
2955
- 'move_to': move_to,
2956
- 'file_ids': file_ids,
2957
- 'source_task_id': source_task_id,
2958
- 'completed_at_override': completed_at_override,
2959
- 'name': name,
2960
- 'file_ids_add': file_ids_add,
2961
- 'file_ids_remove': file_ids_remove,
2962
- 'comments': comments,
2963
- 'follower_ids_add': follower_ids_add,
2964
- 'epic_id': epic_id,
2965
- 'story_template_id': story_template_id,
2966
- 'external_links': external_links,
2967
- 'follower_ids_remove': follower_ids_remove,
2968
- 'sub_tasks': sub_tasks,
2969
- 'linked_file_ids_remove': linked_file_ids_remove,
2970
- 'requested_by_id': requested_by_id,
2971
- 'iteration_id': iteration_id,
2972
- 'custom_fields_remove': custom_fields_remove,
2973
- 'tasks': tasks,
2974
- 'started_at_override': started_at_override,
2975
- 'labels_add': labels_add,
2976
- 'group_id': group_id,
2977
- 'workflow_state_id': workflow_state_id,
2978
- 'updated_at': updated_at,
2979
- 'follower_ids': follower_ids,
2980
- 'owner_ids': owner_ids,
2981
- 'external_id': external_id,
2982
- 'estimate': estimate,
2983
- 'owner_ids_remove': owner_ids_remove,
2984
- 'custom_fields_add': custom_fields_add,
2985
- 'project_id': project_id,
2986
- 'linked_file_ids_add': linked_file_ids_add,
2987
- 'linked_file_ids': linked_file_ids,
2988
- 'labels_remove': labels_remove,
2989
- 'deadline': deadline,
2990
- 'owner_ids_add': owner_ids_add,
2991
- 'created_at': created_at,
2992
- 'external_links_remove': external_links_remove,
2993
- }
2994
- request_body = {k: v for k, v in request_body.items() if v is not None}
2995
- url = f"{self.base_url}/api/v3/stories/from-template"
2996
- query_params = {}
2997
- response = self._post(url, data=request_body, params=query_params)
2998
- response.raise_for_status()
2999
- return response.json()
3000
-
3001
- def search_stories_old(self, archived=None, owner_id=None, story_type=None, epic_ids=None, project_ids=None, updated_at_end=None, completed_at_end=None, workflow_state_types=None, deadline_end=None, created_at_start=None, epic_id=None, label_name=None, requested_by_id=None, iteration_id=None, label_ids=None, group_id=None, workflow_state_id=None, iteration_ids=None, created_at_end=None, deadline_start=None, group_ids=None, owner_ids=None, external_id=None, includes_description=None, estimate=None, project_id=None, completed_at_start=None, updated_at_start=None) -> list[Any]:
3002
- """
3003
- Searches for stories based on various filter criteria.
3004
-
3005
- Args:
3006
- archived: Whether to include archived stories.
3007
- owner_id: ID of the story owner.
3008
- story_type: Type of story to search for.
3009
- epic_ids: List of epic IDs.
3010
- project_ids: List of project IDs.
3011
- updated_at_end: End timestamp for story updates.
3012
- completed_at_end: End timestamp for story completion.
3013
- workflow_state_types: Types of workflow states.
3014
- deadline_end: End deadline for stories.
3015
- created_at_start: Start timestamp for story creation.
3016
- epic_id: Single epic ID.
3017
- label_name: Name of the label to filter by.
3018
- requested_by_id: ID of the user who requested the story.
3019
- iteration_id: Single iteration ID.
3020
- label_ids: List of label IDs.
3021
- group_id: Single group ID.
3022
- workflow_state_id: Single workflow state ID.
3023
- iteration_ids: List of iteration IDs.
3024
- created_at_end: End timestamp for story creation.
3025
- deadline_start: Start deadline for stories.
3026
- group_ids: List of group IDs.
3027
- owner_ids: List of owner IDs.
3028
- external_id: External ID of the story.
3029
- includes_description: Whether the story includes a description.
3030
- estimate: Estimate of the story.
3031
- project_id: Single project ID.
3032
- completed_at_start: Start timestamp for story completion.
3033
- updated_at_start: Start timestamp for story updates.
3034
-
3035
- Returns:
3036
- A list of stories matching the specified criteria.
3037
-
3038
- Raises:
3039
- HTTPError: Raised if the HTTP request to the API fails.
3040
-
3041
- Tags:
3042
- search, story, management,
3043
- """
3044
- request_body = {
3045
- 'archived': archived,
3046
- 'owner_id': owner_id,
3047
- 'story_type': story_type,
3048
- 'epic_ids': epic_ids,
3049
- 'project_ids': project_ids,
3050
- 'updated_at_end': updated_at_end,
3051
- 'completed_at_end': completed_at_end,
3052
- 'workflow_state_types': workflow_state_types,
3053
- 'deadline_end': deadline_end,
3054
- 'created_at_start': created_at_start,
3055
- 'epic_id': epic_id,
3056
- 'label_name': label_name,
3057
- 'requested_by_id': requested_by_id,
3058
- 'iteration_id': iteration_id,
3059
- 'label_ids': label_ids,
3060
- 'group_id': group_id,
3061
- 'workflow_state_id': workflow_state_id,
3062
- 'iteration_ids': iteration_ids,
3063
- 'created_at_end': created_at_end,
3064
- 'deadline_start': deadline_start,
3065
- 'group_ids': group_ids,
3066
- 'owner_ids': owner_ids,
3067
- 'external_id': external_id,
3068
- 'includes_description': includes_description,
3069
- 'estimate': estimate,
3070
- 'project_id': project_id,
3071
- 'completed_at_start': completed_at_start,
3072
- 'updated_at_start': updated_at_start,
3073
- }
3074
- request_body = {k: v for k, v in request_body.items() if v is not None}
3075
- url = f"{self.base_url}/api/v3/stories/search"
3076
- query_params = {}
3077
- response = self._post(url, data=request_body, params=query_params)
3078
- response.raise_for_status()
3079
- return response.json()
3080
-
3081
- def get_story(self, story_public_id) -> dict[str, Any]:
3082
- """
3083
- Retrieves a story from the API based on its public ID
3084
-
3085
- Args:
3086
- story_public_id: The public ID of the story to fetch
3087
-
3088
- Returns:
3089
- A dictionary containing the story data
3090
-
3091
- Raises:
3092
- ValueError: Raised when the required 'story_public_id' parameter is missing
3093
-
3094
- Tags:
3095
- fetch, story-management,
3096
- """
3097
- if story_public_id is None:
3098
- raise ValueError("Missing required parameter 'story-public-id'")
3099
- url = f"{self.base_url}/api/v3/stories/{story_public_id}"
3100
- query_params = {}
3101
- response = self._get(url, params=query_params)
3102
- response.raise_for_status()
3103
- return response.json()
3104
-
3105
- def update_story(self, story_public_id, description=None, archived=None, labels=None, pull_request_ids=None, story_type=None, custom_fields=None, move_to=None, file_ids=None, completed_at_override=None, name=None, epic_id=None, external_links=None, branch_ids=None, commit_ids=None, requested_by_id=None, iteration_id=None, started_at_override=None, group_id=None, workflow_state_id=None, follower_ids=None, owner_ids=None, before_id=None, estimate=None, after_id=None, project_id=None, linked_file_ids=None, deadline=None) -> dict[str, Any]:
3106
- """
3107
- Updates a story in the project management system with the specified attributes.
3108
-
3109
- Args:
3110
- story_public_id: The unique identifier of the story to update.
3111
- description: Optional description text for the story.
3112
- archived: Optional boolean indicating whether the story is archived.
3113
- labels: Optional list of labels to assign to the story.
3114
- pull_request_ids: Optional list of associated pull request IDs.
3115
- story_type: Optional type of the story (e.g., feature, bug, chore).
3116
- custom_fields: Optional dictionary of custom field values.
3117
- move_to: Optional location identifier to move the story to.
3118
- file_ids: Optional list of file IDs to attach to the story.
3119
- completed_at_override: Optional timestamp to override the completion date.
3120
- name: Optional new name/title for the story.
3121
- epic_id: Optional ID of the epic to associate this story with.
3122
- external_links: Optional list of external links related to the story.
3123
- branch_ids: Optional list of branch IDs associated with the story.
3124
- commit_ids: Optional list of commit IDs associated with the story.
3125
- requested_by_id: Optional ID of the user who requested the story.
3126
- iteration_id: Optional ID of the iteration to assign this story to.
3127
- started_at_override: Optional timestamp to override the start date.
3128
- group_id: Optional ID of the group to assign this story to.
3129
- workflow_state_id: Optional ID of the workflow state to assign.
3130
- follower_ids: Optional list of user IDs to follow the story.
3131
- owner_ids: Optional list of user IDs to own the story.
3132
- before_id: Optional story ID to position this story before.
3133
- estimate: Optional estimate value for the story.
3134
- after_id: Optional story ID to position this story after.
3135
- project_id: Optional ID of the project to move the story to.
3136
- linked_file_ids: Optional list of linked file IDs.
3137
- deadline: Optional deadline date for the story.
3138
-
3139
- Returns:
3140
- A dictionary containing the updated story data from the API response.
3141
-
3142
- Raises:
3143
- ValueError: When the required parameter 'story_public_id' is None.
3144
- HTTPError: When the API request fails or returns an error status code.
3145
-
3146
- Tags:
3147
- update, story, management,
3148
- """
3149
- if story_public_id is None:
3150
- raise ValueError("Missing required parameter 'story-public-id'")
3151
- request_body = {
3152
- 'description': description,
3153
- 'archived': archived,
3154
- 'labels': labels,
3155
- 'pull_request_ids': pull_request_ids,
3156
- 'story_type': story_type,
3157
- 'custom_fields': custom_fields,
3158
- 'move_to': move_to,
3159
- 'file_ids': file_ids,
3160
- 'completed_at_override': completed_at_override,
3161
- 'name': name,
3162
- 'epic_id': epic_id,
3163
- 'external_links': external_links,
3164
- 'branch_ids': branch_ids,
3165
- 'commit_ids': commit_ids,
3166
- 'requested_by_id': requested_by_id,
3167
- 'iteration_id': iteration_id,
3168
- 'started_at_override': started_at_override,
3169
- 'group_id': group_id,
3170
- 'workflow_state_id': workflow_state_id,
3171
- 'follower_ids': follower_ids,
3172
- 'owner_ids': owner_ids,
3173
- 'before_id': before_id,
3174
- 'estimate': estimate,
3175
- 'after_id': after_id,
3176
- 'project_id': project_id,
3177
- 'linked_file_ids': linked_file_ids,
3178
- 'deadline': deadline,
3179
- }
3180
- request_body = {k: v for k, v in request_body.items() if v is not None}
3181
- url = f"{self.base_url}/api/v3/stories/{story_public_id}"
3182
- query_params = {}
3183
- response = self._put(url, data=request_body, params=query_params)
3184
- response.raise_for_status()
3185
- return response.json()
3186
-
3187
- def delete_story(self, story_public_id) -> Any:
3188
- """
3189
- Deletes a story using its public ID.
3190
-
3191
- Args:
3192
- story_public_id: The public identifier of the story to be deleted.
3193
-
3194
- Returns:
3195
- The JSON response from the API after successful deletion.
3196
-
3197
- Raises:
3198
- ValueError: Raised when the required story_public_id parameter is None.
3199
- HTTPError: Raised when the API request fails (via raise_for_status()).
3200
-
3201
- Tags:
3202
- delete, story, api,
3203
- """
3204
- if story_public_id is None:
3205
- raise ValueError("Missing required parameter 'story-public-id'")
3206
- url = f"{self.base_url}/api/v3/stories/{story_public_id}"
3207
- query_params = {}
3208
- response = self._delete(url, params=query_params)
3209
- response.raise_for_status()
3210
- return response.json()
3211
-
3212
- def list_story_comment(self, story_public_id) -> list[Any]:
3213
- """
3214
- Retrieves a list of comments for a specific story.
3215
-
3216
- Args:
3217
- story_public_id: The public identifier of the story for which to retrieve comments.
3218
-
3219
- Returns:
3220
- A list of comment objects associated with the specified story.
3221
-
3222
- Raises:
3223
- ValueError: When the required 'story_public_id' parameter is None.
3224
- HTTPError: When the server returns an error response.
3225
-
3226
- Tags:
3227
- list, retrieve, comments, story
3228
- """
3229
- if story_public_id is None:
3230
- raise ValueError("Missing required parameter 'story-public-id'")
3231
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/comments"
3232
- query_params = {}
3233
- response = self._get(url, params=query_params)
3234
- response.raise_for_status()
3235
- return response.json()
3236
-
3237
- def create_story_comment(self, story_public_id, text, author_id=None, created_at=None, updated_at=None, external_id=None, parent_id=None) -> dict[str, Any]:
3238
- """
3239
- Creates a new comment on a story by sending a POST request with the comment details to the specified API endpoint.
3240
-
3241
- Args:
3242
- story_public_id: The public ID of the story to which the comment is to be added.
3243
- text: The content of the comment.
3244
- author_id: Optional: The ID of the author of the comment.
3245
- created_at: Optional: The timestamp when the comment was created.
3246
- updated_at: Optional: The timestamp when the comment was last updated.
3247
- external_id: Optional: An external identifier for the comment.
3248
- parent_id: Optional: The ID of the parent comment if this is a reply.
3249
-
3250
- Returns:
3251
- A dictionary containing the details of the newly created comment.
3252
-
3253
- Raises:
3254
- ValueError: Raised if either 'story_public_id' or 'text' is missing.
3255
-
3256
- Tags:
3257
- create, story-comment, async-job, management,
3258
- """
3259
- if story_public_id is None:
3260
- raise ValueError("Missing required parameter 'story-public-id'")
3261
- if text is None:
3262
- raise ValueError("Missing required parameter 'text'")
3263
- request_body = {
3264
- 'text': text,
3265
- 'author_id': author_id,
3266
- 'created_at': created_at,
3267
- 'updated_at': updated_at,
3268
- 'external_id': external_id,
3269
- 'parent_id': parent_id,
3270
- }
3271
- request_body = {k: v for k, v in request_body.items() if v is not None}
3272
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/comments"
3273
- query_params = {}
3274
- response = self._post(url, data=request_body, params=query_params)
3275
- response.raise_for_status()
3276
- return response.json()
3277
-
3278
- def get_story_comment(self, story_public_id, comment_public_id) -> dict[str, Any]:
3279
- """
3280
- Retrieves a specific comment from a story using the API.
3281
-
3282
- Args:
3283
- story_public_id: The unique public identifier of the story containing the comment.
3284
- comment_public_id: The unique public identifier of the comment to retrieve.
3285
-
3286
- Returns:
3287
- A dictionary containing the comment data from the API response.
3288
-
3289
- Raises:
3290
- ValueError: If story_public_id or comment_public_id is None.
3291
- HTTPError: If the API request fails.
3292
-
3293
- Tags:
3294
- retrieve, comment, story, api, get
3295
- """
3296
- if story_public_id is None:
3297
- raise ValueError("Missing required parameter 'story-public-id'")
3298
- if comment_public_id is None:
3299
- raise ValueError("Missing required parameter 'comment-public-id'")
3300
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/comments/{comment_public_id}"
3301
- query_params = {}
3302
- response = self._get(url, params=query_params)
3303
- response.raise_for_status()
3304
- return response.json()
3305
-
3306
- def update_story_comment(self, story_public_id, comment_public_id, text) -> dict[str, Any]:
3307
- """
3308
- Updates a story comment with new text based on the provided story and comment public IDs.
3309
-
3310
- Args:
3311
- story_public_id: The public ID of the story the comment belongs to.
3312
- comment_public_id: The public ID of the comment to be updated.
3313
- text: The new text for the comment.
3314
-
3315
- Returns:
3316
- A dictionary containing the updated comment data.
3317
-
3318
- Raises:
3319
- ValueError: Raised when any of the required parameters (story_public_id, comment_public_id, or text) are missing.
3320
-
3321
- Tags:
3322
- update, management,
3323
- """
3324
- if story_public_id is None:
3325
- raise ValueError("Missing required parameter 'story-public-id'")
3326
- if comment_public_id is None:
3327
- raise ValueError("Missing required parameter 'comment-public-id'")
3328
- if text is None:
3329
- raise ValueError("Missing required parameter 'text'")
3330
- request_body = {
3331
- 'text': text,
3332
- }
3333
- request_body = {k: v for k, v in request_body.items() if v is not None}
3334
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/comments/{comment_public_id}"
3335
- query_params = {}
3336
- response = self._put(url, data=request_body, params=query_params)
3337
- response.raise_for_status()
3338
- return response.json()
3339
-
3340
- def delete_story_comment(self, story_public_id, comment_public_id) -> Any:
3341
- """
3342
- Deletes a specific comment from a story using the provided story and comment public IDs.
3343
-
3344
- Args:
3345
- story_public_id: The public identifier of the story containing the comment to delete.
3346
- comment_public_id: The public identifier of the comment to be deleted.
3347
-
3348
- Returns:
3349
- A JSON object containing the server's response to the delete operation.
3350
-
3351
- Raises:
3352
- ValueError: Raised if either 'story_public_id' or 'comment_public_id' is None.
3353
- HTTPError: Raised if the HTTP request to delete the comment fails (non-success status code).
3354
-
3355
- Tags:
3356
- delete, comment-management, api,
3357
- """
3358
- if story_public_id is None:
3359
- raise ValueError("Missing required parameter 'story-public-id'")
3360
- if comment_public_id is None:
3361
- raise ValueError("Missing required parameter 'comment-public-id'")
3362
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/comments/{comment_public_id}"
3363
- query_params = {}
3364
- response = self._delete(url, params=query_params)
3365
- response.raise_for_status()
3366
- return response.json()
3367
-
3368
- def create_story_reaction(self, story_public_id, comment_public_id, emoji) -> list[Any]:
3369
- """
3370
- Creates a reaction with an emoji to a comment on a story.
3371
-
3372
- Args:
3373
- story_public_id: Public ID of the story containing the comment to react to.
3374
- comment_public_id: Public ID of the comment to add the reaction to.
3375
- emoji: The emoji to use as the reaction.
3376
-
3377
- Returns:
3378
- A list containing details of the created reaction.
3379
-
3380
- Raises:
3381
- ValueError: If any of the required parameters (story_public_id, comment_public_id, or emoji) is None.
3382
-
3383
- Tags:
3384
- create, reaction, comment, story, emoji,
3385
- """
3386
- if story_public_id is None:
3387
- raise ValueError("Missing required parameter 'story-public-id'")
3388
- if comment_public_id is None:
3389
- raise ValueError("Missing required parameter 'comment-public-id'")
3390
- if emoji is None:
3391
- raise ValueError("Missing required parameter 'emoji'")
3392
- request_body = {
3393
- 'emoji': emoji,
3394
- }
3395
- request_body = {k: v for k, v in request_body.items() if v is not None}
3396
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/comments/{comment_public_id}/reactions"
3397
- query_params = {}
3398
- response = self._post(url, data=request_body, params=query_params)
3399
- response.raise_for_status()
3400
- return response.json()
3401
-
3402
- def unlink_comment_thread_from_slack(self, story_public_id, comment_public_id) -> dict[str, Any]:
3403
- """
3404
- Unlinks a comment thread from Slack for a specific story.
3405
-
3406
- Args:
3407
- story_public_id: The public ID of the story containing the comment thread.
3408
- comment_public_id: The public ID of the comment thread to unlink from Slack.
3409
-
3410
- Returns:
3411
- A dictionary containing the API response data after unlinking the comment thread.
3412
-
3413
- Raises:
3414
- ValueError: When either story_public_id or comment_public_id is None.
3415
- HTTPError: When the API request fails.
3416
-
3417
- Tags:
3418
- unlink, comment, slack, api, management,
3419
- """
3420
- if story_public_id is None:
3421
- raise ValueError("Missing required parameter 'story-public-id'")
3422
- if comment_public_id is None:
3423
- raise ValueError("Missing required parameter 'comment-public-id'")
3424
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/comments/{comment_public_id}/unlink-from-slack"
3425
- query_params = {}
3426
- response = self._post(url, data={}, params=query_params)
3427
- response.raise_for_status()
3428
- return response.json()
3429
-
3430
- def story_history(self, story_public_id) -> list[Any]:
3431
- """
3432
- Retrieves the full change history for a specified story by its public ID.
3433
-
3434
- Args:
3435
- story_public_id: The public identifier of the story whose history is to be fetched. Must not be None.
3436
-
3437
- Returns:
3438
- A list of history records for the specified story, as returned from the API.
3439
-
3440
- Raises:
3441
- ValueError: If 'story_public_id' is None.
3442
- HTTPError: If the HTTP request to the history API fails or returns an unsuccessful status code.
3443
-
3444
- Tags:
3445
- get, history, story, , api, management
3446
- """
3447
- if story_public_id is None:
3448
- raise ValueError("Missing required parameter 'story-public-id'")
3449
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/history"
3450
- query_params = {}
3451
- response = self._get(url, params=query_params)
3452
- response.raise_for_status()
3453
- return response.json()
3454
-
3455
- def create_task(self, story_public_id, description, complete=None, owner_ids=None, external_id=None, created_at=None, updated_at=None) -> dict[str, Any]:
3456
- """
3457
- Creates a task within a specified story.
3458
-
3459
- Args:
3460
- story_public_id: The public identifier of the story to which the task will be added.
3461
- description: The text description of the task.
3462
- complete: Optional boolean indicating if the task is complete.
3463
- owner_ids: Optional list of user IDs who own this task.
3464
- external_id: Optional external identifier for the task.
3465
- created_at: Optional timestamp when the task was created.
3466
- updated_at: Optional timestamp when the task was last updated.
3467
-
3468
- Returns:
3469
- Dictionary containing the created task data returned from the API.
3470
-
3471
- Raises:
3472
- ValueError: Raised when required parameters 'story_public_id' or 'description' are None.
3473
- HTTPError: Raised when the API request fails.
3474
-
3475
- Tags:
3476
- create, task, story, api,
3477
- """
3478
- if story_public_id is None:
3479
- raise ValueError("Missing required parameter 'story-public-id'")
3480
- if description is None:
3481
- raise ValueError("Missing required parameter 'description'")
3482
- request_body = {
3483
- 'description': description,
3484
- 'complete': complete,
3485
- 'owner_ids': owner_ids,
3486
- 'external_id': external_id,
3487
- 'created_at': created_at,
3488
- 'updated_at': updated_at,
3489
- }
3490
- request_body = {k: v for k, v in request_body.items() if v is not None}
3491
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/tasks"
3492
- query_params = {}
3493
- response = self._post(url, data=request_body, params=query_params)
3494
- response.raise_for_status()
3495
- return response.json()
3496
-
3497
- def get_task(self, story_public_id, task_public_id) -> dict[str, Any]:
3498
- """
3499
- Gets task details for a specific task within a story.
3500
-
3501
- Args:
3502
- story_public_id: The public identifier for the story containing the task.
3503
- task_public_id: The public identifier for the task to retrieve.
3504
-
3505
- Returns:
3506
- A dictionary containing the task details and metadata.
3507
-
3508
- Raises:
3509
- ValueError: When either story_public_id or task_public_id is None.
3510
- HTTPError: When the API request fails.
3511
-
3512
- Tags:
3513
- get, retrieve, task, api,
3514
- """
3515
- if story_public_id is None:
3516
- raise ValueError("Missing required parameter 'story-public-id'")
3517
- if task_public_id is None:
3518
- raise ValueError("Missing required parameter 'task-public-id'")
3519
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/tasks/{task_public_id}"
3520
- query_params = {}
3521
- response = self._get(url, params=query_params)
3522
- response.raise_for_status()
3523
- return response.json()
3524
-
3525
- def update_task(self, story_public_id, task_public_id, description=None, owner_ids=None, complete=None, before_id=None, after_id=None) -> dict[str, Any]:
3526
- """
3527
- Updates the specified task within a story, modifying fields such as description, owners, completion status, and position.
3528
-
3529
- Args:
3530
- story_public_id: The unique public identifier of the story containing the task.
3531
- task_public_id: The unique public identifier of the task to update.
3532
- description: Optional; the new description for the task.
3533
- owner_ids: Optional; a list of user IDs to be set as owners of the task.
3534
- complete: Optional; a boolean indicating whether the task is complete.
3535
- before_id: Optional; the public ID of a task before which this task should be moved.
3536
- after_id: Optional; the public ID of a task after which this task should be moved.
3537
-
3538
- Returns:
3539
- A dictionary containing the updated task's data as returned by the API.
3540
-
3541
- Raises:
3542
- ValueError: If either 'story_public_id' or 'task_public_id' is not provided.
3543
- HTTPError: If the API response contains an HTTP error status.
3544
-
3545
- Tags:
3546
- update, task-management, api, story,
3547
- """
3548
- if story_public_id is None:
3549
- raise ValueError("Missing required parameter 'story-public-id'")
3550
- if task_public_id is None:
3551
- raise ValueError("Missing required parameter 'task-public-id'")
3552
- request_body = {
3553
- 'description': description,
3554
- 'owner_ids': owner_ids,
3555
- 'complete': complete,
3556
- 'before_id': before_id,
3557
- 'after_id': after_id,
3558
- }
3559
- request_body = {k: v for k, v in request_body.items() if v is not None}
3560
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/tasks/{task_public_id}"
3561
- query_params = {}
3562
- response = self._put(url, data=request_body, params=query_params)
3563
- response.raise_for_status()
3564
- return response.json()
3565
-
3566
- def delete_task(self, story_public_id, task_public_id) -> Any:
3567
- """
3568
- Deletes a task associated with a story based on their respective public IDs.
3569
-
3570
- Args:
3571
- story_public_id: The public ID of the story containing the task
3572
- task_public_id: The public ID of the task to be deleted
3573
-
3574
- Returns:
3575
- JSON response from the server after the deletion operation
3576
-
3577
- Raises:
3578
- ValueError: Raised if either 'story_public_id' or 'task_public_id' is None
3579
-
3580
- Tags:
3581
- delete, task-management, story-management,
3582
- """
3583
- if story_public_id is None:
3584
- raise ValueError("Missing required parameter 'story-public-id'")
3585
- if task_public_id is None:
3586
- raise ValueError("Missing required parameter 'task-public-id'")
3587
- url = f"{self.base_url}/api/v3/stories/{story_public_id}/tasks/{task_public_id}"
3588
- query_params = {}
3589
- response = self._delete(url, params=query_params)
3590
- response.raise_for_status()
3591
- return response.json()
3592
-
3593
- def create_story_link(self, verb, subject_id, object_id) -> dict[str, Any]:
3594
- """
3595
- Creates a story link between a subject and an object with the specified verb by sending a POST request to the story-links API endpoint.
3596
-
3597
- Args:
3598
- verb: str. Action describing the relationship between subject and object (e.g., 'like', 'comment', 'share').
3599
- subject_id: Any. Unique identifier of the subject entity initiating the action.
3600
- object_id: Any. Unique identifier of the object entity receiving the action.
3601
-
3602
- Returns:
3603
- dict. The JSON response from the API as a dictionary containing details of the created story link.
3604
-
3605
- Raises:
3606
- ValueError: If any of the required parameters ('verb', 'subject_id', or 'object_id') is None.
3607
- requests.HTTPError: If the underlying HTTP request fails or the API response contains an error status code.
3608
-
3609
- Tags:
3610
- create, story-link, api, management,
3611
- """
3612
- if verb is None:
3613
- raise ValueError("Missing required parameter 'verb'")
3614
- if subject_id is None:
3615
- raise ValueError("Missing required parameter 'subject_id'")
3616
- if object_id is None:
3617
- raise ValueError("Missing required parameter 'object_id'")
3618
- request_body = {
3619
- 'verb': verb,
3620
- 'subject_id': subject_id,
3621
- 'object_id': object_id,
3622
- }
3623
- request_body = {k: v for k, v in request_body.items() if v is not None}
3624
- url = f"{self.base_url}/api/v3/story-links"
3625
- query_params = {}
3626
- response = self._post(url, data=request_body, params=query_params)
3627
- response.raise_for_status()
3628
- return response.json()
3629
-
3630
- def get_story_link(self, story_link_public_id) -> dict[str, Any]:
3631
- """
3632
- Retrieves a specific story link by its public ID.
3633
-
3634
- Args:
3635
- story_link_public_id: The unique public identifier for the story link to retrieve.
3636
-
3637
- Returns:
3638
- A dictionary containing the story link data retrieved from the API.
3639
-
3640
- Raises:
3641
- ValueError: If the story_link_public_id parameter is None.
3642
- HTTPError: If the API request fails.
3643
-
3644
- Tags:
3645
- retrieve, get, story-link, api,
3646
- """
3647
- if story_link_public_id is None:
3648
- raise ValueError("Missing required parameter 'story-link-public-id'")
3649
- url = f"{self.base_url}/api/v3/story-links/{story_link_public_id}"
3650
- query_params = {}
3651
- response = self._get(url, params=query_params)
3652
- response.raise_for_status()
3653
- return response.json()
3654
-
3655
- def update_story_link(self, story_link_public_id, verb=None, subject_id=None, object_id=None) -> dict[str, Any]:
3656
- """
3657
- Updates an existing story link with new attributes.
3658
-
3659
- Args:
3660
- story_link_public_id: The public ID of the story link to update.
3661
- verb: Optional. The new verb to assign to the story link.
3662
- subject_id: Optional. The new subject ID to assign to the story link.
3663
- object_id: Optional. The new object ID to assign to the story link.
3664
-
3665
- Returns:
3666
- A dictionary containing the updated story link data.
3667
-
3668
- Raises:
3669
- ValueError: When the required story_link_public_id parameter is None.
3670
- HTTPError: When the API request fails.
3671
-
3672
- Tags:
3673
- update, story-link, api,
3674
- """
3675
- if story_link_public_id is None:
3676
- raise ValueError("Missing required parameter 'story-link-public-id'")
3677
- request_body = {
3678
- 'verb': verb,
3679
- 'subject_id': subject_id,
3680
- 'object_id': object_id,
3681
- }
3682
- request_body = {k: v for k, v in request_body.items() if v is not None}
3683
- url = f"{self.base_url}/api/v3/story-links/{story_link_public_id}"
3684
- query_params = {}
3685
- response = self._put(url, data=request_body, params=query_params)
3686
- response.raise_for_status()
3687
- return response.json()
3688
-
3689
- def delete_story_link(self, story_link_public_id) -> Any:
3690
- """
3691
- Deletes a story link by its public ID.
3692
-
3693
- Args:
3694
- story_link_public_id: The public ID of the story link to be deleted.
3695
-
3696
- Returns:
3697
- JSON response containing the result of the deletion operation.
3698
-
3699
- Raises:
3700
- ValueError: Raised when the required story_link_public_id parameter is None.
3701
- HTTPError: Raised when the HTTP request fails or returns an error status code.
3702
-
3703
- Tags:
3704
- delete, management, story-link,
3705
- """
3706
- if story_link_public_id is None:
3707
- raise ValueError("Missing required parameter 'story-link-public-id'")
3708
- url = f"{self.base_url}/api/v3/story-links/{story_link_public_id}"
3709
- query_params = {}
3710
- response = self._delete(url, params=query_params)
3711
- response.raise_for_status()
3712
- return response.json()
3713
-
3714
- def list_workflows(self, ) -> list[Any]:
3715
- """
3716
- Retrieves a list of available workflows from the API.
3717
-
3718
- Args:
3719
- None: This function takes no arguments
3720
-
3721
- Returns:
3722
- list: A list of workflow objects parsed from the JSON response.
3723
-
3724
- Raises:
3725
- HTTPError: If the HTTP request to the workflow API endpoint fails or returns an error status.
3726
-
3727
- Tags:
3728
- list, workflows, api, management,
3729
- """
3730
- url = f"{self.base_url}/api/v3/workflows"
3731
- query_params = {}
3732
- response = self._get(url, params=query_params)
3733
- response.raise_for_status()
3734
- return response.json()
3735
-
3736
- def get_workflow(self, workflow_public_id) -> dict[str, Any]:
3737
- """
3738
- Retrieves detailed information about a workflow given its public ID.
3739
-
3740
- Args:
3741
- workflow_public_id: The public identifier of the workflow to retrieve.
3742
-
3743
- Returns:
3744
- A dictionary containing the workflow details as returned by the API.
3745
-
3746
- Raises:
3747
- ValueError: If 'workflow_public_id' is None.
3748
- requests.HTTPError: If the HTTP request to the workflow API fails with an error status.
3749
-
3750
- Tags:
3751
- get, workflow, api, management,
3752
- """
3753
- if workflow_public_id is None:
3754
- raise ValueError("Missing required parameter 'workflow-public-id'")
3755
- url = f"{self.base_url}/api/v3/workflows/{workflow_public_id}"
3756
- query_params = {}
3757
- response = self._get(url, params=query_params)
3758
- response.raise_for_status()
3759
- return response.json()
3760
-
3761
- def list_tools(self):
3762
- return [
3763
- self.list_categories,
3764
- self.create_category,
3765
- self.get_category,
3766
- self.update_category,
3767
- self.delete_category,
3768
- self.list_category_milestones,
3769
- self.list_category_objectives,
3770
- self.list_custom_fields,
3771
- self.get_custom_field,
3772
- self.update_custom_field,
3773
- self.delete_custom_field,
3774
- self.list_entity_templates,
3775
- self.create_entity_template,
3776
- self.disable_story_templates,
3777
- self.enable_story_templates,
3778
- self.get_entity_template,
3779
- self.update_entity_template,
3780
- self.delete_entity_template,
3781
- self.get_epic_workflow,
3782
- self.list_epics,
3783
- self.create_epic,
3784
- self.get_epic,
3785
- self.update_epic,
3786
- self.delete_epic,
3787
- self.list_epic_comments,
3788
- self.create_epic_comment,
3789
- self.get_epic_comment,
3790
- self.update_epic_comment,
3791
- self.create_epic_comment_comment,
3792
- self.delete_epic_comment,
3793
- self.list_epic_stories,
3794
- self.unlink_productboard_from_epic,
3795
- self.get_external_link_stories,
3796
- self.list_files,
3797
- self.get_file,
3798
- self.update_file,
3799
- self.delete_file,
3800
- self.list_groups,
3801
- self.create_group,
3802
- self.get_group,
3803
- self.update_group,
3804
- self.list_group_stories,
3805
- self.list_iterations,
3806
- self.create_iteration,
3807
- self.disable_iterations,
3808
- self.enable_iterations,
3809
- self.get_iteration,
3810
- self.update_iteration,
3811
- self.delete_iteration,
3812
- self.list_iteration_stories,
3813
- self.get_key_result,
3814
- self.update_key_result,
3815
- self.list_labels,
3816
- self.create_label,
3817
- self.get_label,
3818
- self.update_label,
3819
- self.delete_label,
3820
- self.list_label_epics,
3821
- self.list_label_stories,
3822
- self.list_linked_files,
3823
- self.create_linked_file,
3824
- self.get_linked_file,
3825
- self.update_linked_file,
3826
- self.delete_linked_file,
3827
- self.get_current_member_info,
3828
- self.list_milestones,
3829
- self.create_milestone,
3830
- self.get_milestone,
3831
- self.update_milestone,
3832
- self.delete_milestone,
3833
- self.list_milestone_epics,
3834
- self.list_objectives,
3835
- self.create_objective,
3836
- self.get_objective,
3837
- self.update_objective,
3838
- self.delete_objective,
3839
- self.list_objective_epics,
3840
- self.list_projects,
3841
- self.create_project,
3842
- self.get_project,
3843
- self.update_project,
3844
- self.delete_project,
3845
- self.list_stories,
3846
- self.list_repositories,
3847
- self.get_repository,
3848
- self.search,
3849
- self.search_epics,
3850
- self.search_iterations,
3851
- self.search_milestones,
3852
- self.search_objectives,
3853
- self.search_stories,
3854
- self.create_story,
3855
- self.update_multiple_stories,
3856
- self.create_multiple_stories,
3857
- self.create_story_from_template,
3858
- self.search_stories_old,
3859
- self.get_story,
3860
- self.update_story,
3861
- self.delete_story,
3862
- self.list_story_comment,
3863
- self.create_story_comment,
3864
- self.get_story_comment,
3865
- self.update_story_comment,
3866
- self.delete_story_comment,
3867
- self.create_story_reaction,
3868
- self.unlink_comment_thread_from_slack,
3869
- self.story_history,
3870
- self.create_task,
3871
- self.get_task,
3872
- self.update_task,
3873
- self.delete_task,
3874
- self.create_story_link,
3875
- self.get_story_link,
3876
- self.update_story_link,
3877
- self.delete_story_link,
3878
- self.list_workflows,
3879
- self.get_workflow
3880
- ]