About
The API enables you to interact with Skills for Jira programmatically. Use this API to migrate data to/from external systems, implement automation around skills (e.g. add a skill to Assignee upon task completion) or develop any other type of integration.
This page documents the available API endpoints Cloud, including the HTTP response codes and example requests and responses.
Accessing the API
Because Skills for Jira is powered by Atlassian Forge its API endpoints inherit all characteristics of Forge Web Triggers. This means that API Endpoint URLs are specific for each Jira instance.
You can access URLs of your instance’s API endpoints in the “Users” section of Skills for Jira - Administration console.
Skills for Jira API uses Bearer Authentication using a custom Authorization-Skills header. You can generate or re-generate your Bearer token at any time in your Skills for Jira - Administration Console.
Endpoints
Get user skills
Returns all skills of the specified user.
HTTP Method: GET
Request:
accountId (query) The account ID of the user. Required
Response [JSON]:
skills: An array of all skill names that the user has expertise in
Example:
Request:
HTTP GET: https://atlassian-dev.net/x1/get-user-skills?accountId=3e63957f-c263-41cd-acda-748560232d49
Response (200):
{ "skills":["Engineering - Beginner","JavaScript", "HTML/CSS"] }
Add user skills
Adds one or more of skills to the specified user.
HTTP Method: PUT
Request:
accountId (query) The account ID of the user. Required
skills (body): An array of skills to add. Required
Response [JSON]:
added: An array of skills that were successfully added
existing: An array of skills that the user already had
Example:
Request:
HTTP PUT: https://{your-generated-endpoint-url}?accountId=3e63957f-c263-41cd-acda-748560232d49 { "skills":["Engineering - Beginner","JavaScript", "HTML/CSS"] }
Response (200):
{ "added":["HTML/CSS"], "existing":["Engineering - Beginner","JavaScript"] }
Remove user skills
Removes one or more skills from the specified user.
HTTP Method: DELETE
Request:
accountId (query) The account ID of the user. Required
skills (body): An array of skills to remove. Required
Response [JSON]:
removed: An array of user’s skills that were successfully deleted
missing: An array of skills that the user did not possess
Example:
Request:
HTTP DELETE: https://{your-generated-endpoint-url}?accountId=3e63957f-c263-41cd-acda-748560232d49 { "skills":["HTML/CSS", "Product Discovery"] }
Response (200):
{ "removed":["HTML/CSS"], "missing":["Product Discovery"] }
Get all users' skills
Returns the mapping of all experts and their skills in your Jira instance
HTTP Method: GET
Request: None
Response [JSON]:
skillsByAccountId: users / skills mapping
Example:
Request:
HTTP GET: https://{your-generated-endpoint-url}
Response (200):
{ "skillsByAccountId": { "3e63957f-c263-41cd-acda-748560232d49": [ "Engineering - Beginner", "JavaScript", "HTML/CSS" ], "63314adf8b75455be455c8a0": [ "Marketing - Competent", "Marketing - Expert", "English - Expert", "Social Media Marketing"], "61a4ad9cf241500072f37d74": [ "QA - Competent", "Test Automation", "Selenium", "Python" ] } }
Bulk update users skills
Updates skill sets of multiple users at once
HTTP Method: POST
Request:
skillsByAccountId: users / skills mapping
Response [JSON]:\
changes: all user skill changes after the import is processed
Example:
Request:
HTTP POST: https://{your-generated-endpoint-url} { "skillsByAccountId": { "3e63957f-c263-41cd-acda-748560232d49": [ "Engineering - Beginner" ], "63314adf8b75455be455c8a0": [ "Marketing - Expert", "Marketing - Master", "English - Expert", "Social Media Marketing"], } }
Response (200):
{ "changes": { "3e63957f-c263-41cd-acda-748560232d49": { "added": [], "removed": [ "JavaScript", "HTML/CSS" ] }, "63314adf8b75455be455c8a0": { "added": [ "Marketing - Master" ], "removed": [ "Marketing - Competent" ] } } }
Get skill tree with experts
Returns the complete skill tree with a list of experts specified for each skill
HTTP Method: GET
Request: None
Response [JSON]:
experts: skill tree with a list of experts specified for each skill
Example:
Request:
HTTP GET: https://{your-generated-endpoint-url}
Response (200):
{ "experts": [ { "key": "f2c4cba9-6082-48c8-b23e-852e101bedbd", "type": "category", "displayName": "Design", "children": [ { "key": "9935f79d-02d1-4415-a81b-04f9e9dcd7ce", "type": "category", "displayName": "UX" "children": [ { "key": "User Flows", "experts": [ "3e63957f-c263-41cd-acda-748560232d49" ] }, { "key": "Wireframes", "experts": [] }, { "key": "Usability Testing", "experts": [ "3e63957f-c263-41cd-acda-748560232d49", "63314adf8b75455be455c8a0" ] } ] } ] } ] }