Certifyos Note API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer 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: Note
  description: APIs for managing notes in credentialing workflows
paths:
  /credentialing-workflows/{workflowId}/notes:
    get:
      summary: List notes on a credentialing workflow
      description: 'Returns all free-text notes attached to the specified credentialing workflow. Use this to display or audit annotations on a practitioner credentialing workflow; for facility workflow notes use the Facility Note endpoints.


        Preconditions: workflowId must identify an existing workflow visible to the tenant.


        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: getNotes
      tags:
      - Note
      parameters:
      - description: ID of the 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 workflow (newest first); list query params are not applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNotesResponse'
        '404':
          description: Credentialing workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
    post:
      summary: Add a note to a credentialing workflow
      description: 'Creates a new free-text note on the specified credentialing workflow. Use this to record annotations during the credentialing lifecycle; for facility workflows use the Facility Note create endpoint.


        Preconditions: request body must contain a non-blank message field; no other fields are accepted. createdBy is set from the caller JWT.


        Returns 201 with the created note. Not idempotent — each call creates a distinct note.'
      operationId: createNote
      tags:
      - Note
      parameters:
      - description: ID of the 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:
              createNote:
                value:
                  message: PSV packet reviewed; ready for committee.
            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:
                note:
                  value:
                    id: 44444444-4444-4444-8444-444444444444
                    workflowId: 22222222-2222-4222-8222-222222222222
                    data:
                      message: PSV packet reviewed; ready for committee.
                    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: Workflow not found (if returned by downstream services)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /credentialing-workflows/{workflowId}/notes/{noteId}:
    put:
      summary: Update the message on a credentialing workflow note
      description: 'Updates the message field of an existing note on the specified credentialing workflow. Use this to correct or amend an annotation after it has been created.


        Despite using HTTP PUT, this is a partial update: the service merges only the message into the existing note data; other note fields are preserved. Only message can be changed.


        Preconditions: noteId must identify an existing note that belongs to the specified workflowId. Returns 400 for null/blank message or when the note belongs to a different workflow. Returns 404 when the note is not found.


        updatedBy is set from the caller JWT. Not idempotent — each call refreshes updatedAt.'
      operationId: updateNote
      tags:
      - Note
      parameters:
      - description: ID of the note
        in: path
        required: true
        name: noteId
        schema:
          type: string
      - description: ID of the 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:
              updateNote:
                value:
                  message: 'Updated: waiting on missing license document.'
            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:
                note:
                  value:
                    id: 44444444-4444-4444-8444-444444444444
                    workflowId: 22222222-2222-4222-8222-222222222222
                    data:
                      message: 'Updated: waiting on missing license document.'
                    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 credentialing workflow note
      description: 'Retrieves a single note by its ID from the specified credentialing workflow. Use this when you already have the noteId (for example from the list endpoint).


        Preconditions: noteId must identify an existing note, and the note must belong 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. Returns 404 when the note record is not found. Downstream data-layer errors (ApiException) are forwarded with their original status code and are not described here.'
      operationId: getNoteById
      tags:
      - Note
      parameters:
      - description: ID of the note
        in: path
        required: true
        name: noteId
        schema:
          type: string
      - description: ID of the 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 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 credentialing workflow note
      description: 'Deletes the specified note from the credentialing workflow. Use this to remove an annotation that was created in error or 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: deleteNote
      tags:
      - Note
      parameters:
      - description: ID of the note
        in: path
        required: true
        name: noteId
        schema:
          type: string
      - description: ID of the 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)