Projects, Dashboards, Versions & Components

This page covers everything about the structure of your Jira Data Center instance: projects themselves (creating, updating, archiving), and the pieces that live inside or alongside them — components, versions, dashboards, project categories, roles, issue link types, issue types, security levels, and avatars. Ask your agent for any of these in plain English; it will pick the right tool.

Some tools here are only available if your Jira administrator has configured Alces with an admin-level credential (marked [ADMIN] below) — see Things to know.

Example prompts

• "Create a new project called 'Customer Portal' with key CP."
• "Archive the LEGACY project — we don't need it active anymore."
• "What components exist in the PROJ project?"
• "Add a component called 'Billing' to PROJ."
• "Create a 2.0 release version for PROJ, due end of September."
• "Who has the Administrators role on the PROJ project?"
• "List all the dashboards I can see."
• "What issue link types are available? I want to link two issues as 'blocks'."
• "Show me the project categories defined on this instance."
• "What's the permission scheme assigned to PROJ?" (requires admin access)
• "Give PROJ a custom avatar — here's the image."
• "What issue types are set up in PROJ, and what statuses does each have?"
• "Merge version 1.9 into 2.0 for PROJ."
• "Delete the 'Old Feature' component and move its issues to 'Core'."
• "What security levels are defined for PROJ?"

What's available

Projects

Lifecycle operations: creating, updating, changing type, archiving/restoring, and deleting projects, plus project-level metadata like properties, statuses, and type info.

Tool	What it does
create_project	Create a new project.
get_project	Get full detail for a single project by ID or key (components, versions, issue types, lead, category).
update_project	Update a project (any subset of key, name, description, lead, url, assigneeType, categoryId).
update_project_type	Change a project's type (e.g. "business" to "service_desk"); requires the target type to be licensed.
archive_project	Archive a project, hiding it from most views without deleting its data.
restore_project	Restore a previously archived project.
delete_project	Permanently delete a project and every issue it contains. Irreversible.
validate_project_key	Validate a candidate project key (checks uniqueness and format).
get_project_type	Get a single project type by key.
get_project_type_accessible	Check whether a project type is accessible to the acting user.
list_project_types	List all project types configured on this instance (e.g. business, service_desk).
get_project_statuses	Get all issue types with their statuses for a project.
get_project_properties	Get the keys of all properties stored on a project.
get_project_property	Get a single project property's value by key.
set_project_property	Set (create or overwrite) a project property's value.
delete_project_property	Delete a property from a project.

Components

Components are sub-groupings of work within a project (e.g. "Backend", "UI").

Tool	What it does
create_component	Create a new project component.
get_component	Get a single project component by ID.
update_component	Update a component (any subset of name, description).
delete_component	Delete a project component, optionally reassigning its issues to another component.
list_components	List project components, optionally filtered to one project.
get_project_components	Get a project's components.
get_component_related_issue_counts	Get the count of issues referencing a given component.

Versions

Versions represent releases (e.g. "2.0", "Sprint 14") that issues can be tagged as affecting or fixing, including remote links to related external pages.

Tool	What it does
create_version	Create a new version on a project.
get_version	Get a single version by ID.
update_version	Update a version's details. Only send the fields to change.
move_version	Change a version's sequence position among a project's versions.
merge_version	Merge one version into another; the source version is deleted and its issues reassigned.
remove_and_swap_version	Permanently delete a version, reassigning its issues' fix/affects-version references to another version.
list_versions	List project versions instance-wide.
list_project_versions	Get all of a project's versions, unpaginated.
get_project_versions_page	Get paginated project versions.
get_version_related_issue_counts	Get the count of issues that fix/affect a given version.
get_version_unresolved_issue_count	Get the count of unresolved issues for a given version.
create_version_remote_link	Create or update a remote link on a version (e.g. linking to an external release page).
create_version_remote_link_by_global_id	Create or update a remote link on a version when the global ID is already known.
get_version_remote_link	Get a specific remote link on a version by global ID.
get_version_remote_links	Get all remote links on a version.
get_version_remote_links_by_global_id	Get remote version links across all versions by global ID.
delete_version_remote_link	Delete a single remote link on a version by its global ID.
delete_version_remote_links	Delete ALL remote links on a version.

Dashboards

Dashboards are saved, shareable collections of Jira reports and gadgets.

Tool	What it does
list_dashboards	List dashboards visible to the acting user.
get_dashboard	Get a single dashboard by ID.

Project categories

Categories group related projects together for organization and reporting.

Tool	What it does
create_project_category	Create a new project category.
get_project_category	Get a single project category by ID.
update_project_category	Update a project category (any subset of name, description).
delete_project_category	Delete a project category.
list_project_categories	List project categories defined on this instance.

Roles

Roles (e.g. Administrators, Developers) group users and groups for permission and notification purposes, both instance-wide and per project.

Tool	What it does
create_role	Create a new project role (e.g. a custom role for a permission scheme).
get_role	Get a single project role by ID, including its default actors.
update_role	Fully update a project role's name and description.
patch_role	Partially update a project role's name and/or description (only send the fields to change).
delete_role	Permanently delete a project role.
list_roles	List all project roles defined on this instance (e.g. Administrators, Developers).
get_role_actors	Get the default actors (users/groups) for a project role.
add_role_actors	Add default actors (users and/or groups) to a project role.
remove_role_actor	Remove a single default actor (a user OR a group, not both) from a role.
get_project_role	Get details (including actors) for one role, scoped to a specific project.
get_project_roles	List all roles in a project as a role-name-to-URL map.
update_project_role	Fully replace a project role's actors (for a specific project) with the given users and/or groups.
add_project_role_actors	Add users and/or groups as actors to a project role, for a specific project.
delete_project_role_actor	Remove a single user or group actor from a project role, for a specific project.

Issue link types

Link types define how two issues can be related (e.g. "Blocks" / "is blocked by").

Tool	What it does
create_issue_link_type	Create a new issue link type (e.g. "Blocks" / "is blocked by").
get_issue_link_type	Get a single issue link type by ID.
update_issue_link_type	Update an issue link type's name and inward/outward phrases.
delete_issue_link_type	Delete an issue link type.
list_issue_link_types	List issue link types (e.g. Blocks, Relates to).
set_issue_link_type_order	Move a single issue link type to a new position among all issue link types.
reset_issue_link_type_order	Reset the order of ALL issue link types alphabetically.

Issue types (instance-wide and in a project)

Issue types (e.g. Bug, Story, Task) classify what kind of work an issue represents, and can carry avatars and custom properties.

Tool	What it does
create_issue_type	Create a new issue type ("standard" or "subtask").
get_issue_type	Get a single issue type by ID.
update_issue_type	Update an issue type (any subset of name, description, avatarId).
delete_issue_type	Permanently delete an issue type, optionally migrating its issues to another type.
list_issue_types	List issue types visible to the acting user.
get_issue_type_alternatives	Get the issue types an existing issue type's issues could migrate to, if that issue type were deleted.
get_issue_type_properties	Get the keys of all properties stored on an issue type.
get_issue_type_property	Get a single issue type property's value by key.
set_issue_type_property	Set an issue type's property value (arbitrary JSON stored under the given key).
delete_issue_type_property	Delete a property from an issue type.
create_issue_type_temporary_avatar	Upload a temporary avatar image for an issue type (base64-encoded), ahead of a follow-up crop step.
convert_issue_type_avatar	Convert a temporary avatar into a real, permanent avatar for an issue type.

Security levels & scheme associations

These tools show which scheme (permission, notification, workflow, priority, or issue-security) applies to a given project. They are read views, not scheme editors — see Things to know.

Tool	What it does
get_project_security_levels	Get all issue-level security levels for a project.
get_project_issue_security_level_scheme	Get the issue security level scheme for a project.
list_issue_security_schemes [ADMIN]	List all issue security schemes on this instance.
get_issue_security_scheme [ADMIN]	Get a single issue security scheme by ID.
get_project_priority_scheme	Get the priority scheme assigned to a project.
assign_project_priority_scheme	Assign a priority scheme to a project.
unassign_project_priority_scheme	Unassign a project from a priority scheme, reverting it to the instance default.
admin_get_project_permission_scheme [ADMIN]	Get the permission scheme assigned to a project.
admin_assign_project_permission_scheme [ADMIN]	Assign a permission scheme to a project.
admin_get_project_notification_scheme [ADMIN]	Get the notification scheme for a project.
admin_get_project_workflow_scheme [ADMIN]	Get the workflow scheme for a project.

Avatars

Avatars are the icon images shown for a project or issue type; changing one is a three-step upload-crop-select flow.

Tool	What it does
get_project_avatars	Get all avatars (system + custom) available for a project.
store_temporary_project_avatar	Upload an image as a project's temporary avatar (step 1 of 3). Accepts base64-encoded image content.
create_project_avatar_from_temporary	Convert a previously uploaded temporary avatar into a real project avatar (step 2 of 3, the crop step).
update_project_avatar	Select an existing avatar (system or previously uploaded custom) as a project's current avatar (step 3 of 3).
delete_project_avatar	Delete a custom project avatar.

Things to know

• Admin access required for 6 tools. get_issue_security_scheme, list_issue_security_schemes, admin_assign_project_permission_scheme, admin_get_project_notification_scheme, admin_get_project_permission_scheme, and admin_get_project_workflow_scheme are only visible to your agent if your administrator has configured Alces with JIRA_ADMIN_TOKEN. If your agent says a tool isn't available, this is likely why.
• Scheme association tools are read-only here. admin_get_project_permission_scheme, admin_get_project_notification_scheme, admin_get_project_workflow_scheme, get_project_priority_scheme, and get_project_issue_security_level_scheme (plus admin_assign_project_permission_scheme, which only assigns an existing scheme to a project) tell you which scheme applies to a project. They don't let you create or edit the schemes themselves — permission and workflow scheme management lives on the Admin page; priority and notification scheme editing isn't currently exposed as a tool.
• Several actions are destructive and require explicit confirmation. Your agent must pass confirm: true — and should always check with you first — before: delete_project (deletes the project and every issue in it, irreversible), delete_component, delete_issue_type, delete_issue_type_property, delete_issue_link_type, delete_project_category, delete_role, remove_role_actor, delete_project_avatar, delete_project_property, delete_project_role_actor, unassign_project_priority_scheme, delete_version_remote_link, delete_version_remote_links, and remove_and_swap_version. Deleting a project is comparable in severity to deleting a single issue, but destroys an entire project's data at once.
• Archiving is reversible, deleting is not. Prefer archive_project over delete_project when you just want a project out of the way; restore_project brings it back. There's no equivalent "undo" for delete_project.
• Avatars and remote links use multi-step flows. Changing a project avatar is upload (store_temporary_project_avatar) then crop (create_project_avatar_from_temporary) then select (update_project_avatar). Issue type avatars follow the same upload-then-convert pattern (create_issue_type_temporary_avatar then convert_issue_type_avatar).
• Prefer the project-scoped tool when you're working within one project. For example, use get_project_components (not list_components) or list_project_versions (not list_versions) when you already know the project — they're the same data, scoped more conveniently.

See docs/api-catalog.md for the complete technical reference (every field, every parameter). For errors, see Troubleshooting.