JIRA Service Desk REST API Reference

JIRA Service Desk 4.3.0

This is the reference document for the REST API and resources provided by JIRA Service Desk. The REST APIs are for developers who want to integrate JIRA Service Desk with other applications, and for administrators who want to script configuration interactions with JIRA Service Desk.

JIRA Service Desk is built upon the JIRA platform. As such there is a natural overlap in functionality between what is provided by JIRA Service Desk and what is provided by the JIRA platform. If you are after an introductory, high-level view of the JIRA REST APIs, then the best place to start is the JIRA REST API home.

Using the REST API

Not familiar with the JIRA Service Desk REST APIs? Start with our Guide to exploring the JIRA Service Desk domain model via the REST APIs, which will help you get a conceptual understanding of the JIRA Service Desk REST APIs.

If you want instructions on how to use the REST APIs, check out the Appendix at the end of this page (after the resources), where you'll find information on the following topics:

Experimental methods

Methods marked as experimental may change without notice. We are looking for your feedback for these methods. To use experimental methods, you must set this header in your requests: X-ExperimentalApi : true. This indicates that you are opting into the experimental preview. Once a resource or method moves out of the experimental phase, then this header will no longer be required nor checked.

Resources

servicedeskapi/customer

This resource represents a customer user account.

Creates a customer that is not associated with a service desk project.

The customer's username is their email address. They can set a password by clicking "Forgotten your password" on the portal login screen, or a Jira administrator can set one in User Management. By default, the customer can email requests to public service desks. If they have a password, they can also raise requests in customer portals that allow public signup. To raise requests in closed service desks, the customer must be added to a service desk project using Add customers.

This operation does not cause invitation email to be sent to the newly created customer.

Jira administrator global permission is required to create a customer.

Request

Example
{"email":"fred@example.com","fullName":"Fred F. User"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/customer-create#","title":"Customer Create","type":"object","properties":{"email":{"type":"string"},"fullName":{"type":"string"}},"additionalProperties":false}

Responses
    • Status 201 - application/json

      Example
      {"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}}

      Return the newly created customer.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]}

    • Status 400
      Returned if the HTTP request is invalid, e.g. invalid email address, or if the username (email) already exists.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to create a customer.

servicedeskapi/info

This resource represents the Jira Service Desk application.

Returns runtime information about Jira Service Desk. You do not need to be logged in to use this method.

Responses
    • Status 200 - application/json

      Example
      {"version":"3.0.1","platformVersion":"7.0.1","buildDate":{"iso8601":"2015-09-15T02:34:00+0700","jira":"2015-09-15T02:34:00.000+0700","friendly":"Monday 02:34 AM","epochMillis":1442259240000},"buildChangeSet":"c6679417c550918e7c94a9eaaada133f15dc8ff0","isLicensedForUse":true,"_links":{"self":"http://host:port/context/rest/servicedeskapi/info"}}

      Returns the runtime information for Jira Service Desk.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/software-info#","title":"Software Info","type":"object","properties":{"version":{"type":"string"},"platformVersion":{"type":"string"},"buildDate":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"buildChangeSet":{"type":"string"},"isLicensedForUse":{"type":"boolean"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

servicedeskapi/organization

To create an organization Jira administrator global permission or agent permission is required depending on the settings

Request

Example
{"name":"Charlie Cakes Franchises"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/organization-create#","title":"Organization Create","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}

Responses
    • Status 201 - application/json

      Example
      {"id":"1","name":"Charlie Cakes Franchises","_links":{"self":"http://host:port/context/rest/servicedeskapi/organization/1"}}

      Return the newly created organization.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/organization#","title":"Organization","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 400
      Returned if the HTTP request is invalid, e.g. organization name already exists.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to create an organization.

Returns a list of organizations in the Jira instance. If the user is not an agent, the resource returns a list of organizations the user is a member of.

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of users to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/organization?start=2&limit=1","prev":"http://host:port/context/rest/servicedeskapi/organization?start=0&limit=1"},"values":[{"id":"1","name":"Charlie Cakes Franchises","_links":{"self":"http://host:port/context/rest/servicedeskapi/organization/1"}}]}

      Returns paginated list of organizations.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-organization#","title":"Paged of Organization","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Organization","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.

Returns an organization for a given organization ID.

Responses
    • Status 200 - application/json

      Example
      {"id":"1","name":"Charlie Cakes Franchises","_links":{"self":"http://host:port/context/rest/servicedeskapi/organization/1"}}

      Returns the requested organization.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/organization#","title":"Organization","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not an agent or is not in the requested organization.
    • Status 404
      Returned if the organization does not exist.

Deletes an organization for a given organization ID.

Responses
    • Status 204 - application/json
      Delete organization was successful.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not a Jira Admin and an agent.
    • Status 404
      Returned if the organization does not exist.

Returns all the users of a specified organization

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of users to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}}

      Returns a paged list of users of the organization

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not an agent.
    • Status 404
      Returned if the organization does not exist.

Adds users to an organization

Request

Example
{"usernames":["bob","fred"]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/users-organization-update#","title":"Users Organization Update","type":"object","properties":{"usernames":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
    • Status 204 - application/json
      Returns a paged list of users of the organization
    • Status 400
      Some usernames are incorrect
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not permitted to add users.
    • Status 404
      Returned if the organization does not exist.

Removes users from an organization

Request

Example
{"organizationId":1}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/users-organization-update#","title":"Users Organization Update","type":"object","properties":{"usernames":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
    • Status 204 - application/json
    • Status 400
      Some usernames are incorrect
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not permitted to remove users from an organization.
    • Status 404
      Returned if the organization does not exist.

servicedeskapi/queues

Responses
    • Status - application/json
Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/boolean#","title":"boolean","type":"boolean"}

Responses
    • Status - application/json
Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/boolean#","title":"boolean","type":"boolean"}

Responses
    • Status - application/json
Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/boolean#","title":"boolean","type":"boolean"}

Responses
    • Status - application/json
Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/boolean#","title":"boolean","type":"boolean"}

Responses
    • Status - application/json

servicedeskapi/request

This resource represents a customer request in a service desk. Every customer request is categorized by a request type, which defines the fields required to create a customer request. A request can also have participants and comments.Show more

Returns all customer requests for the user that is executing the query. That is, the customer requests where the user is the creator of the customer request or has participated in the customer request.

Returned customer requests are ordered chronologically by the latest activity on each customer request. For example, the latest status transition or comment.

Request
query parameters
parametertypedescription
searchTermstring

Filters results to customer requests where the issue summary matches the searchTerm. You can use wildcards in the searchTerm.

requestOwnershipstring

Filters results to customer requests where the user is the creator and/or participant:

  • OWNED_REQUESTS - Only return customer requests where the user is the creator.
  • PARTICIPATED_REQUESTS - Only return customer requests where the user is a participant.
  • ALL_REQUESTS - Return customer requests where the user is the creator or a participant.

requestStatusstring

Filters results to customer requests that are resolved, unresolved, or either of the two:

  • CLOSED_REQUESTS - Only return customer requests that are resolved.
  • OPEN_REQUESTS - Only return customer requests that are unresolved.
  • ALL_REQUESTS - Returns customer requests that are either resolved or unresolved.

serviceDeskIdint

Filters results to customer requests from a specific service desk.

requestTypeIdint

Filters results to customer requests of a specific request type. You must also specify the serviceDeskID for the service desk that the request type belongs to.

expandstring

This is a multi-value parameter indicating which properties of the customer request to expand:

  • serviceDesk - Return additional details for each service desk in the response.
  • requestType - Return additional details for each request type in the response.
  • participant - Return the participant details, if any, for each customer request in the response.
  • sla - Return the SLA information on the given request.
  • status - Return the status transitions, in chronological order, for each customer request in the response.

startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/request?start=0&limit=3"},"values":[{"_expands":["participant","status","sla","requestType","serviceDesk"],"issueId":"107001","issueKey":"HELPDESK-1","requestTypeId":"25","serviceDeskId":"10","createdDate":{"iso8601":"2015-10-08T14:42:00+0700","jira":"2015-10-08T14:42:00.000+0700","friendly":"Monday 14:42 PM","epochMillis":1444290120000},"reporter":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"requestFieldValues":[{"fieldId":"summary","label":"What do you need?","value":"Request JSD help via REST"},{"fieldId":"description","label":"Why do you need this?","value":"I need a new mouse for my Mac"}],"currentStatus":{"status":"Waiting for Support","statusDate":{"iso8601":"2015-10-08T14:01:00+0700","jira":"2015-10-08T14:01:00.000+0700","friendly":"Today 14:01 PM","epochMillis":1444287660000}},"_links":{"jiraRest":"http://host:port/context/rest/api/2/issue/107001","web":"http://host:port/context/servicedesk/customer/portal/10/HELPDESK-1","self":"http://host:port/context/rest/servicedeskapi/request/107001"}},{"_expands":["participant","status","sla","requestType","serviceDesk"],"issueId":"107002","issueKey":"HELPDESK-2","requestTypeId":"25","serviceDeskId":"10","createdDate":{"iso8601":"2015-10-08T14:30:00+0700","jira":"2015-10-08T14:30:00.000+0700","friendly":"Monday 14:30 PM","epochMillis":1444289400000},"reporter":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"requestFieldValues":[{"fieldId":"summary","label":"What do you need?","value":"Request a new account"},{"fieldId":"description","label":"Why do you need this?","value":"Create an account on JIRA"}],"currentStatus":{"status":"Waiting for Support","statusDate":{"iso8601":"2015-10-08T14:01:00+0700","jira":"2015-10-08T14:01:00.000+0700","friendly":"Today 14:01 PM","epochMillis":1444287660000}},"_links":{"jiraRest":"http://host:port/context/rest/api/2/issue/107002","web":"http://host:port/context/servicedesk/customer/portal/10/HELPDESK-2","self":"http://host:port/context/rest/servicedeskapi/request/107002"}},{"_expands":["participant","status","sla","requestType","serviceDesk"],"issueId":"109006","issueKey":"SIMPLEDESK-6","requestTypeId":"33","serviceDeskId":"12","createdDate":{"iso8601":"2015-10-05T14:30:00+0700","jira":"2015-10-05T14:30:00.000+0700","friendly":"Monday 14:30 PM","epochMillis":1444030200000},"reporter":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"requestFieldValues":[{"fieldId":"summary","label":"Summarize the problem","value":"Printer on level 3 did not work"},{"fieldId":"description","value":"Ink cartridge is empty"}],"currentStatus":{"status":"Waiting for Support","statusDate":{"iso8601":"2015-10-08T14:00:00+0700","jira":"2015-10-08T14:00:00.000+0700","friendly":"Today 14:00 PM","epochMillis":1444287600000}},"_links":{"jiraRest":"http://host:port/context/rest/api/2/issue/109006","web":"http://host:port/context/servicedesk/customer/portal/12/SIMPLEDESK-6","self":"http://host:port/context/rest/servicedeskapi/request/109006"}}]}

      Returns the requested customer requests, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-customer-request#","title":"Paged of Customer Request","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"$ref":"#/definitions/paged-link"},"values":{"type":"array","items":{"title":"Customer Request","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"issueId":{"type":"string"},"issueKey":{"type":"string"},"requestTypeId":{"type":"string"},"requestType":{"title":"Request Type","type":"object","properties":{"id":{"type":"string"},"_links":{"$ref":"#/definitions/self-link"},"name":{"type":"string"},"description":{"type":"string"},"helpText":{"type":"string"},"serviceDeskId":{"type":"string"},"groupIds":{"type":"array","items":{"type":"string"}},"icon":{"title":"Request Type Icon","type":"object","properties":{"id":{"type":"string"},"_links":{"title":"Request Type Icon Link","type":"object","properties":{"iconUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"serviceDeskId":{"type":"string"},"serviceDesk":{"title":"Service Desk","type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"projectName":{"type":"string"},"projectKey":{"type":"string"},"_links":{"$ref":"#/definitions/self-link"}},"additionalProperties":false},"createdDate":{"$ref":"#/definitions/date"},"reporter":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"requestFieldValues":{"type":"array","items":{"title":"Customer Request Field Value","type":"object","properties":{"fieldId":{"type":"string"},"label":{"type":"string"},"value":{},"renderedValue":{}},"additionalProperties":false}},"currentStatus":{"$ref":"#/definitions/customer-request-status"},"status":{"$ref":"#/definitions/paged"},"participants":{"$ref":"#/definitions/paged"},"sla":{"$ref":"#/definitions/paged"},"_links":{"title":"Customer Request Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"web":{"type":"string","format":"uri"}},"additionalProperties":false},"issueTypeId":{"type":"string"},"projectId":{"type":"string"}},"additionalProperties":false}}},"definitions":{"customer-request-status":{"title":"Customer Request Status","type":"object","properties":{"status":{"type":"string"},"statusDate":{"$ref":"#/definitions/date"}},"additionalProperties":false},"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"paged":{"title":"Paged","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"$ref":"#/definitions/paged-link"},"values":{"type":"array","items":{"$ref":"#/definitions/customer-request-status"}}},"additionalProperties":false},"paged-link":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"self-link":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 404
      Returned if the user does not have permission to access the service desk, or the service desk does not exist, or the service desk or request type is not found.

Creates a customer request in a service desk. The service desk and request type are required. The fields that are mandatory for the request type are also required. If you need the list of the fields required for the request type, you can get it via this resource: servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field

Notes:

  • The fields for a request type may vary based on the permissions of the currently authenticated user:
    • * raiseOnBehalfOf field - Not available to users who only have the Service Desk customer permission.
    • * requestParticipants field - Not available to users who only have the Service Desk customer permission or if the feature is turned off for customers.
  • Schema of requestFieldValues field is a map of Jira's field's ID and its value, which are JSON ready objects. The object value will be interpreted with JSON semantics according to the specific field requirements. So a simple field like summary or number customer field might take String / Integer while other fields like Multi User Picker will take a more complex object that has JSON semantics. Refer to Field input formats reference on what field types take what values.

Request

Example
{"serviceDeskId":"10","requestTypeId":"25","requestFieldValues":{"summary":"Request JSD help via REST","description":"I need a new mouse for my Mac"},"requestParticipants":["john"]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/request-create#","title":"Request Create","type":"object","properties":{"serviceDeskId":{"type":"string"},"requestTypeId":{"type":"string"},"requestFieldValues":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"requestParticipants":{"type":"array","items":{"type":"string"}},"raiseOnBehalfOf":{"type":"string"}},"additionalProperties":false}

Responses
    • Status 201 - application/json

      Example
      {"_expands":["participant","status","sla","requestType","serviceDesk"],"issueId":"107001","issueKey":"HELPDESK-1","requestTypeId":"25","serviceDeskId":"10","createdDate":{"iso8601":"2015-10-08T14:42:00+0700","jira":"2015-10-08T14:42:00.000+0700","friendly":"Monday 14:42 PM","epochMillis":1444290120000},"reporter":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"requestFieldValues":[{"fieldId":"summary","label":"What do you need?","value":"Request JSD help via REST"},{"fieldId":"description","label":"Why do you need this?","value":"I need a new mouse for my Mac"}],"currentStatus":{"status":"Waiting for Support","statusDate":{"iso8601":"2015-10-08T14:01:00+0700","jira":"2015-10-08T14:01:00.000+0700","friendly":"Today 14:01 PM","epochMillis":1444287660000}},"_links":{"jiraRest":"http://host:port/context/rest/api/2/issue/107001","web":"http://host:port/context/servicedesk/customer/portal/10/HELPDESK-1","self":"http://host:port/context/rest/servicedeskapi/request/107001"}}

      Returned if the customer request was successfully created.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/customer-request#","title":"Customer Request","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"issueId":{"type":"string"},"issueKey":{"type":"string"},"requestTypeId":{"type":"string"},"requestType":{"title":"Request Type","type":"object","properties":{"id":{"type":"string"},"_links":{"$ref":"#/definitions/self-link"},"name":{"type":"string"},"description":{"type":"string"},"helpText":{"type":"string"},"serviceDeskId":{"type":"string"},"groupIds":{"type":"array","items":{"type":"string"}},"icon":{"title":"Request Type Icon","type":"object","properties":{"id":{"type":"string"},"_links":{"title":"Request Type Icon Link","type":"object","properties":{"iconUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"serviceDeskId":{"type":"string"},"serviceDesk":{"title":"Service Desk","type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"projectName":{"type":"string"},"projectKey":{"type":"string"},"_links":{"$ref":"#/definitions/self-link"}},"additionalProperties":false},"createdDate":{"$ref":"#/definitions/date"},"reporter":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"requestFieldValues":{"type":"array","items":{"title":"Customer Request Field Value","type":"object","properties":{"fieldId":{"type":"string"},"label":{"type":"string"},"value":{},"renderedValue":{}},"additionalProperties":false}},"currentStatus":{"$ref":"#/definitions/customer-request-status"},"status":{"$ref":"#/definitions/paged"},"participants":{"$ref":"#/definitions/paged"},"sla":{"$ref":"#/definitions/paged"},"_links":{"title":"Customer Request Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"web":{"type":"string","format":"uri"}},"additionalProperties":false},"issueTypeId":{"type":"string"},"projectId":{"type":"string"}},"definitions":{"customer-request-status":{"title":"Customer Request Status","type":"object","properties":{"status":{"type":"string"},"statusDate":{"$ref":"#/definitions/date"}},"additionalProperties":false},"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"paged":{"title":"Paged","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"$ref":"#/definitions/customer-request-status"}}},"additionalProperties":false},"self-link":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 400
      Returned if the HTTP request call is invalid.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to create a customer request in the specified project or on behalf of another user.

Returns the customer request for a given request Id/key.

Request
query parameters
parametertypedescription
expandstring

This is a multi-value parameter indicating which properties of the customer request to expand:

  • serviceDesk - Return additional details for each service desk in the response.
  • requestType - Return additional details for each request type in the response.
  • participant - Return the participant details, if any, for each customer request in the response.
  • sla - Return the SLA information on the given request.
  • status - Return the status transitions, in chronological order, for each customer request in the response.

Responses
    • Status 200 - application/json

      Example
      {"_expands":["participant","status","sla","requestType","serviceDesk"],"issueId":"107001","issueKey":"HELPDESK-1","requestTypeId":"25","serviceDeskId":"10","createdDate":{"iso8601":"2015-10-08T14:42:00+0700","jira":"2015-10-08T14:42:00.000+0700","friendly":"Monday 14:42 PM","epochMillis":1444290120000},"reporter":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"requestFieldValues":[{"fieldId":"summary","label":"What do you need?","value":"Request JSD help via REST"},{"fieldId":"description","label":"Why do you need this?","value":"I need a new mouse for my Mac"}],"currentStatus":{"status":"Waiting for Support","statusDate":{"iso8601":"2015-10-08T14:01:00+0700","jira":"2015-10-08T14:01:00.000+0700","friendly":"Today 14:01 PM","epochMillis":1444287660000}},"_links":{"jiraRest":"http://host:port/context/rest/api/2/issue/107001","web":"http://host:port/context/servicedesk/customer/portal/10/HELPDESK-1","self":"http://host:port/context/rest/servicedeskapi/request/107001"}}

      Returns the requested customer request.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/customer-request#","title":"Customer Request","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"issueId":{"type":"string"},"issueKey":{"type":"string"},"requestTypeId":{"type":"string"},"requestType":{"title":"Request Type","type":"object","properties":{"id":{"type":"string"},"_links":{"$ref":"#/definitions/self-link"},"name":{"type":"string"},"description":{"type":"string"},"helpText":{"type":"string"},"serviceDeskId":{"type":"string"},"groupIds":{"type":"array","items":{"type":"string"}},"icon":{"title":"Request Type Icon","type":"object","properties":{"id":{"type":"string"},"_links":{"title":"Request Type Icon Link","type":"object","properties":{"iconUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"serviceDeskId":{"type":"string"},"serviceDesk":{"title":"Service Desk","type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"projectName":{"type":"string"},"projectKey":{"type":"string"},"_links":{"$ref":"#/definitions/self-link"}},"additionalProperties":false},"createdDate":{"$ref":"#/definitions/date"},"reporter":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"requestFieldValues":{"type":"array","items":{"title":"Customer Request Field Value","type":"object","properties":{"fieldId":{"type":"string"},"label":{"type":"string"},"value":{},"renderedValue":{}},"additionalProperties":false}},"currentStatus":{"$ref":"#/definitions/customer-request-status"},"status":{"$ref":"#/definitions/paged"},"participants":{"$ref":"#/definitions/paged"},"sla":{"$ref":"#/definitions/paged"},"_links":{"title":"Customer Request Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"web":{"type":"string","format":"uri"}},"additionalProperties":false},"issueTypeId":{"type":"string"},"projectId":{"type":"string"}},"definitions":{"customer-request-status":{"title":"Customer Request Status","type":"object","properties":{"status":{"type":"string"},"statusDate":{"$ref":"#/definitions/date"}},"additionalProperties":false},"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"paged":{"title":"Paged","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"$ref":"#/definitions/customer-request-status"}}},"additionalProperties":false},"self-link":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to access the service desk, or if the user cannot view the customer request.
    • Status 404
      Returned if the customer request does not exist.

servicedeskapi/request/{issueIdOrKey}/approval

This resource represents the approvals on a request.

Returns all approvals on a request, for a given request Id/key.

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of approvals to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/2/approval?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/request/2/approval?start=0&limit=3"},"values":[{"id":"1","name":"Please approve this request","finalDecision":"approved","canAnswerApproval":false,"approvers":[{"approver":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"approverDecision":"approved"}],"createdDate":{"iso8601":"2016-09-28T14:01:00+0700","jira":"2016-09-28T14:01:00.000+0700","friendly":"Monday 14:01 PM","epochMillis":1475046060000},"completedDate":{"iso8601":"2016-09-29T14:30:00+0700","jira":"2016-09-29T14:30:00.000+0700","friendly":"Today 14:30 PM","epochMillis":1475134200000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2/approval/1"}},{"id":"2","name":"Waiting for approval","finalDecision":"declined","canAnswerApproval":false,"approvers":[{"approver":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"approverDecision":"approved"}],"createdDate":{"iso8601":"2016-10-05T14:01:00+0700","jira":"2016-10-05T14:01:00.000+0700","friendly":"Wednesday 14:01 PM","epochMillis":1475650860000},"completedDate":{"iso8601":"2016-10-06T14:30:00+0700","jira":"2016-10-06T14:30:00.000+0700","friendly":"Thursday 14:30 PM","epochMillis":1475739000000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2/approval/2"}}]}

      Returns the requested approval.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-approval#","title":"Paged of Approval","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Approval","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"finalDecision":{"type":"string","enum":["approved","declined","pending"]},"canAnswerApproval":{"type":"boolean"},"approvers":{"type":"array","items":{"title":"Approver","type":"object","properties":{"approver":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"approverDecision":{"type":"string","enum":["approved","declined","pending"]}},"additionalProperties":false}},"createdDate":{"$ref":"#/definitions/date"},"completedDate":{"$ref":"#/definitions/date"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false,"required":["canAnswerApproval"]}}},"definitions":{"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the authenticated user does not have permission to view the request.
    • Status 404
      Returned if the request does not exist.

Returns an approval for a given approval ID.

Responses
    • Status 200 - application/json

      Example
      {"id":"1","name":"Please approve this request","finalDecision":"approved","canAnswerApproval":false,"approvers":[{"approver":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"approverDecision":"approved"}],"createdDate":{"iso8601":"2016-09-28T14:01:00+0700","jira":"2016-09-28T14:01:00.000+0700","friendly":"Monday 14:01 PM","epochMillis":1475046060000},"completedDate":{"iso8601":"2016-09-29T14:30:00+0700","jira":"2016-09-29T14:30:00.000+0700","friendly":"Today 14:30 PM","epochMillis":1475134200000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2/approval/1"}}

      Returns the requested approval.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/approval#","title":"Approval","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"finalDecision":{"type":"string","enum":["approved","declined","pending"]},"canAnswerApproval":{"type":"boolean"},"approvers":{"type":"array","items":{"title":"Approver","type":"object","properties":{"approver":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"approverDecision":{"type":"string","enum":["approved","declined","pending"]}},"additionalProperties":false}},"createdDate":{"$ref":"#/definitions/date"},"completedDate":{"$ref":"#/definitions/date"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"definitions":{"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false,"required":["canAnswerApproval"]}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the authenticated user does not have permission to view the request.
    • Status 404
      Returned if the request or the approval does not exist.

Answer a pending approval

Request

Example
{"decision":"approve"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/approval-decision-request#","title":"Approval Decision Request","type":"object","properties":{"decision":{"type":"string","enum":["approve","decline"]}},"additionalProperties":false}

Responses
    • Status 200 - application/json

      Example
      {"id":"1","name":"Please approve this request","finalDecision":"approved","canAnswerApproval":false,"approvers":[{"approver":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"approverDecision":"approved"}],"createdDate":{"iso8601":"2016-09-28T14:01:00+0700","jira":"2016-09-28T14:01:00.000+0700","friendly":"Monday 14:01 PM","epochMillis":1475046060000},"completedDate":{"iso8601":"2016-09-29T14:30:00+0700","jira":"2016-09-29T14:30:00.000+0700","friendly":"Today 14:30 PM","epochMillis":1475134200000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2/approval/1"}}

      Returns the updated approval.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/approval#","title":"Approval","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"finalDecision":{"type":"string","enum":["approved","declined","pending"]},"canAnswerApproval":{"type":"boolean"},"approvers":{"type":"array","items":{"title":"Approver","type":"object","properties":{"approver":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"approverDecision":{"type":"string","enum":["approved","declined","pending"]}},"additionalProperties":false}},"createdDate":{"$ref":"#/definitions/date"},"completedDate":{"$ref":"#/definitions/date"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"definitions":{"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false,"required":["canAnswerApproval"]}

    • Status 400
      Returned if the request isn't in a status that has the approval or the approval already got decided.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user isn't an approver of the approval or the user doesn't have permission to view the request.
    • Status 404
      Returned if the request doesn't exist or the approval doesn't exist.

servicedeskapi/request/{issueIdOrKey}/attachment

Adds one or more temporary attachments that were created using Attach temporary file to a customer request. The attachment visibility is set by the public field.

Setting attachment visibility is dependent on the user's permission. For example, Agents can create either public or internal attachments, while Unlicensed users can only create internal attachments, and Customers can only create public attachments.

An additional comment may be provided which will be prepended to the attachments.

Request

Example
{"temporaryAttachmentIds":["temp910441317820424274","temp3600755449679003114"],"public":true,"additionalComment":{"body":"Please find the screenshot and the log file attached."}}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/attachment-create#","title":"Attachment Create","type":"object","properties":{"temporaryAttachmentIds":{"type":"array","items":{"type":"string"}},"public":{"type":"boolean"},"additionalComment":{"title":"Additional Comment","type":"object","properties":{"body":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
    • Status 201 - application/json

      Example
      {"comment":{"id":"1000","body":"Please find the screenshot and the log file attached. !screenshot.png|thumbnail! [^log.txt] _(32 kB)_","public":true,"author":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"created":{"iso8601":"2015-10-09T10:22:00+0700","jira":"2015-10-09T10:22:00.000+0700","friendly":"Today 10:22 AM","epochMillis":1444360920000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2000/comment/1000"}},"attachments":[{"filename":"screenshot.png","author":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"created":{"iso8601":"2015-10-09T10:22:00+0700","jira":"2015-10-09T10:22:00.000+0700","friendly":"Today 10:22 AM","epochMillis":1444360920000},"size":23123,"mimeType":"image/png","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/attachment/10000","content":"http://www.example.com/jira/servicedesk/customershim/secure/attachment/10000/screenshot.png","thumbnail":"http://www.example.com/jira/servicedesk/customershim/secure/thumbnail/10000/_thumb_10000.png"}},{"filename":"log.txt","author":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"created":{"iso8601":"2015-10-09T10:22:00+0700","jira":"2015-10-09T10:22:00.000+0700","friendly":"Today 10:22 AM","epochMillis":1444360920000},"size":32132,"mimeType":"text/plain","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/attachment/10001","content":"http://www.example.com/jira/servicedesk/customershim/secure/attachment/10001/log.txt"}}]}

      Return the newly created attachments.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/attachment-create-result#","title":"Attachment Create Result","type":"object","properties":{"comment":{"title":"Comment","type":"object","properties":{"id":{"type":"string"},"body":{"type":"string"},"public":{"type":"boolean"},"author":{"$ref":"#/definitions/user"},"created":{"$ref":"#/definitions/date"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false,"required":["public"]},"attachments":{"type":"array","items":{"title":"Attachment","type":"object","properties":{"filename":{"type":"string"},"author":{"$ref":"#/definitions/user"},"created":{"$ref":"#/definitions/date"},"size":{"type":"integer"},"mimeType":{"type":"string"},"_links":{"title":"Attachment Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"content":{"type":"string","format":"uri"},"thumbnail":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false,"required":["size"]}}},"definitions":{"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

    • Status 400
      Returned if the HTTP request is invalid, e.g. missing the required "public" field, or list of temporary attachment IDs, or the temporary attachment are expired.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to add an attachment, or the attachment violates permission checks.
    • Status 404
      Returned if the customer request does not exist.

servicedeskapi/request/{issueIdOrKey}/comment

This resource represents the comments on a customer request.

Creates a public or internal comment on an existing customer request. The currently logged-in user will be the author of the comment. The comment visibility is set by the public field.

Permissions:
Setting comment visibility depends on the calling user's permissions. For example, Agents can create either public or internal comments, Unlicensed users can only create internal comments, and Customers can only create public comments.

Request

Example
{"body":"Hello there","public":true}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/comment-create#","title":"Comment Create","type":"object","properties":{"body":{"type":"string"},"public":{"type":"boolean"}},"additionalProperties":false}

Responses
    • Status 201 - application/json

      Example
      {"id":"1000","body":"Hello there","public":true,"author":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"created":{"iso8601":"2015-10-09T10:22:00+0700","jira":"2015-10-09T10:22:00.000+0700","friendly":"Today 10:22 AM","epochMillis":1444360920000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2000/comment/1000"}}

      Return the newly created comment.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/comment#","title":"Comment","type":"object","properties":{"id":{"type":"string"},"body":{"type":"string"},"public":{"type":"boolean"},"author":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"created":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false,"required":["public"]}

    • Status 400
      Returned if the HTTP request is invalid, e.g. missing the required "public" field.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to add a comment, or the comment violates permission checks.
    • Status 404
      Returned if the customer request does not exist.

Returns all comments on a customer request, for a given request Id/key.

Permissions:
Only comments that the calling user can see are returned.

Request
query parameters
parametertypedescription
publicboolean

Specifies whether to return public comments or not. Default: true.

internalboolean

Specifies whether to return internal comments or not. Default: true.

startint

The starting index of the returned comments. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of comments to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/2000/comment?start=2&limit=1","prev":"http://host:port/context/rest/servicedeskapi/request/2000/comment?start=0&limit=1"},"values":[{"id":"1000","body":"Hello there","public":true,"author":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"created":{"iso8601":"2015-10-09T10:22:00+0700","jira":"2015-10-09T10:22:00.000+0700","friendly":"Today 10:22 AM","epochMillis":1444360920000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2000/comment/1000"}}]}

      Returns the requested comments, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-comment#","title":"Paged of Comment","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Comment","type":"object","properties":{"id":{"type":"string"},"body":{"type":"string"},"public":{"type":"boolean"},"author":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"created":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false,"required":["public"]}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 404
      Returned if the customer request does not exist.

Returns a specific comment of a specific customer request based on the provided comment ID.

Permissions:
The calling user must have permission to view the comment. For example, customers can only view public comments on requests where they are the reporter or a participant whereas agents can see both internal and public comments.

Responses
    • Status 200 - application/json

      Example
      {"id":"1000","body":"Hello there","public":true,"author":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}},"created":{"iso8601":"2015-10-09T10:22:00+0700","jira":"2015-10-09T10:22:00.000+0700","friendly":"Today 10:22 AM","epochMillis":1444360920000},"_links":{"self":"http://host:port/context/rest/servicedeskapi/request/2000/comment/1000"}}

      Return the requested comment.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/comment#","title":"Comment","type":"object","properties":{"id":{"type":"string"},"body":{"type":"string"},"public":{"type":"boolean"},"author":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]},"created":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false,"required":["public"]}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the authenticated user does not have permission to view the customer request or the comment.
    • Status 404
      Returned if the customer request or the comment do not exist.

servicedeskapi/request/{issueIdOrKey}/participant

This resource represents the participants on a customer request.

Returns all users participating in a customer request, for a given request Id/key.

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of request types to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/1000/participant?start=2&limit=1","prev":"http://host:port/context/rest/servicedeskapi/request/1000/participant?start=0&limit=1"},"values":[{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}}]}

      Returns the participants of the customer request, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-user#","title":"Paged of User","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the customer request.
    • Status 404
      Returned if the customer request does not exist.

Adds users as participants to an existing customer request.

Note, you can also add participants when creating a request via the request resource, by using the requestParticipants field.

Permissions:
The calling user must have permission to manage participants for this customer request.

Request

Example
{"usernames":["josh","john","joe"]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/request-participant-update#","title":"Request Participant Update","type":"object","properties":{"usernames":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/1000/participant?start=2&limit=1","prev":"http://host:port/context/rest/servicedeskapi/request/1000/participant?start=0&limit=1"},"values":[{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}}]}

      Returns the participants of the customer request.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-user#","title":"Paged of User","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false}

    • Status 400
      Returned if any user in the request does not exist.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to manage participants of the customer request.
    • Status 404
      Returned if the customer request does not exist.

Removes participants from an existing customer request.

Permissions:
The calling user must have permission to manage participants for this customer request.

Request

Example
{"usernames":["josh","john","joe"]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/request-participant-update#","title":"Request Participant Update","type":"object","properties":{"usernames":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/1000/participant?start=2&limit=1","prev":"http://host:port/context/rest/servicedeskapi/request/1000/participant?start=0&limit=1"},"values":[{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}}]}

      Returns the first page of participants of the customer request after removing the specified users.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-user#","title":"Paged of User","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false}

    • Status 400
      Returned if any user in the request does not exist, or is not a participant of the customer request, or is the reporter of the customer request.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to manage participants of the customer request.
    • Status 404
      Returned if the customer request does not exist.

servicedeskapi/request/{issueIdOrKey}/sla

This resource represents the SLAs (service level agreements) on a customer request.

Returns the SLA information for a customer request for a given request Id/key. A request can have zero or more SLA values. Each SLA value can have zero or more "completed cycles" and zero or 1 "ongoing cycles". Each cycle has information on when it started and stopped, and whether it breached the SLA goal.

Permissions:
The calling user must be an agent.

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of request types to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/101102/sla?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/request/101102/sla?start=0&limit=3"},"values":[{"name":"Time To First Response","_links":{"self":"http://host:port/context/rest/servicedeskapi/request/101102/sla/10030"},"completedCycles":[{"startTime":{"iso8601":"2015-10-09T10:45:23+0700","jira":"2015-10-09T10:45:23.000+0700","friendly":"Yesterday 10:45 AM","epochMillis":1444362323000},"stopTime":{"iso8601":"2015-10-09T10:52:23+0700","jira":"2015-10-09T10:52:23.000+0700","friendly":"Yesterday 10:52 AM","epochMillis":1444362743000},"breached":false,"goalDuration":{"millis":14400000,"friendly":"4h 240m"},"elapsedTime":{"millis":420000,"friendly":"0h 7m"},"remainingTime":{"millis":13980000,"friendly":"3h 233m"}},{"startTime":{"iso8601":"2015-10-10T10:52:23+0700","jira":"2015-10-10T10:52:23.000+0700","friendly":"Today 10:52 AM","epochMillis":1444449143000},"stopTime":{"iso8601":"2015-10-10T16:15:23+0700","jira":"2015-10-10T16:15:23.000+0700","friendly":"Today 16:15 PM","epochMillis":1444468523000},"breached":true,"goalDuration":{"millis":14400000,"friendly":"4h 240m"},"elapsedTime":{"millis":19380000,"friendly":"5h 323m"},"remainingTime":{"millis":-4980000,"friendly":"-1h -83m"}}],"ongoingCycle":{"startTime":{"iso8601":"2015-10-10T19:15:23+0700","jira":"2015-10-10T19:15:23.000+0700","friendly":"Today 19:15 PM","epochMillis":1444479323000},"breached":false,"paused":false,"withinCalendarHours":false,"goalDuration":{"millis":14400000,"friendly":"4h 240m"},"elapsedTime":{"millis":5640000,"friendly":"1h 94m"},"remainingTime":{"millis":8760000,"friendly":"2h 146m"}}},{"name":"Time To Resolution","_links":{"self":"http://host:port/context/rest/servicedeskapi/request/101102/sla/10040"},"completedCycles":[{"startTime":{"iso8601":"2015-10-09T10:45:23+0700","jira":"2015-10-09T10:45:23.000+0700","friendly":"Yesterday 10:45 AM","epochMillis":1444362323000},"stopTime":{"iso8601":"2015-10-09T20:52:23+0700","jira":"2015-10-09T20:52:23.000+0700","friendly":"Yesterday 20:52 PM","epochMillis":1444398743000},"breached":false,"goalDuration":{"millis":72000000,"friendly":"20h 1200m"},"elapsedTime":{"millis":36420000,"friendly":"10h 607m"},"remainingTime":{"millis":35580000,"friendly":"9h 593m"}},{"startTime":{"iso8601":"2015-10-10T20:52:23+0700","jira":"2015-10-10T20:52:23.000+0700","friendly":"Today 20:52 PM","epochMillis":1444485143000},"stopTime":{"iso8601":"2015-10-11T02:15:23+0700","jira":"2015-10-11T02:15:23.000+0700","friendly":"Today 02:15 AM","epochMillis":1444504523000},"breached":true,"goalDuration":{"millis":72000000,"friendly":"20h 1200m"},"elapsedTime":{"millis":19380000,"friendly":"5h 323m"},"remainingTime":{"millis":52620000,"friendly":"14h 877m"}}],"ongoingCycle":{"startTime":{"iso8601":"2015-10-11T05:15:23+0700","jira":"2015-10-11T05:15:23.000+0700","friendly":"Today 05:15 AM","epochMillis":1444515323000},"breached":false,"paused":false,"withinCalendarHours":false,"goalDuration":{"millis":72000000,"friendly":"20h 1200m"},"elapsedTime":{"millis":5640000,"friendly":"1h 94m"},"remainingTime":{"millis":66360000,"friendly":"18h 1106m"}}},{"name":"Time To Retrospective","_links":{"self":"http://host:port/context/rest/servicedeskapi/request/101102/sla/10050"},"completedCycles":[{"startTime":{"iso8601":"2015-10-09T10:45:23+0700","jira":"2015-10-09T10:45:23.000+0700","friendly":"Yesterday 10:45 AM","epochMillis":1444362323000},"stopTime":{"iso8601":"2015-10-10T10:52:23+0700","jira":"2015-10-10T10:52:23.000+0700","friendly":"Yesterday 10:52 AM","epochMillis":1444449143000},"breached":false,"goalDuration":{"millis":144000000,"friendly":"40h 2400m"},"elapsedTime":{"millis":86820000,"friendly":"24h 1447m"},"remainingTime":{"millis":57180000,"friendly":"15h 953m"}},{"startTime":{"iso8601":"2015-10-11T10:52:23+0700","jira":"2015-10-11T10:52:23.000+0700","friendly":"Today 10:52 AM","epochMillis":1444535543000},"stopTime":{"iso8601":"2015-10-11T16:15:23+0700","jira":"2015-10-11T16:15:23.000+0700","friendly":"Today 16:15 PM","epochMillis":1444554923000},"breached":true,"goalDuration":{"millis":144000000,"friendly":"40h 2400m"},"elapsedTime":{"millis":19380000,"friendly":"5h 323m"},"remainingTime":{"millis":124620000,"friendly":"34h 2077m"}}],"ongoingCycle":{"startTime":{"iso8601":"2015-10-11T19:15:23+0700","jira":"2015-10-11T19:15:23.000+0700","friendly":"Today 19:15 PM","epochMillis":1444565723000},"breached":false,"paused":false,"withinCalendarHours":false,"goalDuration":{"millis":144000000,"friendly":"40h 2400m"},"elapsedTime":{"millis":5640000,"friendly":"1h 94m"},"remainingTime":{"millis":138360000,"friendly":"38h 2306m"}}}]}

      Returns the SLA information of the customer request, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-sla-information#","title":"Paged of Sla Information","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Sla Information","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false},"completedCycles":{"type":"array","items":{"title":"Sla Information Completed Cycle","type":"object","properties":{"startTime":{"$ref":"#/definitions/date"},"stopTime":{"$ref":"#/definitions/date"},"breached":{"type":"boolean"},"goalDuration":{"$ref":"#/definitions/duration"},"elapsedTime":{"$ref":"#/definitions/duration"},"remainingTime":{"$ref":"#/definitions/duration"}},"additionalProperties":false,"required":["breached"]}},"ongoingCycle":{"title":"Sla Information Ongoing Cycle","type":"object","properties":{"startTime":{"$ref":"#/definitions/date"},"breachTime":{"$ref":"#/definitions/date"},"breached":{"type":"boolean"},"paused":{"type":"boolean"},"withinCalendarHours":{"type":"boolean"},"goalDuration":{"$ref":"#/definitions/duration"},"elapsedTime":{"$ref":"#/definitions/duration"},"remainingTime":{"$ref":"#/definitions/duration"}},"additionalProperties":false,"required":["breached","paused","withinCalendarHours"]}},"additionalProperties":false}}},"definitions":{"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"duration":{"title":"Duration","type":"object","properties":{"millis":{"type":"integer"},"friendly":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the customer request.
    • Status 404
      Returned if the customer request does not exist.

Returns the SLA information for a customer request for a given request Id/key and SLA metric Id. A request can have zero or more SLA values. Each SLA value can have zero or more "completed cycles" and zero or 1 "ongoing cycles". Each cycle has information on when it started and stopped, and whether it breached the SLA goal.

Permissions:
The calling user must be an agent.

Responses
    • Status 200 - application/json

      Example
      {"name":"Time To First Response","_links":{"self":"http://host:port/context/rest/servicedeskapi/request/101102/sla/10030"},"completedCycles":[{"startTime":{"iso8601":"2015-10-09T10:45:23+0700","jira":"2015-10-09T10:45:23.000+0700","friendly":"Yesterday 10:45 AM","epochMillis":1444362323000},"stopTime":{"iso8601":"2015-10-09T10:52:23+0700","jira":"2015-10-09T10:52:23.000+0700","friendly":"Yesterday 10:52 AM","epochMillis":1444362743000},"breached":false,"goalDuration":{"millis":14400000,"friendly":"4h 240m"},"elapsedTime":{"millis":420000,"friendly":"0h 7m"},"remainingTime":{"millis":13980000,"friendly":"3h 233m"}},{"startTime":{"iso8601":"2015-10-10T10:52:23+0700","jira":"2015-10-10T10:52:23.000+0700","friendly":"Today 10:52 AM","epochMillis":1444449143000},"stopTime":{"iso8601":"2015-10-10T16:15:23+0700","jira":"2015-10-10T16:15:23.000+0700","friendly":"Today 16:15 PM","epochMillis":1444468523000},"breached":true,"goalDuration":{"millis":14400000,"friendly":"4h 240m"},"elapsedTime":{"millis":19380000,"friendly":"5h 323m"},"remainingTime":{"millis":-4980000,"friendly":"-1h -83m"}}],"ongoingCycle":{"startTime":{"iso8601":"2015-10-10T19:15:23+0700","jira":"2015-10-10T19:15:23.000+0700","friendly":"Today 19:15 PM","epochMillis":1444479323000},"breached":false,"paused":false,"withinCalendarHours":false,"goalDuration":{"millis":14400000,"friendly":"4h 240m"},"elapsedTime":{"millis":5640000,"friendly":"1h 94m"},"remainingTime":{"millis":8760000,"friendly":"2h 146m"}}}

      Returns the SLA information of the customer request, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/sla-information#","title":"Sla Information","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false},"completedCycles":{"type":"array","items":{"title":"Sla Information Completed Cycle","type":"object","properties":{"startTime":{"$ref":"#/definitions/date"},"stopTime":{"$ref":"#/definitions/date"},"breached":{"type":"boolean"},"goalDuration":{"$ref":"#/definitions/duration"},"elapsedTime":{"$ref":"#/definitions/duration"},"remainingTime":{"$ref":"#/definitions/duration"}},"additionalProperties":false,"required":["breached"]}},"ongoingCycle":{"title":"Sla Information Ongoing Cycle","type":"object","properties":{"startTime":{"$ref":"#/definitions/date"},"breachTime":{"$ref":"#/definitions/date"},"breached":{"type":"boolean"},"paused":{"type":"boolean"},"withinCalendarHours":{"type":"boolean"},"goalDuration":{"$ref":"#/definitions/duration"},"elapsedTime":{"$ref":"#/definitions/duration"},"remainingTime":{"$ref":"#/definitions/duration"}},"additionalProperties":false,"required":["breached","paused","withinCalendarHours"]}},"definitions":{"date":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false},"duration":{"title":"Duration","type":"object","properties":{"millis":{"type":"integer"},"friendly":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the customer request.
    • Status 404
      Returned if the customer request does not exist.

servicedeskapi/request/{issueIdOrKey}/status

This resource represents the status transitions for a customer request.

Returns the status transitions for a customer request for a given request Id/key. The status transitions are returned in chronological order.

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/1/status?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/request/1/status?start=0&limit=3"},"values":[{"status":"Waiting for Customer","statusDate":{"iso8601":"2015-10-08T14:05:00+0700","jira":"2015-10-08T14:05:00.000+0700","friendly":"Today 14:05 PM","epochMillis":1444287900000}},{"status":"Waiting for Support","statusDate":{"iso8601":"2015-10-08T14:01:00+0700","jira":"2015-10-08T14:01:00.000+0700","friendly":"Today 14:01 PM","epochMillis":1444287660000}},{"status":"Waiting for Customer","statusDate":{"iso8601":"2015-10-08T14:00:00+0700","jira":"2015-10-08T14:00:00.000+0700","friendly":"Today 14:00 PM","epochMillis":1444287600000}}]}

      Returns the requested customer request status, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-customer-request-status#","title":"Paged of Customer Request Status","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Customer Request Status","type":"object","properties":{"status":{"type":"string"},"statusDate":{"title":"Date","type":"object","properties":{"iso8601":{"type":"string"},"jira":{"type":"string"},"friendly":{"type":"string"},"epochMillis":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the customer request.
    • Status 404
      Returned if the customer request is not found.

servicedeskapi/request/{issueIdOrKey}/transition

Perform a customer transition for a given request and transition ID. An optional comment can be included to provide a reason for the transition.

Permissions:
The calling user must be able to view the request and have the Transition Issues permission. If an additional comment is passed the calling user must also have the Add Comments permission.

Request

Example
{"id":"1","additionalComment":{"body":"I have fixed the problem."}}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/customer-transition-execution#","title":"Customer Transition Execution","type":"object","properties":{"id":{"type":"string"},"additionalComment":{"title":"Additional Comment","type":"object","properties":{"body":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
    • Status 204 - application/json
      Returned if the request is transitioned.
    • Status 400
      Returned if the transition ID is invalid or the comment is too long.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the request or does not have permission to add a comment.
    • Status 404
      Returned if the request does not exist.

Returns a list of transitions that customers can perform on the request.

Permissions:
The calling user must be able to view the request

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 100. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":2,"start":2,"limit":2,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/request/1/transition?start=4&limit=2","prev":"http://host:port/context/rest/servicedeskapi/request/1/transition?start=0&limit=2"},"values":[{"id":"1","name":"Close Request"},{"id":"2","name":"Escalate Request"}]}

      Returns the customer transitions for the request.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/customer-transition#","title":"Customer Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the customer request.
    • Status 404
      Returned if the customer request does not exist.

servicedeskapi/servicedesk

This resource represents a service desk. A service desk is based on a project in the Jira platform, and is used to manage customer requests.Show more

Returns all service desks in the Jira Service Desk application with the option to include archived service desks.

Request
query parameters
parametertypedescription
includeArchivedboolean

Default: false

The option to include archived service desks. False by default.

startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 50 See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/servicedesk?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/servicedesk?start=0&limit=3"},"values":[{"id":"10001","projectId":"11001","projectName":"IT Help Desk","projectKey":"ITH","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10001"}},{"id":"10002","projectId":"11002","projectName":"HR Self Serve Desk","projectKey":"HR","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10002"}},{"id":"10003","projectId":"11003","projectName":"Foundation Leave","projectKey":"FL","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10003"}}]}

      Returns the service desks, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-service-desk#","title":"Paged of Service Desk","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Service Desk","type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"projectName":{"type":"string"},"projectKey":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.

Returns the service desk for a given service desk Id.

Responses
    • Status 200 - application/json

      Example
      {"id":"10001","projectId":"11001","projectName":"IT Help Desk","projectKey":"ITH","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10001"}}

      Returns the requested service desk.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/service-desk#","title":"Service Desk","type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"projectName":{"type":"string"},"projectKey":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to access the service desk.
    • Status 404
      Returned if service desk does not exist.

servicedeskapi/servicedesk/{serviceDeskId}/attachTemporaryFile

Create one or more temporary attachments, which can later be converted into permanent attachments on Create attachment.

On successful execution, this resource will return a list of temporary attachment IDs, which are used in subsequent calls to convert the attachments into permanent attachments.

This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST.

In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: no-check with the request, otherwise it will be blocked.

The name of the multipart/form-data parameter that contains attachments must be "file"

A simple example to upload a file called "myfile.txt" in Service Desk with ID 10001

curl -D- -u customer:customer -X POST -H "X-ExperimentalApi: opt-in" -H "X-Atlassian-Token: no-check" -F "file=@myfile.txt" http://host:port/rest/servicedeskapi/servicedesk/10001/attachTemporaryFile

Responses
    • Status 201 - application/json

      Example
      {"temporaryAttachments":[{"temporaryAttachmentId":"temp8186986881700442965","fileName":"atlassian.png"},{"temporaryAttachmentId":"temp589064256337898328","fileName":"readme.txt"}]}

      Returned if the temporary attachment was successfully created.
    • Status 400
      Returned if attachments are not invalid, or exceeds the maximum configured attachment size.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if attachments is disabled or if you don't have permission to add attachments, or if no permission to access the Service Desk
    • Status 404
      Returned if the Service Desk is not found

servicedeskapi/servicedesk/{serviceDeskId}/customer

This resource represents the customers in a service desk.

Adds one or more existing customers to the given service desk. If you need to create a customer, see Create customer.

Administer project permission is required, or agents if public signups and invites are enabled for the Service Desk project.

Request

Example
{"usernames":["joe","john","josh"]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/service-desk-customer-add#","title":"Service Desk Customer Add","type":"object","properties":{"usernames":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
    • Status 200

      Example
      {"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/servicedesk/1/customer?start=2&limit=1","prev":"http://host:port/context/rest/servicedeskapi/servicedesk/1/customer?start=0&limit=1"},"values":[{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}}]}

      Return the customers added to the service desk.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-user#","title":"Paged of User","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"_links":{"title":"User Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"jiraRest":{"type":"string","format":"uri"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false}

    • Status 201 - application/json
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to add a participant.

servicedeskapi/servicedesk/{serviceDeskId}/organization

Returns all organizations within a servicedesk for a given servicedesk id.

Request
query parameters
parametertypedescription
startint
limitint
Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/organization?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/organization?start=0&limit=3"},"values":[{"id":"1","name":"Charlie Cakes Franchises","_links":{"self":"http://host:port/context/rest/servicedeskapi/organization/1"}},{"id":"2","name":"Atlas Coffee Co","_links":{"self":"http://host:port/context/rest/servicedeskapi/organization/2"}},{"id":"3","name":"The Adjustment Bureau","_links":{"self":"http://host:port/context/rest/servicedeskapi/organization/3"}}]}

      Returns the requested organizations.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/organization#","title":"Organization","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not an agent of the servicedesk.
    • Status 404
      Returned if the servicedesk does not exist.

Adds an organization to a servicedesk for a given servicedesk id and organization id.

Request

Example
{"organizationId":1}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/organization-service-desk-update#","title":"Organization Service Desk Update","type":"object","properties":{"organizationId":{"type":"integer"}},"additionalProperties":false}

Responses
    • Status 204 - application/json
      Add organization was successful.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not an agent of the servicedesk.
    • Status 404
      Returned if the servicedesk or organization does not exist.

Removes an organization from a servicedesk for a given servicedesk id and organization id.

Request

Example
{"organizationId":1}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/organization-service-desk-update#","title":"Organization Service Desk Update","type":"object","properties":{"organizationId":{"type":"integer"}},"additionalProperties":false}

Responses
    • Status 204 - application/json
      Remove organization was successful.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user is not an agent of the servicedesk.
    • Status 404
      Returned if the servicedesk or organization does not exist.

servicedeskapi/servicedesk/{serviceDeskId}/queue

This resource represents the queues of a service desk. A queue is a named grouping of issues filtered by a JQL query.Show more

Returns a page of queues defined inside a service desk, for a given service desk ID. The returned queues will include an issue count for each queue (represented in issueCount field) if the query param includeCount is set to true (defaults to false).

Permissions:
The calling user must be an agent of the given service desk.

Request
query parameters
parametertypedescription
includeCountboolean

Default: false

Specifies whether to include the issue count of each queue in the response. Valid values: true/false. Default: false.

startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":2,"start":2,"limit":2,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/servicedesk/1/queue?start=4&limit=2","prev":"http://host:port/context/rest/servicedeskapi/servicedesk/1/queue?start=0&limit=2"},"values":[{"id":"10","name":"Unassigned issues","jql":"project = SD AND assignee is EMPTY AND resolution = Unresolved ORDER BY \"Time to resolution\" ASC","fields":["issuetype","issuekey","summary","created","reporter","duedate"],"issueCount":10,"_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/1/queue/10"}},{"id":"20","name":"Assigned to me","jql":"project = SD AND assignee = currentUser() AND resolution = Unresolved ORDER BY \"Time to resolution\" ASC","fields":["issuetype","issuekey","summary","created","reporter","duedate"],"issueCount":10,"_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/1/queue/20"}}]}

      Returns the queues belonging to the provided service desk, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-queue#","title":"Paged of Queue","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Queue","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"jql":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}},"issueCount":{"type":"integer"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the service desk.
    • Status 404
      Returned if the service desk does not exist.

Returns a page of issues inside a queue for a given queue ID. Only fields that the queue is configured to show are returned. For example, if a queue is configured to show only Description and Due Date, then only those two fields are returned for each issue in the queue.

Permissions:
The calling user must have permission to view the requested queue, i.e. they must be an agent of the service desk that the queue belongs to.

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 50. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/servicedesk/1/queue/10/issue?start=2&limit=1","prev":"http://host:port/context/rest/servicedeskapi/servicedesk/1/queue/10/issue?start=0&limit=1"},"values":[{"id":"10001","self":"http://host:port/context/rest/servicedeskapi/rest/api/2/issue/10001","key":"SD-1","fields":{"summary":"My keyboard is broken","issuetype":{"self":"http://host:port/context/rest/api/2/issuetype/13","id":"13","description":"For general IT problems and questions. Created by JIRA Service Desk.","iconUrl":"http://host:port/context/servicedesk/issue-type-icons?icon=it-help","name":"IT Help","subtask":false,"avatarId":10002},"duedate":"2015-11-11T14:17:13.000+0700","created":"2015-11-09T14:17:13.000+0700","reporter":{"name":"fred","key":"fred","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"http://www.example.com/jira/rest/api/2/user?username=fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"},"self":"http://www.example.com/jira/rest/api/2/user?username=fred"}}}}]}

      Returns the issues belonging to the provided queue, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-issue#","title":"Paged of Issue","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Issue","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"string"},"self":{"type":"string","format":"uri"},"key":{"type":"string"},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"renderedFields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"properties":{"title":"Properties","type":"object","properties":{"properties":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"names":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"schema":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/json-type"}},"additionalProperties":false},"transitions":{"type":"array","items":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false}},"operations":{"title":"Opsbar","type":"object","properties":{"linkGroups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"editmeta":{"title":"Edit Meta","type":"object","properties":{"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false}},"additionalProperties":false},"changelog":{"title":"Changelog","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"histories":{"type":"array","items":{"title":"Change History","type":"object","properties":{"id":{"type":"string"},"author":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"created":{"type":"string"},"items":{"type":"array","items":{"title":"Change Item","type":"object","properties":{"field":{"type":"string"},"fieldtype":{"type":"string"},"from":{"type":"string"},"fromString":{"type":"string"},"to":{"type":"string"},"toString":{"type":"string"}},"additionalProperties":false}},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false},"versionedRepresentations":{"type":"object","patternProperties":{".+":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false}},"additionalProperties":false},"fieldsToInclude":{"title":"Included Fields","type":"object"}},"additionalProperties":false}}},"definitions":{"field-meta":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"$ref":"#/definitions/json-type"},"name":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]},"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false},"json-type":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"link-group":{"title":"Link Group","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"header":{"$ref":"#/definitions/simple-link"},"weight":{"type":"integer"},"links":{"type":"array","items":{"$ref":"#/definitions/simple-link"}},"groups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"simple-link":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to view the queue.
    • Status 404
      Returned if the service desk or the queue do not exist.

servicedeskapi/servicedesk/{serviceDeskId}/requesttype

This resource represents a request type in a service desk. Each service desk can have many request types. Request types categorize the customer requests in a service desk, and define the fields required to create a customer request.Show more

Returns all request types from a service desk, for a given service desk Id.

Request
query parameters
parametertypedescription
groupIdint

Filter results where the group ID of the request type matches groupId

startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 100. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/requesttype?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/requesttype?start=0&limit=3"},"values":[{"id":"11001","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/requesttype/11001"},"name":"Get IT Help","description":"Get IT Help","helpText":"Please tell us clearly the problem you have within 100 words.","serviceDeskId":"10001","groupIds":["12"],"icon":{"id":"12345","_links":{"iconUrls":{"48x48":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12345","24x24":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12345","16x16":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12345","32x32":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12345"}}}},{"id":"11002","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/requesttype/11002"},"name":"Request a new account","description":"Request a new account","serviceDeskId":"10001","groupIds":["13","14"],"icon":{"id":"12346","_links":{"iconUrls":{"48x48":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12346","24x24":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12346","16x16":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12346","32x32":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12346"}}}},{"id":"11003","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/requesttype/11003"},"name":"Hardware request","description":"Request a hardware support","serviceDeskId":"10001","groupIds":["13"],"icon":{"id":"12347","_links":{"iconUrls":{"48x48":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12347","24x24":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12347","16x16":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12347","32x32":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12347"}}}}]}

      Returns the requested request types, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-request-type#","title":"Paged of Request Type","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Request Type","type":"object","properties":{"id":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false},"name":{"type":"string"},"description":{"type":"string"},"helpText":{"type":"string"},"serviceDeskId":{"type":"string"},"groupIds":{"type":"array","items":{"type":"string"}},"icon":{"title":"Request Type Icon","type":"object","properties":{"id":{"type":"string"},"_links":{"title":"Request Type Icon Link","type":"object","properties":{"iconUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to access the service desk.
    • Status 404
      Returned if the service desk does not exist.

Creates a new request type for a given service desk. Certain fields cannot be specified on creation. These fields are given default values instead, as shown below.

  • Request Type icon - Question mark icon
  • Request Type groups - Empty, i.e. this request type will be hidden by default and not visible on the customer portal
  • Request Type status mapping - Empty, i.e. no custom status mapping
  • Request Type field mapping - Show the required fields as specified by the issue type

These fields can be updated after creation by a project administrator using the Agent view.

Permissions:
The calling user must be a project administrator for the service desk project.

Request

Example
{"issueTypeId":"10000","name":"Get IT Help","description":"Get IT Help","helpText":"Please tell us clearly the problem you have within 100 words."}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/request-type-create#","title":"Request Type Create","type":"object","properties":{"issueTypeId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"helpText":{"type":"string"}},"additionalProperties":false}

Responses
    • Status 200 - application/json

      Example
      {"id":"11001","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/requesttype/11001"},"name":"Get IT Help","description":"Get IT Help","helpText":"Please tell us clearly the problem you have within 100 words.","serviceDeskId":"10001","groupIds":["12"],"icon":{"id":"12345","_links":{"iconUrls":{"48x48":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12345","24x24":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12345","16x16":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12345","32x32":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12345"}}}}

      Returns the newly created request type
    • Status 400
      Returned if request type name is empty.
    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to create a new request type.
    • Status 404
      Returned if the service desk or issue type does not exist.

Returns a request type for a given request type Id.

Responses
    • Status 200 - application/json

      Example
      {"id":"11001","_links":{"self":"http://host:port/context/rest/servicedeskapi/servicedesk/10001/requesttype/11001"},"name":"Get IT Help","description":"Get IT Help","helpText":"Please tell us clearly the problem you have within 100 words.","serviceDeskId":"10001","groupIds":["12"],"icon":{"id":"12345","_links":{"iconUrls":{"48x48":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12345","24x24":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12345","16x16":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12345","32x32":"http://host:port/context/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12345"}}}}

      Returns the requested request type.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/request-type#","title":"Request Type","type":"object","properties":{"id":{"type":"string"},"_links":{"title":"Self Link","type":"object","properties":{"self":{"type":"string","format":"uri"}},"additionalProperties":false},"name":{"type":"string"},"description":{"type":"string"},"helpText":{"type":"string"},"serviceDeskId":{"type":"string"},"groupIds":{"type":"array","items":{"type":"string"}},"icon":{"title":"Request Type Icon","type":"object","properties":{"id":{"type":"string"},"_links":{"title":"Request Type Icon Link","type":"object","properties":{"iconUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to access the service desk.
    • Status 404
      Returned if the service desk or request type does not exist.

servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field

This resource represents the fields for a request type. A request type defines the fields required to create a customer request.Show more

Returns the fields for a request type, for a given request type Id and service desk Id. These are the fields that are required to create a customer request of that particular request type.

In addition, the following information about the current user's permissions for the request type is returned:

  • * canRaiseOnBehalfOf field - Returns true, if the user has permission to raise requests on behalf of customers. Otherwise, returns false.
  • * canAddRequestParticipants field - Returns true, if the user can add request participants. Otherwise, returns false.

Responses
    • Status 200 - application/json

      Example
      {"requestTypeFields":[{"fieldId":"summary","name":"What do you need?","required":true,"validValues":[],"jiraSchema":{"type":"string","system":"summary"}},{"fieldId":"customfield_10000","name":"Nominee","required":true,"validValues":[],"jiraSchema":{"type":"user","custom":"com.atlassian.jira.plugin.system.customfieldtypes:userpicker","customId":10000}},{"fieldId":"customfield_10001","name":"Gifts","required":true,"validValues":[{"value":"10000","label":"Bottle of Wine","children":[]},{"value":"10001","label":"Threadless Voucher","children":[]},{"value":"10002","label":"2 Movie Tickets","children":[]}],"jiraSchema":{"type":"string","custom":"com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons","customId":10001}}],"canRaiseOnBehalfOf":true,"canAddRequestParticipants":true}

      Returns the requested request type fields and related fields, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/customer-request-create-meta#","title":"Customer Request Create Meta","type":"object","properties":{"requestTypeFields":{"type":"array","items":{"title":"Request Type Field","type":"object","properties":{"fieldId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"validValues":{"type":"array","items":{"$ref":"#/definitions/request-type-field-value"}},"jiraSchema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false,"required":["required"]}},"canRaiseOnBehalfOf":{"type":"boolean"},"canAddRequestParticipants":{"type":"boolean"}},"definitions":{"request-type-field-value":{"title":"Request Type Field Value","type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"children":{"type":"array","items":{"$ref":"#/definitions/request-type-field-value"}}},"additionalProperties":false}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to access the service desk.
    • Status 404
      Returned if the service desk or request type does not exist.

servicedeskapi/servicedesk/{serviceDeskId}/requesttypegroup

This resource represents a request type group in a service desk. Each service desk can have many request type groups. Request type groups are used to organize request types in a service desk.Show more

Returns all request type groups from a service desk, for a given service desk Id. The groups will be in the same order as the order in which they appear on the customer portal

Request
query parameters
parametertypedescription
startint

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

limitint

The maximum number of items to return per page. Default: 100. See the Pagination section for more details.

Responses
    • Status 200 - application/json

      Example
      {"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"http://host:port/context/rest/servicedeskapi","context":"context","next":"http://host:port/context/rest/servicedeskapi/servicedesk//requesttypegroup?start=6&limit=3","prev":"http://host:port/context/rest/servicedeskapi/servicedesk//requesttypegroup?start=0&limit=3"},"values":[{"id":"12","name":"Common Requests"},{"id":"13","name":"Logins and Accounts"},{"id":"14","name":"Servers and Infrastructure"}]}

      Returns the requested request type groups, at the specified page of the results.

      Schema
      {"id":"https://docs.atlassian.com/jira/REST/schema/paged-of-request-type-group#","title":"Paged of Request Type Group","type":"object","properties":{"_expands":{"type":"array","items":{"type":"string"}},"size":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"isLastPage":{"type":"boolean"},"_links":{"title":"Paged Link","type":"object","properties":{"base":{"type":"string","format":"uri"},"context":{"type":"string"},"next":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"values":{"type":"array","items":{"title":"Request Type Group","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

    • Status 401
      Returned if the user is not logged in.
    • Status 403
      Returned if the user does not have permission to access the service desk.
    • Status 404
      Returned if the service desk does not exist.

Appendix

Topics in this section:

Structure of the REST URIs

JIRA Service Desk's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The JIRA Service Desk REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST, and DELETE (see each individual resource to find out which methods are available). URIs for JIRA Service Desk's REST API resources have the following structure:

http://host:port/context/rest/servicedeskapi/resource-name

Note:

  • There is only one version of the JIRA Service Desk REST APIs, which is the version supported by JIRA Service Desk Cloud and the latest JIRA Service Desk Server version.
  • All query parameters for the JIRA Service Desk resources are optional, unless specified otherwise.

Authentication

The JIRA Service Desk REST API uses the same authentication methods as JIRA. The preferred authentication methods are OAuth and HTTP Basic Auth (when using SSL). Other supported methods include: HTTP Cookies and Trusted Applications.

If you are using JIRA Service Desk in a browser you can call the REST API from JavaScript on the page and rely on the authentication that the browser has established.

You can find OAuth code samples in several programming languages at bitbucket.org/atlassian_tutorial/atlassian-oauth-examples.

Pagination

The JIRA Service Desk REST API uses pagination to conserve server resources and limit response size. Pagination is set by default for methods that could return a large collection, although you can modify the pagination parameters. When you make a request to a paged API, the response will wrap the returned values in a JSON object with paging metadata, like this:

Request

http://host:port/context/rest/api-name/resource-name?start=0&limit=10

Response

{
    "start" : 0,
    "limit" : 10,
    "size" : 7,
    "isLastPage" : true,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
        { /* result 5 */ }
        { /* result 4 */ }
        { /* result 5 */ }
        { /* result 6 */ }
    ]
}
  • start - the item used as the first item in the page of results.
  • limit - total number of items to return, subject to server enforced limits.
  • size - number of items to return per page.
  • isLastPage - indicates whether the current page returned is the last page of results.

Clients can use the start, limit, and size parameters to retrieve the desired number of results. Note, each API resource or method may have a different limit on the number of items returned, which means you can ask for more than you are given. The actual number of items returned is an implementation detail and this can be changed over time.

Expansion

In order to simplify API responses, the JIRA Service Desk REST API uses resource expansion. This means the API will only return parts of the resource when explicitly requested.

You can use the expand query parameter to specify the list of entities that you want expanded, identifying each of them by name. For example, appending ?expand=serviceDesk&expand=requestType to a customer request's URI requests the inclusion of the service desk and request type details in the response. We would use the following URL to get that information for JSD-1:

http://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk&expand=requestType

Alternatively, the list of expansions can be passed as a single comma-separated parameter, e.g:

http://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk,requestType

To discover the identifiers for each entity, look at the _expands property in the parent object. In the JSON example below, the resource declares participant, status, sla, requestType and serviceDesk as being expandable.


{
    "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk"
    ],
    "issueId": "107001",
    "issueKey": "HELPDESK-1",
    "requestTypeId": "11001",
    "serviceDeskId": "10001",
 ...

Special headers

The following request and response headers define important metadata for the Service Desk REST resources.

  • X-Atlassian-Token (request) - Methods which accept multipart/form-data will only process requests with X-Atlassian-Token: nocheck.
  • X-ExperimentalApi (request) - Experimental methods will only process requests with X-ExperimentalApi : true. See the Experimental methods section above for more details.
  • X-AUSERNAME (response) - This response header contains either the username of the authenticated user or 'anonymous'.

Field input formats

Summary - A system field that is a single line of text.


"summary": "A summary is one line of text"

Description - A system field that is multiple lines of text.


"description": "A description is multiples lines of text\n separated by\n line feeds",

Components - A system field that is multiple values addressed by 'name'.


"components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ]

Due date - A system field that is a date in 'YYYY-MM-DD' format.


"duedate" : "2015-11-18"

Labels - A system field that is an array of string values.


"labels" : ["examplelabelnumber1", "examplelabelnumber2"]

Checkbox custom field - A custom field that allows you to select a multiple values from a defined list of values. You can address them by 'value' or by 'id'.


"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]

or

"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}]

Date picker custom field - A custom field that is a date in 'YYYY-MM-DD' format.


"customfield_11441" : "2015-11-18"

Date time picker custom field - A custom field that is a datetime in ISO 8601 'YYYY-MM-DDThh:mm:ss.sTZD' format.


"customfield_11442" : "2015-11-18T14:39:00.000+1100"

Labels custom field - A custom field that is an array of strings.


"customfield_11443" : [ "rest_label1", "rest_label2" ]

Number custom field - A custom field that contains a number.


"customfield_11444" : 666

Radio button custom field - A custom field that allows you to select a single value from a defined list of values. You can address them by 'value' or by 'id'.


"customfield_11445" : { "value": "option2" }

or

"customfield_11445" : { "id": 10112 }

Cascading select custom field - A custom field that allows you to select a single parent value and then a related child value. You can address them by 'value' or by 'id'.


"customfield_11447" : { "value": "parent_option1", "child": { "value" : "p1_child1"} }

or

"customfield_11447" : { "id": 10112, "child": { "id" : 10115 } }

Multi-select custom field - A custom field that allows you to select a multiple values from a defined list of values. You can address them by 'value' or by 'id'.


"customfield_11448" : [ { "value": "option1" }, { "value": "option2" } ]

or

"customfield_11448" : [ { "id": 10112 }, { "id": 10115 } ]

Single-select custom field - A custom field that allows you to select a single value from a defined list of values. You can address them by 'value' or by 'id'.


"customfield_11449" : { "value": "option3" }

or

"customfield_11449" : { "id": 10112 }

Multi-line text custom field - A custom field that allows multiple lines of text.


"customfield_11450": "Multiples lines of text\n separated by\n line feeds"

Text custom field - A custom field that allows a single line of text.


"customfield_11450": "a single line of text"

URL custom field - A custom field that allows a URL to be entered.


"customfield_11452" : "http://www.atlassian.com",

Single-user picker custom field - A custom field that allows a single user to be selected.


"customfield_11453" : { "name":"tommytomtomahawk" },

Multi-user picker custom field - A custom field that allows multiple users to be selected.


"customfield_11458" : [ { "name":"inigomontoya" }, { "name":"tommytomtomahawk" }]