openapi: 3.1.0
info:
  title: Fieldwire Plans and Sheets API
  description: |
    Upload PDF drawing sets, manage sheet versioning and floorplan hierarchies,
    organise plans into collections, calibrate scale, and attach Building
    Information Models (BIM) with versioned object trees. Used by general
    contractors, architects, and specialty contractors to keep the latest
    drawings in the field.
  version: v3.1
  contact:
    name: Fieldwire Developer Support
    url: https://developers.fieldwire.com/
  license:
    name: Fieldwire Terms of Service
    url: https://www.fieldwire.com/terms/
servers:
  - url: https://client-api.us.fieldwire.com/api/v3
    description: US Region
  - url: https://client-api.eu.fieldwire.com/api/v3
    description: EU Region
security:
  - BearerAuth: []
tags:
  - name: Floorplans
    description: Floorplan lifecycle, hierarchy, and collections.
  - name: Sheets
    description: Sheet upload and version management.
  - name: Hyperlinks
    description: Single and multi-hyperlink jumps between sheets.
  - name: Building Information Models
    description: BIM and BIM versions attached to a project.
paths:
  /projects/{project_id}/floorplans:
    get:
      operationId: getFloorplansInProject
      summary: Get Floorplans In Project
      tags: [Floorplans]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Floorplan list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Floorplan'
    post:
      operationId: createFloorplanInProject
      summary: Create Floorplan In Project
      description: Create a new floorplan; sheets are uploaded separately via the Attachments API.
      tags: [Floorplans]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FloorplanCreate'
      responses:
        '201':
          description: Created floorplan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Floorplan'
  /projects/{project_id}/floorplans/{floorplan_id}:
    get:
      operationId: getFloorplanById
      summary: Get Floorplan By ID
      tags: [Floorplans]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/FloorplanId'
      responses:
        '200':
          description: Floorplan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Floorplan'
    patch:
      operationId: updateFloorplanById
      summary: Update Floorplan By ID
      tags: [Floorplans]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/FloorplanId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FloorplanUpdate'
      responses:
        '200':
          description: Updated floorplan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Floorplan'
  /projects/{project_id}/sheets:
    get:
      operationId: getSheetsInProject
      summary: Get Sheets In Project
      tags: [Sheets]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Sheet list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sheet'
    post:
      operationId: createSheetInProject
      summary: Create Sheet In Project
      description: Register a new sheet version. The underlying PDF is uploaded via the Attachments S3 token flow.
      tags: [Sheets]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SheetCreate'
      responses:
        '201':
          description: Created sheet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sheet'
  /projects/{project_id}/hyperlinks:
    get:
      operationId: getHyperlinksInProject
      summary: Get Hyperlinks In Project
      tags: [Hyperlinks]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Hyperlink list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Hyperlink'
  /projects/{project_id}/building_information_models:
    get:
      operationId: getBuildingInformationModelsInProject
      summary: Get Building Information Models In Project
      tags: [Building Information Models]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: BIM list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BuildingInformationModel'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
    FloorplanId:
      name: floorplan_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
  schemas:
    Floorplan:
      type: object
      properties:
        id:
          type: integer
          format: int64
        project_id:
          type: integer
          format: int64
        name:
          type: string
        sheet_id:
          type: integer
          format: int64
        parent_id:
          type: integer
          format: int64
          description: Parent floorplan for nested collections.
        floorplan_collection_id:
          type: integer
          format: int64
        position:
          type: number
          format: double
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    FloorplanCreate:
      type: object
      required: [name]
      properties:
        name:
          type: string
        parent_id:
          type: integer
          format: int64
        floorplan_collection_id:
          type: integer
          format: int64
    FloorplanUpdate:
      type: object
      properties:
        name:
          type: string
        parent_id:
          type: integer
          format: int64
        floorplan_collection_id:
          type: integer
          format: int64
    Sheet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        floorplan_id:
          type: integer
          format: int64
        sheet_number:
          type: string
        title:
          type: string
        version:
          type: integer
        original_pdf_url:
          type: string
          format: uri
        thumb_url:
          type: string
          format: uri
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SheetCreate:
      type: object
      required: [floorplan_id]
      properties:
        floorplan_id:
          type: integer
          format: int64
        sheet_number:
          type: string
        title:
          type: string
        attachment_token:
          type: string
          description: AWS POST token identifier for the uploaded PDF.
    Hyperlink:
      type: object
      properties:
        id:
          type: integer
          format: int64
        source_sheet_id:
          type: integer
          format: int64
        target_sheet_id:
          type: integer
          format: int64
        label:
          type: string
        position:
          type: object
          properties:
            x:
              type: number
              format: double
            y:
              type: number
              format: double
    BuildingInformationModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        project_id:
          type: integer
          format: int64
        name:
          type: string
        latest_version_id:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time