openapi: 3.1.0
info:
  title: Bluebeam Studio API
  description: >-
    The Bluebeam Studio API enables programmatic access to Studio Sessions for
    document collaboration, markup management, and PDF review workflows. OAuth 2.0
    REST APIs allow third-party applications to create and manage studio sessions,
    retrieve markup data, and integrate document annotations into AEC construction
    workflows.
  version: 1.0.0
  contact:
    name: Bluebeam Developer Portal
    url: https://developers.bluebeam.com/

servers:
  - url: https://api.bluebeam.com
    description: Bluebeam Studio API

security:
  - oauth2: []

tags:
  - name: Documents
    description: Document management within sessions
  - name: Markups
    description: Markup and annotation access
  - name: Sessions
    description: Studio Session management
  - name: Users
    description: Session user management

paths:
  /studio/v1/sessions:
    get:
      operationId: listSessions
      summary: List sessions
      description: Retrieve a list of Studio Sessions the authenticated user has access to.
      tags: [Sessions]
      parameters:
        - name: status
          in: query
          description: Filter by session status
          schema:
            type: string
            enum: [Active, Finished, Pending]
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createSession
      summary: Create a Studio Session
      description: >-
        Create a new Bluebeam Studio Session for collaborative document review and markup.
        Sessions can be configured with attendees, invitation settings, and file upload permissions.
      tags: [Sessions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRequest'
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          $ref: '#/components/responses/BadRequest'

  /studio/v1/sessions/{sessionId}:
    get:
      operationId: getSession
      summary: Get session by ID
      description: Retrieve full details for a specific Studio Session.
      tags: [Sessions]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      operationId: updateSession
      summary: Update session
      description: Update session settings such as name, status, or invitation permissions.
      tags: [Sessions]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionUpdate'
      responses:
        '200':
          description: Session updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'

  /studio/v1/sessions/{sessionId}/finish:
    post:
      operationId: finishSession
      summary: Finish/close a session
      description: Close a Studio Session, preventing further markups from attendees.
      tags: [Sessions]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session finished
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'

  /studio/v1/sessions/{sessionId}/documents:
    get:
      operationId: listSessionDocuments
      summary: List session documents
      description: Retrieve all documents uploaded to a Studio Session.
      tags: [Documents]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'

    post:
      operationId: uploadSessionDocument
      summary: Upload document to session
      description: Upload a PDF document to a Studio Session.
      tags: [Documents]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: PDF file to upload
                fileName:
                  type: string
      responses:
        '201':
          description: Document uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'

  /studio/v1/sessions/{sessionId}/documents/{documentId}/markups:
    get:
      operationId: getDocumentMarkups
      summary: Get document markups
      description: >-
        Retrieve all markups (annotations, comments, stamps) from a document
        in a Studio Session.
      tags: [Markups]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
        - name: documentId
          in: path
          required: true
          schema:
            type: string
        - name: pageNumber
          in: query
          description: Filter markups by page number
          schema:
            type: integer
        - name: markupType
          in: query
          schema:
            type: string
            enum: [Highlight, Ellipse, Rectangle, Polyline, Cloud, Stamp, Text, Note, Measurement]
      responses:
        '200':
          description: Document markups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkupList'

  /studio/v1/sessions/{sessionId}/users:
    get:
      operationId: listSessionUsers
      summary: List session users/attendees
      description: Retrieve all users invited to or attending a Studio Session.
      tags: [Users]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionUserList'

    post:
      operationId: inviteSessionUser
      summary: Invite user to session
      description: Invite a user to a Studio Session by email address.
      tags: [Users]
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                permission:
                  type: string
                  enum: [ReadOnly, MarkupOnly, FullAccess]
                  default: MarkupOnly
      responses:
        '201':
          description: User invited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionUser'

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://authserver.bluebeam.com/auth/oauth/authorize
          tokenUrl: https://authserver.bluebeam.com/auth/oauth/token
          scopes:
            full: Full access to Bluebeam Studio API
            jobs.read: Read session data
            jobs.create: Create and manage sessions

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Session:
      type: object
      properties:
        id:
          type: string
          description: Studio Session ID
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [Active, Finished, Pending]
        inviteUrl:
          type: string
          format: uri
          description: URL for users to join the session
        defaultPermission:
          type: string
          enum: [ReadOnly, MarkupOnly, FullAccess]
        allowInvitations:
          type: boolean
        restricted:
          type: boolean
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        documentCount:
          type: integer
        userCount:
          type: integer

    SessionRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        description:
          type: string
        defaultPermission:
          type: string
          enum: [ReadOnly, MarkupOnly, FullAccess]
          default: MarkupOnly
        allowInvitations:
          type: boolean
          default: true
        restricted:
          type: boolean
          default: false
        invitees:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                format: email
              permission:
                type: string
                enum: [ReadOnly, MarkupOnly, FullAccess]

    SessionUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        defaultPermission:
          type: string
          enum: [ReadOnly, MarkupOnly, FullAccess]
        allowInvitations:
          type: boolean

    SessionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        total:
          type: integer
        offset:
          type: integer

    Document:
      type: object
      properties:
        id:
          type: string
        sessionId:
          type: string
        name:
          type: string
        pageCount:
          type: integer
        fileSize:
          type: integer
          description: File size in bytes
        uploadedBy:
          type: string
        uploadedAt:
          type: string
          format: date-time
        markupCount:
          type: integer

    DocumentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Document'

    Markup:
      type: object
      properties:
        id:
          type: string
        documentId:
          type: string
        sessionId:
          type: string
        pageNumber:
          type: integer
        markupType:
          type: string
          enum: [Highlight, Ellipse, Rectangle, Polyline, Cloud, Stamp, Text, Note, Measurement]
        subject:
          type: string
        comment:
          type: string
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        color:
          type: string
        status:
          type: string
          enum: [None, Accepted, Rejected, Cancelled, Completed]
        space:
          type: object
          properties:
            x:
              type: number
            y:
              type: number
            width:
              type: number
            height:
              type: number

    MarkupList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Markup'
        total:
          type: integer

    SessionUser:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        permission:
          type: string
          enum: [ReadOnly, MarkupOnly, FullAccess]
        status:
          type: string
          enum: [Invited, Active, Left]
        invitedAt:
          type: string
          format: date-time
        lastActiveAt:
          type: string
          format: date-time

    SessionUserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SessionUser'

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string