PlanRadar Project Reports API

swagger: '2.0'
info:
  title: PlanRadar's API Documentation Approval Requests V2 Project Reports 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>"
basePath: /
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: Project Reports
  description: Manage project reports in your account
paths:
  /api/v1/{customer_id}/projects/{project_id}/site_reports:
    post:
      summary: Creates report
      tags:
      - Project Reports
      description: This API is used for creating a site report aka project report based on a report template.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: report
        in: body
        schema:
          type: object
          properties:
            data:
              type: object
              properties:
                attributes:
                  $ref: '#/definitions/SiteReport'
      responses:
        '406':
          description: Unsupported Accept Header
    get:
      summary: Returns all reports
      tags:
      - Project Reports
      description: 'This API returns all Project Reports aka project reports of a specfic project based on its id. Without any extra parameters it will return the first 100 reports ordered by ascending ID. Extra parameters can be added to sort the results. The sort is always ascending unless the field name is prefixed with a minus (U+002D HYPHEN-MINUS, "-") i.e. `-id` or `id`.<br /><b>Report Sorting:</b> Reports can be sorted by id: sequential-id, name: title, template: site-report-template-id, status: status, author: user-id, creation date: created-at, update date: updated-at.<br /><b>Example#1: </b> `/site_reports?sort=-sequential-id`<br /><b>Example#2: </b> `/site_reports?sort=created-at`<br />'
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: search
        in: query
        type: string
        description: search keyword based on which reports are returned
      - name: sort
        in: query
        type: string
      - name: page
        in: query
        type: integer
        description: sets the number of pages for the returned reports
      - name: pagesize
        in: query
        type: integer
        description: sets the number of reports that should be returned per page <br/>Maximum is 500, default is 100
      responses:
        '406':
          description: Unsupported Accept Header
  /api/v1/{customer_id}/projects/{project_id}/site_reports/{uuid}:
    put:
      summary: Updates specfic report
      tags:
      - Project Reports
      description: This API is used for updating a specific site report aka project report based on its uuid.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: uuid
        in: path
        type: string
        description: unique identifier of the report
        required: true
      - name: report
        in: body
        schema:
          type: object
          properties:
            data:
              type: object
              properties:
                attributes:
                  $ref: '#/definitions/SiteReport'
      responses:
        '406':
          description: Unsupported Accept Header
    get:
      summary: Returns specific report
      tags:
      - Project Reports
      description: This API returns a specific site report aka project report based on its uuid.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: uuid
        in: path
        type: string
        description: unique identifier of the report
        required: true
      responses:
        '406':
          description: Unsupported Accept Header
    delete:
      summary: Deletes specific report
      tags:
      - Project Reports
      description: This API is used for deleting a specific site report aka project report based on its uuid.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: uuid
        in: path
        type: string
        required: true
      responses:
        '406':
          description: Unsupported Accept Header
  /api/v1/{customer_id}/projects/{project_id}/site_reports/{site_report_uuid}/image:
    post:
      summary: Attaches image to specific report
      tags:
      - Project Reports
      description: This API is used for attaching an image to a specific project report.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: site_report_uuid
        in: path
        type: string
        required: true
      - name: image_data
        in: body
        schema:
          type: object
          properties:
            data:
              type: object
              properties:
                attributes:
                  type: object
                  properties:
                    image-caption:
                      type: string
                      description: image caption
                    image:
                      type: string
                      example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABwAAAAYCAYAAADpnJ2CAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACOSURBVEhLY3jx7cN/euJRC6mORy2kOh61kOp4aFj4/Ov7/8++vP///Ms7IE0aJtlCkKbJ+5//z1n2+H/MnMf/PSc8IgmTZCHIsp6dT//HzyPPMhAm2kJQMD7++OZ/zhLyLIJhkix89OHV/+jZ2A0iFpNm4ftXWA0hBZPsQ2yGkIJHLYTjUQuJxXS28NF/AGstLixx12vdAAAAAElFTkSuQmCC
                      description: base64 data URI or multipart file upload
                    uuid:
                      type: string
                      example: 8f1c50d8-96d3-4b54-bb5f-1145eeccb7bb
                      description: Optional client-generated UUID. If an attachment with this UUID already exists, it is returned instead of creating a new one. If omitted, the server assigns a random UUID.
                    created-at:
                      type: string
                      format: date-time
                      description: Optional client-provided created_at timestamp. Defaults to the current time.
                    updated-at:
                      type: string
                      format: date-time
                      description: Optional client-provided updated_at timestamp. Defaults to the current time.
      responses:
        '406':
          description: Unsupported Accept Header
  /api/v1/{customer_id}/projects/{project_id}/site_reports/{site_report_uuid}/image/{image_uuid}:
    put:
      summary: Updates image caption
      tags:
      - Project Reports
      description: This API is used for updating the caption of a specfic image that is attached to a specific site report aka project report. Only the caption of the image of a draft can be updated.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: site_report_uuid
        in: path
        type: string
        required: true
      - name: image_uuid
        in: path
        type: string
        required: true
      - name: image_data
        in: body
        schema:
          type: object
          properties:
            data:
              type: object
              properties:
                attributes:
                  type: object
                  properties:
                    image-caption:
                      type: string
                      description: image caption
      responses:
        '406':
          description: Unsupported Accept Header
    delete:
      summary: Deletes specific image
      tags:
      - Project Reports
      description: This API is used for deleting a specific image that is attached to a specific site report aka project report. Only an image of a draft can be deleted.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: site_report_uuid
        in: path
        type: string
        required: true
      - name: image_uuid
        in: path
        type: string
        required: true
      responses:
        '406':
          description: Unsupported Accept Header
  /api/v1/{customer_id}/projects/{project_id}/site_reports/{site_report_uuid}/clone:
    get:
      summary: Clones specific report
      tags:
      - Project Reports
      description: This API is used for cloning a specific site report aka project report.
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: site_report_uuid
        in: path
        type: string
        required: true
      responses:
        '406':
          description: Unsupported Accept Header
  /api/v1/{customer_id}/projects/{project_id}/site_reports/export_reports:
    get:
      summary: Exports reports as Excel file
      tags:
      - Project Reports
      description: 'This API is used for exporting one or multiple project reports as an Excel file. It takes the id/s of the report/s and exports it/them.<br > <b>Example:</b> export_reports?ids[]=wjb&ids[]=nak<br > Reports can be sorted before being exported. They can be sorted by id: sequential-id, name: title, template: site-report-template-id, status: status, author: user-id, creation date: created-at and update date: updated-at. The sort is always ascending unless the field name is prefixed with a minus (U+002D HYPHEN-MINUS, "-") i.e. `-id` or `id.<br ><b>Example:</b> export_reports?ids[]=wjb&ids[]=nak&ids[]=pxq&sort=title<br >It is also possible to export reports filtered by the template-id of one of the customer''s created templates or by a searched keyword. Therefore you have to set the project_id to 0.<br ><b>Example:</b> export_reports?search=template&filter[template_id]=ojk'
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: sort
        in: query
        type: string
      - name: ids
        in: query
        type: array
        items:
          type: string
      responses:
        '404':
          description: 'Project Not Found '
        '406':
          description: Unsupported Accept Header
  /api/v1/{customer_id}/projects/{project_id}/site_reports/download_combined_reports:
    get:
      summary: Exports reports as PDF file
      tags:
      - Project Reports
      description: 'This API is used for exporting one or multiple project reports as a PDF file. It takes the id/s of the report/s and exports it/them.<br ><b>Example:</b> download_combined_reports?ids[]=bjk&ids[]=pxq<br > in this API the user can exporting all project reports as a PDF file. It takes the -id/s of the report/s to exclued it/them from exports.<br ><b>Example:</b> download_combined_reports?export_all=true&-ids[]=doqnn&-ids[]=zxgdp<br > Reports can be sorted before being exported. They can be sorted by id: sequential-id, name: title, template: site-report-template-id, status: status, author: user-id, creation date: created-at and update date: updated-at. The sort is always ascending unless the field name is prefixed with a minus (U+002D HYPHEN-MINUS, "-") i.e. `-id` or `id.<br ><b>Example:</b> download_combined_reports?ids[]=jdg&ids[]=pxq&sort=status<br >It is also possible to export reports filtered by the template-id of one of the customer''s created templates or by a searched keyword. Therefore you have to set the project_id to 0.<br ><b>Example:</b> download_combined_reports?search=template&filter[template_id]=ojk'
      produces:
      - application/json
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: sort
        in: query
        type: string
      - name: ids
        in: query
        type: array
        items:
          type: string
      responses:
        '404':
          description: 'Project Not Found '
        '406':
          description: Unsupported Accept Header
  /api/v2/{customer_id}/projects/{project_id}/site_reports/{site_report_id}/site_report_tickets/attach_tickets:
    post:
      summary: Attach Ticket to Site report
      tags:
      - Project Reports
      security:
      - apiKey: []
      description: Add ticket to site report
      x-websocket-response:
        channel: user_{customerId}_{userId}
        message_type: cable-events
        payload:
          type: object
          properties:
            assign-ticket-to-site-report-finished:
              type: boolean
              description: Always true, signals completion
      produces:
      - application/json
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: site_report_id
        in: path
        type: string
        required: true
      - name: pagesize
        in: query
        type: integer
        description: Maximum is 500, default is 100
      - name: last_sync_date
        in: query
        type: string
      - name: sort
        in: query
        type: string
      - name: filter
        in: query
        type: string
      - name: apply_filter
        in: query
        type: string
        description: filterid, based on which the tickets should be filtered
      - name: search
        in: query
        type: string
        description: keyword, based on which the tickets should be filtered
      - name: task
        in: body
        schema:
          type: object
          properties:
            data:
              type: object
              properties:
                attributes:
                  type: object
                  properties:
                    uuids:
                      type: array
                      items:
                        type: string
        description: 'uuids: array of tickets uuids will be attached to a site report'
      responses:
        '404':
          description: Site report Errors
  /api/v2/{customer_id}/projects/{project_id}/site_reports/{site_report_id}/site_report_tickets/unattach_tickets:
    post:
      summary: Unattach tickets from site report
      tags:
      - Project Reports
      security:
      - apiKey: []
      description: Unattach tickets from site report
      x-websocket-response:
        channel: user_{customerId}_{userId}
        message_type: cable-events
        payload:
          type: object
          properties:
            unassign-ticket-from-site-report-finished:
              type: boolean
              description: Always true, signals completion
      produces:
      - application/json
      parameters:
      - name: customer_id
        in: path
        type: string
        required: true
      - name: project_id
        in: path
        type: string
        required: true
      - name: site_report_uuid
        in: path
        type: string
        required: true
      - name: page
        in: query
        type: integer
      - name: pagesize
        in: query
        type: integer
        description: Maximum is 500, default is 100
      - name: last_sync_date
        in: query
        type: string
      - name: sort
        in: query
        type: string
      - name: filter
        in: query
        type: string
      - name: apply_filter
        in: query
        type: string
        description: filterid, based on which the tickets should be filtered
      - name: search
        in: query
        type: string
        description: keyword, based on which the tickets should be filtered
      - name: task
        in: body
        schema:
          type: object
          properties:
            data:
              type: object
              properties:
                attributes:
                  type: object
                  properties:
                    uuids:
                      type: array
                      items:
                        type: string
        description: 'uuids: array of tickets uuids will be unattached from a site report'
      responses:
        '404':
          description: Site report Errors
definitions:
  SiteReport:
    type: object
    properties:
      uuid:
        type: string
        example: 558f3c6e-105e-40a4-9625-7f6569a703a3
        description: unique identifier of the site report - is optional
      title:
        type: string
        example: new_site_report
        description: title of the site report - is optional, will be generated if left empty
      template-id:
        type: string
        example: yyw
        description: id of the created site report template that is being used
      template-version:
        type: integer
        example: 1
        description: version of the template - is changed as soon as the form is updated
      fields-values:
        type: object
        description: 'contains all fields and their values - depends on the form that is used for the site report, example: "Textfeld 106": "hello world" (in this case the form field is a text field)'
      annotations:
        type: object
        description: data of the annotations of the form - annotations can be notes, signatures etc. Per-annotation `isSignature` and `isDrawnNaturally` attributes must be booleans (true/false); legacy numeric (0/1) and string ("true"/"false"/"1"/"0") variants are accepted and coerced.
      status:
        type: string
        example: draft
        description: status of the site report, the only allowed values are "submitted" and "draft" - sets whether the created report is saved as a draft or is submitted
securityDefinitions:
  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/