PlanRadar Project Reports API

openapi: 3.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>"
servers:
- url: /
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.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '406':
          description: Unsupported Accept Header
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/SiteReport'
    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 />'
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: search
        in: query
        description: search keyword based on which reports are returned
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: page
        in: query
        description: sets the number of pages for the returned reports
        schema:
          type: integer
      - name: pagesize
        in: query
        description: sets the number of reports that should be returned per page <br/>Maximum is 500, default is 100
        schema:
          type: integer
      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.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: unique identifier of the report
        required: true
        schema:
          type: string
      responses:
        '406':
          description: Unsupported Accept Header
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/SiteReport'
    get:
      summary: Returns specific report
      tags:
      - Project Reports
      description: This API returns a specific site report aka project report based on its uuid.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: unique identifier of the report
        required: true
        schema:
          type: string
      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.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        required: true
        schema:
          type: string
      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.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: site_report_uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '406':
          description: Unsupported Accept Header
      requestBody:
        content:
          application/json:
            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.
  /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.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: site_report_uuid
        in: path
        required: true
        schema:
          type: string
      - name: image_uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '406':
          description: Unsupported Accept Header
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        image-caption:
                          type: string
                          description: image caption
    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.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: site_report_uuid
        in: path
        required: true
        schema:
          type: string
      - name: image_uuid
        in: path
        required: true
        schema:
          type: string
      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.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: site_report_uuid
        in: path
        required: true
        schema:
          type: string
      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'
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: ids
        in: query
        schema:
          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'
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: ids
        in: query
        schema:
          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
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: site_report_id
        in: path
        required: true
        schema:
          type: string
      - name: pagesize
        in: query
        description: Maximum is 500, default is 100
        schema:
          type: integer
      - name: last_sync_date
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: filter
        in: query
        schema:
          type: string
      - name: apply_filter
        in: query
        description: filterid, based on which the tickets should be filtered
        schema:
          type: string
      - name: search
        in: query
        description: keyword, based on which the tickets should be filtered
        schema:
          type: string
      responses:
        '404':
          description: Site report Errors
      requestBody:
        content:
          application/json:
            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'
  /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
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: site_report_uuid
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
      - name: pagesize
        in: query
        description: Maximum is 500, default is 100
        schema:
          type: integer
      - name: last_sync_date
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: filter
        in: query
        schema:
          type: string
      - name: apply_filter
        in: query
        description: filterid, based on which the tickets should be filtered
        schema:
          type: string
      - name: search
        in: query
        description: keyword, based on which the tickets should be filtered
        schema:
          type: string
      responses:
        '404':
          description: Site report Errors
      requestBody:
        content:
          application/json:
            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'
components:
  schemas:
    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
  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/