PlanRadar Ticket Attachments API

openapi: 3.2.0
info:
  title: PlanRadar's API Documentation Approval Requests V2 Ticket Attachments API
  version: '2.0'
  description: "Welcome to PlanRadar's API documentation, here you can find all the details about our APIs as well as test them online.<br />\n        <h5>Rate Limits</h5>30 requests per minute per account, aggregated across all tokens.<br />\n        If the threshold is exceeded, a 5-minute cooldown is applied to the account, aggregated across all tokens.<br />\n        During the cooldown period, further requests may be rejected until the cooldown ends.<br />\n        In rare cases, an endpoint may have a different rate limit than the default. When that happens, the differing limit will be explicitly stated in the API documentation for that endpoint.<br />\n        <h5>Access Key</h5>In order to be able to access any API you have to create an access token.Therefore you have to follow these steps:-\n        <ul>\n          <li>Go to your profile page and click on Personal Access Tokens on the left side bar</li><li>Click on the 'Create Access Token' top right button in order to create a new access token.</li><li>Copy the created token and paste it into the field that pops up when you click on the 'Authorize' button </li><li>Note: you can copy the token only once.</li><li>Now you can easily access any API</li>\n        </ul>\n        <h5>V2 APIs</h5>We are currently working on upgrading all our APIs to v2, and we recommend that you use v2 APIs if it is available.\n        <p>V2 APIs are faster, robust and more flexible than v1 APIs</p>"
servers:
- url: /
tags:
- name: Ticket Attachments
  description: New APIs to manage all ticket related attachments (Audio, Video, Images, Documents)
paths:
  /api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments:
    get:
      summary: Returns all attachments of one ticket
      tags:
      - Ticket Attachments
      description: "This API returns all attachments of one ticket. An attachment can be of type image, audio, video or document.<br />\n      By default, this endpoint returns both ticket attachments and form field attachments. Use <b>only_ticket_attachments=true</b> to exclude form field attachments.<br />\n      Extra parameters can be added to filter and sort the results.<br />\n      <b>Attachment Sorting:</b>\n      The results can be sorted by the attributes of the attachment object e.g title, attachment type, creation time or creator.\n      The sort is always ascending unless the field name is prefixed with a minus i.e. -created-at.\n      <br /><b>Example#1: </b>sorting attachments by the creator\n      `/attachments?sort=created-by`\n      <br /><b>Example#2: </b>sorting attachments by descending creation time\n       `/attachments?sort=-created-at`\n       <br /><b>Example#3: </b>sorting attachments by attachment type\n       `/attachments?sort=attachable-type`\n       <br /><b>Attachment Filtering:</b>\n      The results can be filtered by attachment types [images, audios, videos, documents]</br>\n      <b>Example:</b>\n      `/attachments?page=1&types[]=images&types[]=videos`\n      "
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: ticket_uuid
        in: path
        required: true
        schema:
          type: string
      - name: last_sync_date
        in: query
        description: is a Unix Timestamp. If it is set, only attachments that were created after that timestamp will be returned
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: pagesize
        in: query
        description: sets the number of attachments that should be returned per page
        schema:
          type: string
      - name: page
        in: query
        description: sets the number of pages for the returned attachments
        schema:
          type: string
      - name: types
        in: query
        description: 'limits the response to specific attachment types: images, audios, videos, documents'
        schema:
          type: array
          items:
            type: string
      - name: only_ticket_attachments
        in: query
        description: when true, excludes form field attachments and returns only regular ticket attachments
        schema:
          type: boolean
      responses:
        '404':
          description: Attachments not found
    post:
      summary: 'Uploads new attachment '
      tags:
      - Ticket Attachments
      description: ' This API is used for uploading a new ticket attachment. <br></br> If you want to attach a google drive document the following array structure is necessary </br> &nbsp; data[attributes][attachment][type] - type is google_drive </br> &nbsp; data[attributes][attachment][token] - token is the google drive access token <br></br><b>Supported document types:</b> PDF, Word (doc/docx), Excel (xls/xlsx), CSV, ODS, ODT, DWG, DXF, EML, MSG, RTF, <b>ZIP, RAR</b>. Images, audio and video files are also accepted.'
      x-websocket-response:
      - channel: customer_{customerId}
        message_type: dms_documents
        payload:
          type: object
          description: Serialized file attachment version with processing status
      - channel: customer_{customerId}
        message_type: dms_log_created
        payload:
          type: object
          description: ActivityLog entry broadcast when attachment is created
          properties:
            node_ids:
              type: array
              items:
                type: string
              description: Encoded node IDs
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: ticket_uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Attachment type is not supported.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        uuid:
                          type: string
                          description: unique identifier of the attachment - is optional
                        attachment:
                          type: string
                          example: data:application/zip;base64,string
                          description: 'Data URI or binary data of the attachment. Supported MIME types include images, audio, video, application/pdf, application/msword, application/vnd.ms-excel, application/zip, application/vnd.rar, application/x-rar-compressed, application/x-rar and other common document types.</br><i style="color:#9999CC"> base64 schema: data:mime_type;base64,string<i>'
                        attachment-name:
                          type: string
                          example: archive.zip
                          description: name of the attachment including extension (e.g. archive.zip, backup.rar) - required when a Data URI is sent
                        caption:
                          type: string
                          example: this is a caption
                          description: caption - is the attachment name by default but can be edited
  /api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments/{attachment_id}:
    get:
      summary: Returns one attachment of one ticket
      tags:
      - Ticket Attachments
      description: This API returns one attachment of one ticket.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: ticket_uuid
        in: path
        required: true
        schema:
          type: string
      - name: attachment_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Attachment Not Found
    delete:
      summary: Deletes specific attachment
      tags:
      - Ticket Attachments
      description: This API is used for deleting a specific ticket attachment based on its id.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: ticket_uuid
        in: path
        required: true
        schema:
          type: string
      - name: attachment_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Attachment Not Found
    put:
      summary: Updates specific attachment
      tags:
      - Ticket Attachments
      description: This API is used for updating a specific ticket attachment based on its id.
      x-websocket-response:
      - channel: customer_{customerId}
        message_type: dms_documents
        payload:
          type: object
          description: Serialized file attachment version with updated attributes
      - channel: customer_{customerId}
        message_type: dms_log_created
        payload:
          type: object
          description: ActivityLog entry broadcast when attachment is updated
          properties:
            node_ids:
              type: array
              items:
                type: string
              description: Encoded node IDs
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: ticket_uuid
        in: path
        required: true
        schema:
          type: string
      - name: attachment_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Attachment Not Found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        attachment:
                          type: string
                          example: 'data: image/png;base64,string'
                          description: 'Data URI or binary data of the attachment</br><i style="color:#9999CC"> base64 schema: data:mime_type;base64,string<i>'
                        attachment-name:
                          type: string
                          example: image.png
                          description: name of the attachment - is required when a Data URI is sent
                        caption:
                          type: string
                          example: this is a caption
                          description: 'caption - is the attachment name by default but can be edited '
        description: "\n      both the attachment itself and the caption can be updated\n      "
  /api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments/batch_delete:
    post:
      summary: 'Deletes multiple attachments at once '
      tags:
      - Ticket Attachments
      description: This API is used for deleting multiple attachments at once.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: ticket_uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Attachments Not Found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/Attachments'
        description: In order to delete multiple attachments at once you have to send an array that contains the ids of the attachments that you want to delete i.e [122, 123]
  /api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments/batch_export:
    post:
      summary: Exports multiple attachments at once
      tags:
      - Ticket Attachments
      description: This API is used for exporting multiple attachments at once.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: ticket_uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Attachments Not Found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/Attachments'
        description: ' In order to export multiple attachments at once you have to send an array that contains the ids of the attachments that you want to export'
components:
  schemas:
    Attachments:
      type: object
      properties:
        attachment-ids:
          type: array
          items:
            type: string
          example: ' ["id1", "id2"]'
          description: 'array of the ids of the attachments that should be deleted</br><i style=color:red> minimum number of ids: 1</i>'
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-PlanRadar-API-Key
      in: header
externalDocs:
  description: Find out more about our development portal
  url: https://www.planradar.com/knowledge-base-overview/