openapi: 3.1.0
info:
  title: Zendesk Requests
  description: Needs a description.
paths:
  /api/v2/requests:
    get:
      operationId: ListRequests
      tags:
        - Requests
      summary: Zendesk Get  Api V2 Requests
      description: |
        #### Allowed for

        * End Users

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      parameters:
        - name: sort_by
          in: query
          description: Possible values are "updated_at", "created_at"
          schema:
            type: string
        - name: sort_order
          in: query
          description: One of "asc", "desc". Defaults to "asc"
          schema:
            type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestsResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestsResponseExample'
    post:
      operationId: CreateRequest
      tags:
        - Requests
      summary: Zendesk Post  Api V2 Requests
      description: >
        Accepts a `request` object that sets one or more properties.


        #### Allowed for


        * End users

        * Anonymous users (rate limit of 5 requests per hour for [trial
        accounts](/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/))


        #### Additional properties


        In addition to the writable request properties in the [JSON Format
        table](#json-format) above, you can set the following properties when
        creating a request.


        | Name                | Type   | Mandatory | Comment

        | ----------------    | -------| --------- | -------

        | comment             | object | yes       | Describes the problem,
        incident, question, or task. See [Request comments](#request-comments)

        | collaborators       | array  | no        | Adds collaborators (cc's)
        to the request. An email notification is sent to them when the ticket is
        created. See [Setting
        collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#setting-collaborators)

        | requester           | object | yes*      | \*Required for anonymous
        requests. Specifies the requester of the anonymous request. See
        [Creating anonymous
        requests](/documentation/ticketing/managing-tickets/creating-and-managing-requests#creating-anonymous-requests)


        #### Creating follow-up requests


        Once a ticket is closed (as distinct from solved), it can't be reopened.
        However, you can create a new request that references the closed ticket.
        To create the follow-up request, include a `via_followup_source_id`
        property in the `request` object that specifies the closed ticket. The
        parameter only works with closed tickets. It has no effect with other
        tickets.
      responses:
        '201':
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestCreateResponseExample'
  /api/v2/requests/{request_id}:
    parameters:
      - $ref: '#/components/parameters/RequestId'
    get:
      operationId: ShowRequest
      tags:
        - Requests
      summary: Zendesk Get  Api V2 Requests Request_id
      description: |
        #### Sideloads

        The following sideloads are supported:

        | Name             | Will sideload
        | ---------------- | -------------
        | users            | The email ccs for a request by side-loading users

        #### Allowed For

        * End Users
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestResponseExample'
    put:
      operationId: UpdateRequest
      tags:
        - Requests
      summary: Zendesk Put  Api V2 Requests Request_id
      description: >
        Updates a request with a comment or collaborators (cc's). The end user
        who created the request can also use it to mark the request as solved.
        The endpoint can't be used to update other request attributes.


        #### Writable properties

        This endpoint can only update the following properties in the request.


        | Name                     | Type    | Required |
        Description                                          |

        | ------------------------ | ------- | -------- |
        ---------------------------------------------------- |

        | comment                  | object  | no       | Adds a comment to the
        request. See [Request comments](#request-comments) |

        | solved                   | boolean | no       | Marks the request as
        solved. Example: `{"request": {"solved": "true"}}`. End users can mark
        requests as solved only if the request's `can_be_solved_by_me` property
        is true. The property is true only when the ticket is assigned to an
        agent and the ticket type is not a problem but a question, task, or
        incident |

        | additional_collaborators | array   | no       | Adds collaborators to
        the request. An email notification is sent to them when the ticket is
        updated. See [Adding
        collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#adding-collaborators)
        |


        #### Allowed For


        * End users
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestCreateResponseExample'
  /api/v2/requests/{request_id}/comments:
    parameters:
      - $ref: '#/components/parameters/RequestId'
    get:
      operationId: ListComments
      tags:
        - Requests
      summary: Zendesk Get  Api V2 Requests Request_id Comments
      description: >
        #### Pagination


        - Cursor pagination (recommended)

        - Offset pagination


        See [Pagination](/api-reference/introduction/pagination/).


        #### Sorting


        By default, comments are sorted by creation date in ascending order.


        When using cursor pagination, use the following parameter to change the
        sort order:


        | Name   | Type   | Required | Comments

        | ------ | ------ | -------- | --------

        | `sort` | string | no       | Possible values are "created_at"
        (ascending order) or "-created_at" (descending order)


        When using offset pagination, use the following parameters to change the
        sort order:


        | Name         | Type   | Required | Comments

        | ------------ | ------ | -------- | --------

        | `sort_by`    | string | no       | One of `created_at`, `updated_at`

        | `sort_order` | string | no       | One of `asc`, `desc`


        #### Allowed For


        * End Users
      parameters:
        - name: since
          in: query
          description: Filters the comments from the given datetime
          schema:
            type: string
        - name: role
          in: query
          description: One of "agent", "end_user". If not specified it does not filter
          schema:
            type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestListCommentsResponseExample'
  /api/v2/requests/{request_id}/comments/{ticket_comment_id}:
    parameters:
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/TicketCommentId'
    get:
      operationId: ShowComment
      tags:
        - Requests
      summary: Zendesk Get  Api V2 Requests Request_id Comments Ticket_comment_id
      description: |
        #### Allowed For

        * End Users
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestGetCommentResponseExample'
  /api/v2/requests/search:
    get:
      operationId: SearchRequests
      tags:
        - Requests
      summary: Zendesk Get  Api V2 Requests Search
      description: >
        Examples:


        * `GET /api/v2/requests/search.json?query=printer`

        * `GET /api/v2/requests/search.json?query=printer&organization_id=1`

        * `GET /api/v2/requests/search.json?query=printer&cc_id=true`

        * `GET /api/v2/requests/search.json?query=printer&status=hold,open`


        #### Pagination


        * Offset pagination only


        See [Using Offset
        Pagination](/api-reference/introduction/pagination/#using-offset-pagination).


        #### Results limit


        The Search Requests endpoint returns up to 1,000 results per query, with
        a maximum of 100 results per page. See
        [Pagination](/api-reference/ticketing/introduction/#pagination). If you
        request a page past the limit (`page=11` at 100 results per page), a 422
        Insufficient Resource Error is returned.


        #### Allowed For


        * End Users
      parameters:
        - name: query
          in: query
          description: >-
            The syntax and matching logic for the string is detailed in the
            [Zendesk Support search
            reference](https://support.zendesk.com/hc/en-us/articles/203663226).
            See also [Query
            basics](/api-reference/ticketing/ticket-management/search/#query-basics)
            in the Tickets API doc.
          schema:
            type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestsResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestsResponseExample'
components:
  schemas:
    RequestsResponse:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/RequestObject'
    RequestResponse:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/RequestObject'
    TicketCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/TicketCommentObject'
    TicketCommentResponse:
      type: object
      properties:
        comment:
          $ref: '#/components/schemas/TicketCommentObject'
tags:
  - name: Requests