Kno2 Intake and Retrieval API

openapi: 3.0.3
info:
  title: Kno2 Communication API
  description: >-
    Kno2 is a healthcare Interoperability-as-a-Service network. Through a single
    Communication API you SEND, RECEIVE, and FIND patient information - Direct
    Secure Messaging, clinical document exchange, HL7 FHIR, HL7 V2.x, and cloud
    fax - across Kno2's private network, Carequality, eHealth Exchange, and TEFCA
    (Kno2 is a federally designated QHIN).


    SCOPE AND SOURCING: The endpoints modeled in this document are the CONFIRMED
    messaging surface (api/token, api/messages, api/messages/{id}/attachments,
    api/documenttypes, api/directory/validate). They are grounded in Kno2's own
    open-source integrator reference, the Kno2.ApiTestClient
    (https://github.com/Kno2/Kno2.ApiTestClient), whose configuration and helper
    code use these exact relative paths, HTTP verbs, and the OAuth2
    client-credentials token flow. Request/response schemas are MODELED from that
    reference client and Kno2 product documentation; the full field-level
    contracts live behind the login-walled developer portal
    (https://developer.kno2.com) and are provisioned per partner.


    Kno2 also markets FHIR resource query/retrieval and cross-network patient
    record location (Carequality / eHealth Exchange / TEFCA). Those are real
    product capabilities but their specific endpoint paths are partner-provisioned
    and NOT publicly documented, so they are intentionally omitted here rather
    than fabricated.


    BASE HOST: Kno2 does not expose one shared public API host. Each integrator is
    provisioned a per-subscription tenant, e.g. https://{subscription}.kno2fy.com
    in production and https://{subscription}.kno2-stage.com in the staging
    sandbox. Access requires OAuth2 client credentials (client id + secret) and an
    IP allowlist configured by a Kno2 admin.
  version: '1.0'
  contact:
    name: Kno2
    url: https://kno2.com
    email: info@kno2.com
  x-sourcing: >-
    Endpoints, paths, verbs, and the OAuth2 client-credentials token flow are
    CONFIRMED from Kno2's official ApiTestClient (github.com/Kno2/Kno2.ApiTestClient,
    app.config + ApiHelper.cs). Payload schemas are MODELED and simplified.
servers:
  - url: https://{subscription}.kno2fy.com
    description: Production tenant (per-integrator subscription host)
    variables:
      subscription:
        default: your-subscription
        description: The subscription/tenant slug assigned to your Kno2 account.
  - url: https://{subscription}.kno2-stage.com
    description: Staging sandbox tenant (Kno2 Developer Program)
    variables:
      subscription:
        default: your-subscription
        description: The staging subscription/tenant slug assigned to your account.
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: OAuth2 client-credentials token issuance.
  - name: Messaging
    description: SEND surface - draft, populate, attach, and send messages.
  - name: Intake
    description: RECEIVE surface - search, retrieve, and process inbound messages.
  - name: Attachments
    description: Upload, retrieve, and mark clinical document attachments.
  - name: Directory
    description: Validate Direct addresses and list document types.
paths:
  /api/token:
    post:
      operationId: createToken
      tags:
        - Authentication
      summary: Issue an OAuth2 access token
      description: >-
        OAuth2 client-credentials token endpoint. Authenticate with HTTP Basic
        using base64(client_id:client_secret) and grant_type=client_credentials
        to receive a Bearer access token. A grant_type=refresh_token flow is also
        supported. CONFIRMED from ApiTestClient (AuthUri = api/token).
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                    - refresh_token
                  example: client_credentials
                refresh_token:
                  type: string
      responses:
        '200':
          description: An access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/messages:
    get:
      operationId: searchMessages
      tags:
        - Intake
      summary: Search / find messages
      description: >-
        Search messages with filters. The reference intake loop polls with
        statuses=processed and processedtypes=AwaitingEMRExport to find inbound
        messages ready for EMR export (the RECEIVE / FIND queue). CONFIRMED from
        ApiTestClient (MessageSearchTemplate).
      parameters:
        - name: statuses
          in: query
          schema:
            type: string
          example: processed
        - name: processedtypes
          in: query
          schema:
            type: string
          example: AwaitingEMRExport
        - name: isAll
          in: query
          schema:
            type: boolean
        - name: isUnassigned
          in: query
          schema:
            type: boolean
        - name: orderBy
          in: query
          schema:
            type: string
          example: updatedDate
        - name: orderDir
          in: query
          schema:
            type: string
          example: desc
        - name: pageSize
          in: query
          schema:
            type: integer
          example: 10
        - name: pageStart
          in: query
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: A page of messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: createMessageDraft
      tags:
        - Messaging
      summary: Request a new draft message
      description: >-
        Creates a new draft message and returns its identifier. CONFIRMED from
        ApiTestClient (RequestMessageDraft PUTs to api/messages).
      responses:
        '200':
          description: The created draft message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/messages/{id}:
    parameters:
      - $ref: '#/components/parameters/MessageId'
    get:
      operationId: getMessage
      tags:
        - Intake
      summary: Retrieve a message
      description: Retrieves a single message by id. CONFIRMED from ApiTestClient.
      responses:
        '200':
          description: The message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateMessageDraft
      tags:
        - Messaging
      summary: Populate / update a draft message
      description: >-
        Updates a draft message with patient, recipient Direct address, document
        type, and metadata before sending. CONFIRMED from ApiTestClient
        (SendDraft PUTs the message resource to api/messages/{id}).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '200':
          description: The updated message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/messages/{id}/send:
    parameters:
      - $ref: '#/components/parameters/MessageId'
    post:
      operationId: sendMessage
      tags:
        - Messaging
      summary: Send a message
      description: >-
        Releases/sends the populated draft over Direct Secure Messaging or
        document exchange. CONFIRMED from ApiTestClient (SendRelease POSTs to
        api/messages/{id}/send).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '200':
          description: The message was accepted for sending.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/messages/{id}/process:
    parameters:
      - $ref: '#/components/parameters/MessageId'
    post:
      operationId: processMessage
      tags:
        - Intake
      summary: Process a message (read event)
      description: >-
        Marks a message as processed / records a read event. CONFIRMED from
        ApiTestClient (MessageReadEventUriTemplate = api/messages/{id}/process).
      responses:
        '200':
          description: The message was marked processed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/messages/{id}/attachments/{attachmentId}:
    parameters:
      - $ref: '#/components/parameters/MessageId'
      - $ref: '#/components/parameters/AttachmentId'
    get:
      operationId: getAttachment
      tags:
        - Attachments
      summary: Retrieve an attachment
      description: >-
        Retrieves attachment metadata or its binary content (CCDA, PDF, image,
        HL7). CONFIRMED from ApiTestClient (AttachmentsUriTemplate).
      responses:
        '200':
          description: The attachment metadata or content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: uploadAttachment
      tags:
        - Attachments
      summary: Upload an attachment
      description: >-
        Uploads a clinical document to a draft message as multipart/form-data.
        CONFIRMED from ApiTestClient (UploadAttachment POSTs multipart content to
        api/messages/{id}/attachments/{attachmentId}).
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                documentType:
                  type: string
      responses:
        '200':
          description: The uploaded attachment metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/messages/{id}/attachments/{attachmentId}/read:
    parameters:
      - $ref: '#/components/parameters/MessageId'
      - $ref: '#/components/parameters/AttachmentId'
    put:
      operationId: markAttachmentRead
      tags:
        - Attachments
      summary: Mark an attachment as read
      description: >-
        Records that an attachment has been read/consumed. CONFIRMED from
        ApiTestClient (AttachmentReadUriTemplate =
        api/messages/{id}/attachments/{attachmentid}/read).
      responses:
        '200':
          description: The attachment was marked read.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/documenttypes:
    get:
      operationId: listDocumentTypes
      tags:
        - Directory
      summary: List document types
      description: >-
        Lists the document types available to the current subscription. CONFIRMED
        from ApiTestClient (DocumentTypesUriTemplate = api/documenttypes).
      responses:
        '200':
          description: A collection of document types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/directory/validate:
    get:
      operationId: validateAddresses
      tags:
        - Directory
      summary: Validate Direct addresses
      description: >-
        Validates one or more Direct Secure Messaging addresses / endpoints before
        sending. CONFIRMED from ApiTestClient (DirectoryValidateTemplate =
        api/directory/validate).
      parameters:
        - name: addresses
          in: query
          description: One or more Direct addresses to validate.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: A map of address to validity.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer access token obtained from POST /api/token.
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic with base64(client_id:client_secret), used only against
        /api/token to obtain a Bearer token.
  parameters:
    MessageId:
      name: id
      in: path
      required: true
      description: The message identifier.
      schema:
        type: string
    AttachmentId:
      name: attachmentId
      in: path
      required: true
      description: The attachment identifier.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication failed or the token is missing/expired.
    NotFound:
      description: The requested resource was not found.
  schemas:
    AuthResponse:
      type: object
      description: MODELED - OAuth2 token response.
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 3600
        refresh_token:
          type: string
    Message:
      type: object
      description: >-
        MODELED - a Kno2 message resource. Field set simplified from the
        ApiTestClient MessageResource and product docs; the authoritative schema
        is provisioned per partner via developer.kno2.com.
      properties:
        id:
          type: string
        status:
          type: string
          example: draft
        subject:
          type: string
        patient:
          $ref: '#/components/schemas/Patient'
        recipients:
          type: array
          items:
            type: string
            description: Direct Secure Messaging address.
        documentType:
          type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        updatedDate:
          type: string
          format: date-time
    Patient:
      type: object
      description: MODELED - patient demographics attached to a message.
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        gender:
          type: string
        mrn:
          type: string
          description: Medical record number.
    Attachment:
      type: object
      description: MODELED - a clinical document attachment.
      properties:
        id:
          type: string
        fileName:
          type: string
        mediaType:
          type: string
          example: application/pdf
        documentType:
          type: string
        size:
          type: integer