Certifyos Facility Note API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer Facility Note API
  version: 1.0.0
servers:
- url: http://localhost:9000
  description: Local Development Server
- url: https://api-service.staging.certifyos.com
  description: Staging Server
- url: https://api-service.internal.certifyos.com
  description: Internal Server
- url: https://api-service.test.certifyos.com
  description: Test Server
- url: https://api-service.demo.certifyos.com
  description: Demo Server
- url: https://api-service.certifyos.com
  description: Production Server
tags:
- name: Facility Note
  description: APIs for managing notes in facility credentialing workflows
paths:
  /facility-credentialing-workflows/{workflowId}/notes:
    get:
      summary: List notes for a facility credentialing workflow
      description: 'Returns all notes attached to the specified facility credentialing workflow. Use this for the facility workflow note thread; for practitioner workflow notes use the Note endpoints.


        Preconditions: workflowId must identify an existing facility credentialing workflow.


        Important — query parameters with no current effect: filter, page, size, startAfterId, endAtId, and order are accepted for compatibility but are not applied by api-layer (not forwarded to the data layer). Results are returned in the order provided by the data layer (typically createdAt descending).


        **Error behavior:** If the data layer returns a 5xx error, that status code is forwarded directly to the caller. Mutating operations (POST, PUT, DELETE) normalize 5xx to 502.


        Returns a GetNotesResponse with totalCount, data, and links.'
      operationId: getFacilityNotes
      tags:
      - Facility Note
      parameters:
      - description: ID of the facility credentialing workflow
        in: path
        required: true
        name: workflowId
        schema:
          type: string
      - description: Accepted for compatibility but not applied by api-layer
        name: endAtId
        in: query
        schema:
          type: string
      - description: Accepted for compatibility but not applied by api-layer
        name: filter
        in: query
        schema:
          type: string
      - description: Accepted for compatibility but not applied by api-layer. Results are returned in the order provided by the data layer (typically createdAt descending).
        name: order
        in: query
        schema:
          type: string
      - description: Accepted for compatibility but not applied by api-layer (default 1)
        name: page
        in: query
        schema:
          type: integer
          format: int32
          default: '1'
      - description: Accepted for compatibility but not applied by api-layer (default 50)
        name: size
        in: query
        schema:
          type: integer
          format: int32
          default: '50'
      - description: Accepted for compatibility but not applied by api-layer
        name: startAfterId
        in: query
        schema:
          type: string
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '502':
          description: Data-layer 5xx forwarded directly (not normalized to 502 as mutating ops are)
        '200':
          description: Note list for the facility workflow (newest first); list query params are not applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNotesResponse'
        '404':
          description: Facility credentialing workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
    post:
      summary: Add a note to a facility credentialing workflow
      description: 'Creates a new note on the specified facility credentialing workflow. Use this to append free-text commentary to the facility note thread.


        Preconditions: request body must contain a non-blank message — the only accepted field in CreateNoteRequest.


        Returns 201 with the created note. Not idempotent — each call creates a distinct note.'
      operationId: createFacilityNote
      tags:
      - Facility Note
      parameters:
      - description: ID of the facility credentialing workflow
        in: path
        required: true
        name: workflowId
        schema:
          type: string
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        description: Note payload — only message is accepted
        content:
          application/json:
            examples:
              createFacilityNote:
                value:
                  message: Site visit complete; awaiting accreditation docs.
            schema:
              $ref: '#/components/schemas/CreateNoteRequest'
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '502':
          description: Downstream DAL failure (5xx ApiException). Mutating ops normalize to 502; GET ops forward the raw DAL status code.
        '201':
          description: Created note, including server-assigned id and audit fields
          content:
            application/json:
              examples:
                facilityNote:
                  value:
                    id: 44444444-4444-4444-8444-444444444444
                    workflowId: 33333333-3333-4333-8333-333333333333
                    data:
                      message: Site visit complete; awaiting accreditation docs.
                    createdBy: 55555555-5555-4555-8555-555555555555
                    createdByName: Example Analyst
                    updatedBy: 55555555-5555-4555-8555-555555555555
                    updatedByName: Example Analyst
                    createdAt: '2024-01-01T00:00:00Z'
                    updatedAt: '2024-01-01T00:00:00Z'
              schema:
                $ref: '#/components/schemas/NoteResponse'
        '400':
          description: 'Invalid request — blank or null message: validation failures return an `ApiError` (errors array); ownership mismatches and null-body errors return a `BadRequestErrorResponse` (errors string array)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '404':
          description: Facility workflow not found (if returned by downstream services)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /facility-credentialing-workflows/{workflowId}/notes/{noteId}:
    put:
      summary: Update the message on a facility credentialing workflow note
      description: 'Updates the message of an existing note on the specified facility credentialing workflow. Use this to correct or revise previously created note text.


        Despite using HTTP PUT, this is a partial update: only the message field is merged; all other note fields are preserved.


        Preconditions: noteId must identify an existing note that belongs to the specified workflowId. Returns 400 for blank/missing message or ownership mismatch. Returns 404 when the note is not found.


        Not idempotent — each call refreshes updatedAt.'
      operationId: updateFacilityNote
      tags:
      - Facility Note
      parameters:
      - description: ID of the note
        in: path
        required: true
        name: noteId
        schema:
          type: string
      - description: ID of the facility credentialing workflow
        in: path
        required: true
        name: workflowId
        schema:
          type: string
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        description: Partial update payload — only message is merged
        content:
          application/json:
            examples:
              updateFacilityNote:
                value:
                  message: 'Updated: accreditation packet received.'
            schema:
              $ref: '#/components/schemas/UpdateNoteRequest'
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '502':
          description: Downstream DAL failure (5xx ApiException). Mutating ops normalize to 502; GET ops forward the raw DAL status code.
        '200':
          description: Updated note after message merge
          content:
            application/json:
              examples:
                facilityNote:
                  value:
                    id: 44444444-4444-4444-8444-444444444444
                    workflowId: 33333333-3333-4333-8333-333333333333
                    data:
                      message: 'Updated: accreditation packet received.'
                    createdBy: 55555555-5555-4555-8555-555555555555
                    createdByName: Example Analyst
                    updatedBy: 55555555-5555-4555-8555-555555555555
                    updatedByName: Example Analyst
                    createdAt: '2024-01-01T00:00:00Z'
                    updatedAt: '2024-01-01T00:00:00Z'
              schema:
                $ref: '#/components/schemas/NoteResponse'
        '400':
          description: 'Invalid request — blank or null message, or note belongs to a different workflow: validation failures return an `ApiError` (errors array); ownership mismatches and null-body errors return a `BadRequestErrorResponse` (errors string array)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
    get:
      summary: Fetch a single facility credentialing workflow note
      description: 'Retrieves a single note by ID, scoped to the specified facility credentialing workflow. Use this when you already hold workflowId and noteId; use the list endpoint for the full thread.


        Preconditions: noteId must identify an existing note that belongs to the specified workflowId.


        Returns 200 with the note. Returns 404 when the note record is not found. Returns 400 when the note exists but belongs to a different workflow.


        **Error behavior:** If the data layer returns a 5xx error, that status code is forwarded directly to the caller. Mutating operations (POST, PUT, DELETE) normalize 5xx to 502. Downstream data-layer errors (ApiException) are forwarded with their original status code and are not described here.'
      operationId: getFacilityNoteById
      tags:
      - Facility Note
      parameters:
      - description: ID of the note
        in: path
        required: true
        name: noteId
        schema:
          type: string
      - description: ID of the facility credentialing workflow
        in: path
        required: true
        name: workflowId
        schema:
          type: string
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '502':
          description: Data-layer 5xx forwarded directly (not normalized to 502 as mutating ops are)
        '200':
          description: Note detail for the specified facility workflow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoteResponse'
        '400':
          description: Note exists but belongs to a different workflow — verify workflowId and noteId pairing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
    delete:
      summary: Remove a facility credentialing workflow note
      description: 'Removes the specified note from the facility credentialing workflow. Use this to remove an annotation that is no longer relevant.


        Preconditions: noteId must identify an existing note that belongs to the specified workflowId.


        Returns 204 with an empty body on success. Returns 404 when the note is not found. Returns 400 when the note exists but belongs to a different workflow.'
      operationId: deleteFacilityNote
      tags:
      - Facility Note
      parameters:
      - description: ID of the note
        in: path
        required: true
        name: noteId
        schema:
          type: string
      - description: ID of the facility credentialing workflow
        in: path
        required: true
        name: workflowId
        schema:
          type: string
      - description: Tenant ID
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '502':
          description: Downstream DAL failure (5xx ApiException). Mutating ops normalize to 502; GET ops forward the raw DAL status code.
        '204':
          description: Note deleted; empty body
        '400':
          description: Note exists but belongs to a different workflow — verify workflowId and noteId pairing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
components:
  schemas:
    ApiError1:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject1'
    NoteData:
      type: object
      required:
      - message
      description: Note data containing message content
      properties:
        message:
          type: string
          examples:
          - This is a note message
          description: The message content of the note
    CreateNoteRequest:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          pattern: \S
    UpdateNoteRequest:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          pattern: \S
    Instant:
      type: string
      format: date-time
      examples:
      - '2022-03-10T16:15:50Z'
    GetNotesResponse:
      type: object
      description: Response containing a list of notes
      properties:
        totalCount:
          type: integer
          format: int64
          examples:
          - 100
          description: Total count of notes returned for the workflow
        data:
          type: array
          items:
            $ref: '#/components/schemas/NoteResponse'
          description: Array of note records
        links:
          $ref: '#/components/schemas/PageLinks1'
          type: object
          description: Optional links envelope retained for compatibility; list query params are not applied
    BadRequestErrorResponse:
      type: object
      description: Standard error response structure for 400 Bad Request validation and client errors
      properties:
        errors:
          type: array
          examples:
          - - Validation failed
            - Required field missing
          items:
            type: string
          description: List of error messages
        errorDetails:
          type: object
          description: Detailed error information with specific validation failures
    PageLinks1:
      type: object
      properties:
        self:
          type: string
        next:
          type: string
        prev:
          type: string
    ErrorObject1:
      type: object
      properties:
        reason:
          type: string
        detail:
          type: string
        httpStatus:
          type: integer
          format: int32
        title:
          type: string
        workflowId:
          type: string
        section:
          type: string
        opIndex:
          type: integer
          format: int32
    NoteResponse:
      type: object
      description: Response containing note information
      properties:
        id:
          type: string
          examples:
          - 44444444-4444-4444-8444-444444444444
          description: Unique identifier for the note
        workflowId:
          type: string
          examples:
          - 22222222-2222-4222-8222-222222222222
          description: ID of the associated credentialing workflow
        data:
          $ref: '#/components/schemas/NoteData'
          type: object
          description: Note data containing message
        createdBy:
          type: string
          examples:
          - 55555555-5555-4555-8555-555555555555
          description: ID of the user who created the note
        createdByName:
          type: string
          examples:
          - Example Analyst
          description: Full name of the user who created the note
        updatedBy:
          type: string
          examples:
          - 55555555-5555-4555-8555-555555555555
          description: ID of the user who last updated the note
        updatedByName:
          type: string
          examples:
          - Example Analyst
          description: Full name of the user who last updated the note
        createdAt:
          $ref: '#/components/schemas/Instant'
          type: string
          examples:
          - '2024-01-01T00:00:00Z'
          description: Timestamp when the note was created
        updatedAt:
          $ref: '#/components/schemas/Instant'
          type: string
          examples:
          - '2024-01-01T00:00:00Z'
          description: Timestamp when the note was last updated
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Certifyos
  source: https://api-service.internal.certifyos.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)