PlanRadar Documents API

openapi: 3.2.0
info:
  title: PlanRadar's API Documentation Documents 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.
servers:
- url: /
tags:
- name: Documents
  description: Manage your documents in PlanRadar, adding documents to a ticket is covered in the 'Tickets' section
paths:
  /api/v1/{customer_id}/projects/{project_id}/documents/:
    get:
      summary: Retrieves All Documents
      tags:
      - Documents
      description: 'Retrieve all documents in a specific project. Documents are returned with respect to the role of the authenticated user in the project.


        Without any extra parameters it will return the first 100 documents ordered by ID ascending. Extra parameters can be added to filter and sort the results.


        Document Types Dictionary: [pdf = 1, excel = 2, word = 3, dwg = 4, dxf = 5]'
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        description: Authenticated user must be a member of this project
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: 'default: 1'
        schema:
          type: integer
      - name: pagesize
        in: query
        description: Maximum is 500, default is 100
        schema:
          type: integer
      - name: last_sync_date
        in: query
        description: Only retrieve documents that were created after a specific timestamp
        schema:
          type: string
      - name: sort
        in: query
        description: Field name to sort the results based on it, sort is always ascending unless the field name is prefixed with a minus (U+002D HYPHEN-MINUS, “-“)  i.e. "-id" or "id"
        schema:
          type: string
      - name: filter
        in: query
        description: Filter documents based on specific field values, for example filter[component_id]=1, will only return documents created in the provided component_id
        schema:
          type: string
      responses:
        '404':
          description: Documents not found
      operationId: getApiV1ByCustomerIdProjectsByProjectIdDocuments
      x-operation-id-source: derived
    post:
      summary: Create New Document
      tags:
      - Documents
      security:
      - apiKey: []
      x-websocket-response:
        channel: customer_{customerId}
        message_type: documents
        payload:
          type: object
          properties:
            is_scanned:
              type: boolean
              description: Whether the document has been scanned
            is_processed:
              type: boolean
              description: Whether processing is complete
            updated_at:
              type: string
              format: date-time
            err:
              type: object
              description: Error details if processing failed
      description: 'API to upload new documents.


        Supported Types: [PDF, Excel, Word, DWG, DXF]


        This API accepts both base64 and multipart data.


        Base64 Uploads

        Set `is_base64` to `true`, add the base64 encoded document to the `document` field, add the uploaded file name to `filename`


        Multipart Uploads

        Set `is_base64` to `false`, set the value of the `document` field to be the multipart data'
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '403':
          description: Invalid Data Provided
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/Document'
      operationId: postApiV1ByCustomerIdProjectsByProjectIdDocuments
      x-operation-id-source: derived
  /api/v1/{customer_id}/projects/{project_id}/documents/{document_uuid}:
    delete:
      summary: Delete one Document
      tags:
      - Documents
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: document_uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Document Not found
      operationId: deleteApiV1ByCustomerIdProjectsByProjectIdDocumentsByDocumentUuid
      x-operation-id-source: derived
    get:
      summary: Load one Document
      tags:
      - Documents
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: document_uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Document Not found
      operationId: getApiV1ByCustomerIdProjectsByProjectIdDocumentsByDocumentUuid
      x-operation-id-source: derived
    put:
      summary: Update Document
      tags:
      - Documents
      description: To rename the document, just send the title attribute, to update the whole document please check document creation API documentation.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Document found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/Document'
      operationId: putApiV1ByCustomerIdProjectsByProjectIdDocumentsByDocumentUuid
      x-operation-id-source: derived
components:
  schemas:
    Document:
      type: object
      properties:
        title:
          type: string
          example: document1
          description: If no value provided the file name will be used as a title
        component-id:
          type: integer
          description: Only set the value of this field if you want to attach the document to specific layer, if you added a ticket id, to component will be set automatically.
        is-base64:
          type: boolean
          description: set to true if the document is base64 encoded
        async:
          type: boolean
          description: by default documents are processed asynchronously, set the flag to false if you don't want that
        document:
          type: string
          example: ZW1wdHlkb2N1bWVudAo=
          description: the actual document to be uploaded, or the base64 encoded document if you set the is-base64 to true
        uuid:
          type: string
          example: 8f1c50d8-96d3-4b54-bb5f-1145eeccb7bb
          description: Document UUID, should be unique, if empty the server will assign a random UUID
        ticket-id:
          type: string
          description: If you want attach the document to a specific ticket, use the ticket UUID here, if not leave empty
        filename:
          type: string
          example: document1.pdf
          description: Set the name of the uploaded file, only use it when uploading base64 encoded documents
  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/