Meegle API — Setting (Field Settings)
APIs under this skill: Get Field Information, Create Custom Field, Update Custom Field.
Get Field Information
Obtain the basic information of all fields under the specified space or, when work_item_type_key is provided, under that work item type. Response follows the SimpleField structure (field_key, field_type_key, options for select, compound_fields for compound_field). Permission: Permission Management – Configuration.
When to Use
- When building field selectors or form UIs that need field keys, types, aliases, and scopes (work_item_scopes)
- When you need option lists for select-type fields (label, value, order, is_disabled, etc.) or sub-fields for compound_field
- When resolving field_key for Update Work Item Basic Information Settings (schedule_field_key, estimate_point_field_key, actual_work_time_field_key) or for work item read/write APIs
API Spec: get_field_information
name: get_field_information
type: api
description: >
Obtain all fields under the space or under a work item type. Returns SimpleField
list: field_key, field_type_key, field_alias, field_name, is_custom_field,
work_item_scopes, value_generate_mode, relation_id; options for select; compound_fields for compound_field.
auth:
type: plugin_access_token
header: X-Plugin-Token
user_header: X-User-Key
http:
method: POST
url: https://{domain}/open_api/{project_key}/field/all
headers:
Content-Type: application/json
X-Plugin-Token: "{{resolved_token}}"
X-User-Key: "{{user_key}}"
path_params:
project_key:
type: string
required: true
description: >
Space ID (project_key) or space domain name (simple_name).
project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
inputs:
work_item_type_key:
type: string
required: false
description: Work item type. Obtain via Get work item types in space. Omit to get all fields in space.
outputs:
data:
type: array
description: >
List of SimpleField. Each has field_key, field_type_key, field_alias, field_name,
is_custom_field, work_item_scopes, value_generate_mode, relation_id. Select-type
fields include options (order, color, is_visibility, is_disabled, label, value,
work_item_type_key). compound_field type includes compound_fields (array of
field objects with field_key, field_type_key, field_name, etc.).
constraints:
- Permission: Permission Management – Configuration
error_mapping:
30001: Data not found (project_key does not match work_item_type_key; no such work item type in this space)
Usage notes
- work_item_type_key: Omit to return all fields in the space; set to a type (e.g.
story, chart) to return only fields scoped to that type. If the type does not exist in the space, 30001 is returned.
- data items: Use field_key when updating work item type settings (schedule_field_key, etc.) or when sending field values in work item APIs. field_type_key (e.g.
multi_text, select, compound_field) determines value shape.
- options: For select (and similar) fields; value is what to send in API payloads; label is display. compound_fields: For compound_field type; each sub-field has its own field_key and field_type_key.
Create Custom Field
Create a new custom field under the specified work item type. Returns the new field_key. Permission: Permission Management – Work Item Instances. For feature details, see Permission Management.
Points to note
- Work item relationship field default data visibility is fixed; conditional data range cannot be modified.
- Default values are not supported for attachment type or for external system signal / multi-value external system signal.
- Modifying field validity (default valid) is not supported.
- Updating work item type, creator, submission time, completion time, and business line fields is not supported.
- Voting fields are not supported.
When to Use
- When adding a new custom field (text, select, date, user, number, link, etc.) to a work item type
- When reusing options from another field (value_type 1 + reference_work_item_type_key, reference_field_key) or defining custom options (field_value)
- When configuring team_option for cascading single/multi-select (tree_select, tree_multi_select); mutually exclusive with field_value
API Spec: create_custom_field
name: create_custom_field
type: api
description: >
Create a custom field under the specified work item type. Returns field_key.
Supports text, select, tree_select, date, user, number, link, multi_file, bool,
work_item_related_select, etc. field_value and team_option are mutually exclusive.
auth:
type: plugin_access_token
header: X-Plugin-Token
user_header: X-User-Key
http:
method: POST
url: https://{domain}/open_api/{project_key}/field/{work_item_type_key}/create
headers:
Content-Type: application/json
X-Plugin-Token: "{{resolved_token}}"
X-User-Key: "{{user_key}}"
path_params:
project_key:
type: string
required: true
description: >
Space ID (project_key) or space domain name (simple_name).
project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
work_item_type_key:
type: string
required: true
description: Work item type. Obtain via Get work item types in space.
inputs:
field_name:
type: string
required: true
description: Field name; must not duplicate other fields.
field_alias:
type: string
required: false
description: Field alias; cannot duplicate other fields of the same work item type.
field_type_key:
type: string
required: true
description: >
Field type. See Attributes and fields. Supported: text, multi_text, select,
multi_select, tree_select, tree_multi_select, radio, user, multi_user, date,
schedule, link, number, multi_file, bool, signal, work_item_related_select,
work_item_related_multi_select.
value_type:
type: integer
required: false
description: >
Option source for select/multi_select/tree_select/tree_multi_select/radio.
0: Custom (default); 1: Reuse. When 1, reference_work_item_type_key and reference_field_key required.
field_value:
type: object
required: false
description: >
Option values; structure per Attributes and fields. For select, multi_select,
tree_select, tree_multi_select, radio. Mutually exclusive with team_option.
reference_work_item_type_key:
type: string
required: false
description: Required when value_type = 1.
reference_field_key:
type: string
required: false
description: Required when value_type = 1.
is_multi:
type: boolean
required: false
description: For text: true = multi-line; false = single-line (default).
format:
type: boolean
required: false
description: For date: true = date only; false = date + time (default).
free_add:
type: integer
required: false
description: For select/tree_select etc.: 1 = allow users to add options; 2 = No (default).
work_item_relation_uuid:
type: string
required: false
description: Work item relationship ID from Get field information. Required for work_item_related_select / work_item_related_multi_select.
default_value:
type: object
required: false
description: >
Default value; structure per field type (Attributes and fields). Not supported
for attachment, external system signal, multi-value external system signal.
help_description:
type: string
required: false
description: Help instructions.
authorized_roles:
type: array
items: string
required: false
description: >
Roles or system keys that can access/operate this field. Default "Anyone".
e.g. _master (Administrator), _owner (Creator), _role (Requirement-related person).
team_option:
type: object
required: false
description: >
Team scope per TeamOption. Only for tree_select, tree_multi_select.
Mutually exclusive with field_value.
outputs:
data:
type: string
description: Created field key (e.g. field_73jds7).
constraints:
- Permission: Permission Management – Work Item Instances
- field_value and team_option cannot both be sent
error_mapping:
1000051468: Field alias repeated (field_alias duplicate)
1000051469: Invalid update version (field being concurrently updated)
1000051750: Field name has been used (field_name duplicate)
1000053603: Field name length exceeded (max characters for field name)
Usage notes
- field_type_key: Use supported API types (e.g. text, select, date, user, number, link, multi_file, bool, work_item_related_select, work_item_related_multi_select). See Attributes and fields and the field type support list in the product docs.
- field_value vs team_option: Use field_value for custom/reused option values for select/tree_select etc.; use team_option only for cascading single/multi-select with team scope. Do not send both.
- value_type 1: Set reference_work_item_type_key and reference_field_key to reuse options from another field.
- work_item_relation_uuid: From Get Field Information (relation or work item relation fields). Required for work_item_related_select / work_item_related_multi_select.
- Default values are not supported for attachment, external system signal, or multi-value external system signal fields.
Update Custom Field
Update the configuration of the specified custom field. Identify the field by field_key in the body. Permission: Permission Management – Configuration. For details, see Permission Management.
Points to note
- Work item relationship field default data visibility is fixed; conditional data range cannot be modified.
- Default values are not supported for attachment type or for external system signal / multi-value external system signal.
- Modifying field validity (default valid) is not supported.
- Updating work item type, creator, submission time, completion time, and business line fields is not supported.
- Voting fields are not supported.
- When modifying or adding sub-options (cascading options), parent_value is required.
When to Use
- When changing field name, alias, help description, default value, authorized roles, or option list (field_value with action add/modify/delete)
- When updating team scope (team_option) for cascading single/multi-select; mutually exclusive with field_value
- When updating a composite field: pass parent field_key to change only field_name, field_alias, help_description; pass child field_key to update all attributes
API Spec: update_custom_field
name: update_custom_field
type: api
description: >
Update configuration of the specified custom field. field_key in body identifies
the field. field_value supports option actions (add/modify/delete); parent_value
required for sub-options. field_value and team_option are mutually exclusive.
auth:
type: plugin_access_token
header: X-Plugin-Token
user_header: X-User-Key
http:
method: PUT
url: https://{domain}/open_api/{project_key}/field/{work_item_type_key}
headers:
Content-Type: application/json
X-Plugin-Token: "{{resolved_token}}"
X-User-Key: "{{user_key}}"
path_params:
project_key:
type: string
required: true
description: >
Space ID (project_key) or space domain name (simple_name).
project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
work_item_type_key:
type: string
required: true
description: Work item type. Obtain via Get work item types in space.
inputs:
field_key:
type: string
required: false
description: >
Unique identifier of the field from Get Field Information. For composite
fields: parent field_key allows only field_name, field_alias, help_description;
child field_key allows all attributes.
field_name:
type: string
required: false
description: Field name.
field_value:
type: array
required: false
description: >
Option updates. Each item: label, value (option id), action (0 add, 1 modify, 2 delete).
For sub-options include parent_value. Structure per Attributes and fields.
Mutually exclusive with team_option.
free_add:
type: integer
required: false
description: 1 = allow users to add options; 2 = No (default). For select/tree_select etc.
work_item_relation_uuid:
type: string
required: false
description: Work item relationship ID from Get Field Information. For work_item_related_select / work_item_related_multi_select.
default_value:
type: object
required: false
description: Default value; structure per field type. Not supported for attachment, signal, multi-value signal.
field_alias:
type: string
required: false
description: Field alias; cannot duplicate other fields of same work item type.
help_description:
type: string
required: false
description: Help instructions.
authorized_roles:
type: array
items: string
required: false
description: Role or system keys (e.g. _master, _owner, _role). Default "Anyone".
team_option:
type: object
required: false
description: Team scope per TeamOption. Only for tree_select, tree_multi_select. Mutually exclusive with field_value.
outputs:
data:
type: object
description: Empty on success (no data in response).
constraints:
- Permission: Permission Management – Configuration
- field_value and team_option cannot both be sent
error_mapping:
1000051468: Field alias repeated (replace field_alias)
1000051750: Field name has been used (replace field_name)
1000050746: Field type not supported
1000053603: Field name length exceeded (max 255 characters)
1000053604: Field description length exceeded (max 255 characters)
1000053605: Option count exceeded (up to {Number} options)
Usage notes
- field_key: Required to identify which field to update; from Get Field Information. For compound_field: use parent field_key to change only name/alias/help_description; use child field_key to update all attributes.
- field_value option actions: action 0 = add option, 1 = modify option, 2 = delete option. Include parent_value when adding or modifying sub-options (cascading).
- field_value vs team_option: Do not send both. Use field_value for option list changes; use team_option for team scope on tree_select / tree_multi_select.
- Default values are not supported for attachment, external system signal, or multi-value external system signal.
1---2name: meegle-api-setting-field-settings3description: Meegle OpenAPI for field settings: get, create, update custom fields.4---5
6# Meegle API — Setting (Field Settings)
7
8APIs under this skill: Get Field Information, Create Custom Field, Update Custom Field.
9
10---
11
12## Get Field Information
13
14Obtain the basic information of all fields under the specified space or, when **work_item_type_key** is provided, under that work item type. Response follows the SimpleField structure (field_key, field_type_key, options for select, compound_fields for compound_field). Permission: Permission Management – Configuration.
15
16### When to Use
17
18- When building field selectors or form UIs that need field keys, types, aliases, and scopes (work_item_scopes)
19- When you need option lists for select-type fields (label, value, order, is_disabled, etc.) or sub-fields for compound_field
20- When resolving field_key for Update Work Item Basic Information Settings (schedule_field_key, estimate_point_field_key, actual_work_time_field_key) or for work item read/write APIs
21
22### API Spec: get_field_information
23
24```yaml
25name: get_field_information
26type: api
27description: >
28 Obtain all fields under the space or under a work item type. Returns SimpleField
29 list: field_key, field_type_key, field_alias, field_name, is_custom_field,
30 work_item_scopes, value_generate_mode, relation_id; options for select; compound_fields for compound_field.
31
32auth:
33 type: plugin_access_token
34 header: X-Plugin-Token
35 user_header: X-User-Key
36
37http:
38 method: POST
39 url: https://{domain}/open_api/{project_key}/field/all
40 headers:
41 Content-Type: application/json
42 X-Plugin-Token: "{{resolved_token}}"
43 X-User-Key: "{{user_key}}"
44
45path_params:
46 project_key:
47 type: string
48 required: true
49 description: >
50 Space ID (project_key) or space domain name (simple_name).
51 project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
52
53inputs:
54 work_item_type_key:
55 type: string
56 required: false
57 description: Work item type. Obtain via Get work item types in space. Omit to get all fields in space.
58
59outputs:
60 data:
61 type: array
62 description: >
63 List of SimpleField. Each has field_key, field_type_key, field_alias, field_name,
64 is_custom_field, work_item_scopes, value_generate_mode, relation_id. Select-type
65 fields include options (order, color, is_visibility, is_disabled, label, value,
66 work_item_type_key). compound_field type includes compound_fields (array of
67 field objects with field_key, field_type_key, field_name, etc.).
68
69constraints:
70 - Permission: Permission Management – Configuration
71
72error_mapping:
73 30001: Data not found (project_key does not match work_item_type_key; no such work item type in this space)
74```
75
76### Usage notes
77
78- **work_item_type_key**: Omit to return all fields in the space; set to a type (e.g. `story`, `chart`) to return only fields scoped to that type. If the type does not exist in the space, 30001 is returned.
79- **data** items: Use **field_key** when updating work item type settings (schedule_field_key, etc.) or when sending field values in work item APIs. **field_type_key** (e.g. `multi_text`, `select`, `compound_field`) determines value shape.
80- **options**: For **select** (and similar) fields; **value** is what to send in API payloads; **label** is display. **compound_fields**: For **compound_field** type; each sub-field has its own field_key and field_type_key.
81
82---
83
84## Create Custom Field
85
86Create a new custom field under the specified work item type. Returns the new **field_key**. Permission: Permission Management – Work Item Instances. For feature details, see Permission Management.
87
88### Points to note
89
90- Work item relationship field default data visibility is fixed; conditional data range cannot be modified.
91- Default values are not supported for attachment type or for external system signal / multi-value external system signal.
92- Modifying field validity (default valid) is not supported.
93- Updating work item type, creator, submission time, completion time, and business line fields is not supported.
94- Voting fields are not supported.
95
96### When to Use
97
98- When adding a new custom field (text, select, date, user, number, link, etc.) to a work item type
99- When reusing options from another field (value_type 1 + reference_work_item_type_key, reference_field_key) or defining custom options (field_value)
100- When configuring team_option for cascading single/multi-select (tree_select, tree_multi_select); mutually exclusive with field_value
101
102### API Spec: create_custom_field
103
104```yaml
105name: create_custom_field
106type: api
107description: >
108 Create a custom field under the specified work item type. Returns field_key.
109 Supports text, select, tree_select, date, user, number, link, multi_file, bool,
110 work_item_related_select, etc. field_value and team_option are mutually exclusive.
111
112auth:
113 type: plugin_access_token
114 header: X-Plugin-Token
115 user_header: X-User-Key
116
117http:
118 method: POST
119 url: https://{domain}/open_api/{project_key}/field/{work_item_type_key}/create
120 headers:
121 Content-Type: application/json
122 X-Plugin-Token: "{{resolved_token}}"
123 X-User-Key: "{{user_key}}"
124
125path_params:
126 project_key:
127 type: string
128 required: true
129 description: >
130 Space ID (project_key) or space domain name (simple_name).
131 project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
132 work_item_type_key:
133 type: string
134 required: true
135 description: Work item type. Obtain via Get work item types in space.
136
137inputs:
138 field_name:
139 type: string
140 required: true
141 description: Field name; must not duplicate other fields.
142 field_alias:
143 type: string
144 required: false
145 description: Field alias; cannot duplicate other fields of the same work item type.
146 field_type_key:
147 type: string
148 required: true
149 description: >
150 Field type. See Attributes and fields. Supported: text, multi_text, select,
151 multi_select, tree_select, tree_multi_select, radio, user, multi_user, date,
152 schedule, link, number, multi_file, bool, signal, work_item_related_select,
153 work_item_related_multi_select.
154 value_type:
155 type: integer
156 required: false
157 description: >
158 Option source for select/multi_select/tree_select/tree_multi_select/radio.
159 0: Custom (default); 1: Reuse. When 1, reference_work_item_type_key and reference_field_key required.
160 field_value:
161 type: object
162 required: false
163 description: >
164 Option values; structure per Attributes and fields. For select, multi_select,
165 tree_select, tree_multi_select, radio. Mutually exclusive with team_option.
166 reference_work_item_type_key:
167 type: string
168 required: false
169 description: Required when value_type = 1.
170 reference_field_key:
171 type: string
172 required: false
173 description: Required when value_type = 1.
174 is_multi:
175 type: boolean
176 required: false
177 description: For text: true = multi-line; false = single-line (default).
178 format:
179 type: boolean
180 required: false
181 description: For date: true = date only; false = date + time (default).
182 free_add:
183 type: integer
184 required: false
185 description: For select/tree_select etc.: 1 = allow users to add options; 2 = No (default).
186 work_item_relation_uuid:
187 type: string
188 required: false
189 description: Work item relationship ID from Get field information. Required for work_item_related_select / work_item_related_multi_select.
190 default_value:
191 type: object
192 required: false
193 description: >
194 Default value; structure per field type (Attributes and fields). Not supported
195 for attachment, external system signal, multi-value external system signal.
196 help_description:
197 type: string
198 required: false
199 description: Help instructions.
200 authorized_roles:
201 type: array
202 items: string
203 required: false
204 description: >
205 Roles or system keys that can access/operate this field. Default "Anyone".
206 e.g. _master (Administrator), _owner (Creator), _role (Requirement-related person).
207 team_option:
208 type: object
209 required: false
210 description: >
211 Team scope per TeamOption. Only for tree_select, tree_multi_select.
212 Mutually exclusive with field_value.
213
214outputs:
215 data:
216 type: string
217 description: Created field key (e.g. field_73jds7).
218
219constraints:
220 - Permission: Permission Management – Work Item Instances
221 - field_value and team_option cannot both be sent
222
223error_mapping:
224 1000051468: Field alias repeated (field_alias duplicate)
225 1000051469: Invalid update version (field being concurrently updated)
226 1000051750: Field name has been used (field_name duplicate)
227 1000053603: Field name length exceeded (max characters for field name)
228```
229
230### Usage notes
231
232- **field_type_key**: Use supported API types (e.g. **text**, **select**, **date**, **user**, **number**, **link**, **multi_file**, **bool**, **work_item_related_select**, **work_item_related_multi_select**). See **Attributes and fields** and the field type support list in the product docs.
233- **field_value** vs **team_option**: Use **field_value** for custom/reused option values for select/tree_select etc.; use **team_option** only for cascading single/multi-select with team scope. Do not send both.
234- **value_type 1**: Set **reference_work_item_type_key** and **reference_field_key** to reuse options from another field.
235- **work_item_relation_uuid**: From Get Field Information (relation or work item relation fields). Required for **work_item_related_select** / **work_item_related_multi_select**.
236- Default values are not supported for attachment, external system signal, or multi-value external system signal fields.
237
238---
239
240## Update Custom Field
241
242Update the configuration of the specified custom field. Identify the field by **field_key** in the body. Permission: Permission Management – Configuration. For details, see Permission Management.
243
244### Points to note
245
246- Work item relationship field default data visibility is fixed; conditional data range cannot be modified.
247- Default values are not supported for attachment type or for external system signal / multi-value external system signal.
248- Modifying field validity (default valid) is not supported.
249- Updating work item type, creator, submission time, completion time, and business line fields is not supported.
250- Voting fields are not supported.
251- When modifying or adding sub-options (cascading options), **parent_value** is required.
252
253### When to Use
254
255- When changing field name, alias, help description, default value, authorized roles, or option list (field_value with action add/modify/delete)
256- When updating team scope (team_option) for cascading single/multi-select; mutually exclusive with field_value
257- When updating a composite field: pass parent field_key to change only field_name, field_alias, help_description; pass child field_key to update all attributes
258
259### API Spec: update_custom_field
260
261```yaml
262name: update_custom_field
263type: api
264description: >
265 Update configuration of the specified custom field. field_key in body identifies
266 the field. field_value supports option actions (add/modify/delete); parent_value
267 required for sub-options. field_value and team_option are mutually exclusive.
268
269auth:
270 type: plugin_access_token
271 header: X-Plugin-Token
272 user_header: X-User-Key
273
274http:
275 method: PUT
276 url: https://{domain}/open_api/{project_key}/field/{work_item_type_key}
277 headers:
278 Content-Type: application/json
279 X-Plugin-Token: "{{resolved_token}}"
280 X-User-Key: "{{user_key}}"
281
282path_params:
283 project_key:
284 type: string
285 required: true
286 description: >
287 Space ID (project_key) or space domain name (simple_name).
288 project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
289 work_item_type_key:
290 type: string
291 required: true
292 description: Work item type. Obtain via Get work item types in space.
293
294inputs:
295 field_key:
296 type: string
297 required: false
298 description: >
299 Unique identifier of the field from Get Field Information. For composite
300 fields: parent field_key allows only field_name, field_alias, help_description;
301 child field_key allows all attributes.
302 field_name:
303 type: string
304 required: false
305 description: Field name.
306 field_value:
307 type: array
308 required: false
309 description: >
310 Option updates. Each item: label, value (option id), action (0 add, 1 modify, 2 delete).
311 For sub-options include parent_value. Structure per Attributes and fields.
312 Mutually exclusive with team_option.
313 free_add:
314 type: integer
315 required: false
316 description: 1 = allow users to add options; 2 = No (default). For select/tree_select etc.
317 work_item_relation_uuid:
318 type: string
319 required: false
320 description: Work item relationship ID from Get Field Information. For work_item_related_select / work_item_related_multi_select.
321 default_value:
322 type: object
323 required: false
324 description: Default value; structure per field type. Not supported for attachment, signal, multi-value signal.
325 field_alias:
326 type: string
327 required: false
328 description: Field alias; cannot duplicate other fields of same work item type.
329 help_description:
330 type: string
331 required: false
332 description: Help instructions.
333 authorized_roles:
334 type: array
335 items: string
336 required: false
337 description: Role or system keys (e.g. _master, _owner, _role). Default "Anyone".
338 team_option:
339 type: object
340 required: false
341 description: Team scope per TeamOption. Only for tree_select, tree_multi_select. Mutually exclusive with field_value.
342
343outputs:
344 data:
345 type: object
346 description: Empty on success (no data in response).
347
348constraints:
349 - Permission: Permission Management – Configuration
350 - field_value and team_option cannot both be sent
351
352error_mapping:
353 1000051468: Field alias repeated (replace field_alias)
354 1000051750: Field name has been used (replace field_name)
355 1000050746: Field type not supported
356 1000053603: Field name length exceeded (max 255 characters)
357 1000053604: Field description length exceeded (max 255 characters)
358 1000053605: Option count exceeded (up to {Number} options)
359```
360
361### Usage notes
362
363- **field_key**: Required to identify which field to update; from **Get Field Information**. For **compound_field**: use parent **field_key** to change only name/alias/help_description; use child **field_key** to update all attributes.
364- **field_value** option actions: **action** 0 = add option, 1 = modify option, 2 = delete option. Include **parent_value** when adding or modifying sub-options (cascading).
365- **field_value** vs **team_option**: Do not send both. Use **field_value** for option list changes; use **team_option** for team scope on tree_select / tree_multi_select.
366- Default values are not supported for attachment, external system signal, or multi-value external system signal.
modbender