Shepherd Veterinary Software Soap Imaging API

openapi: 3.2.0
info:
  version: v1
  title: Shepherd Open API (v2.248.0.39) Soap Imaging API
  description: 'Production Base URL: https://open-api.shepherd.vet/pav2/


    Production App URL: https://app.shepherd.vet/


    Production Documentation URL: https://app.shepherd.vet/swagger/


    Sandbox Base URL: https://demo-open-api.shepherd.vet/pav2/


    Sandbox App URL: https://demo.shepherd.vet/


    Sandbox Documentation URL: https://demo.shepherd.vet/swagger


    Authorization: The integration is authorized by providing two headers in the API call


    X-Integration-Private-Key - this contains the private key from your credentials

    X-Integration-Public-Key - this contains the public key from your credentials


    Additionally, for all requests other than Clinic, the X-Clinic-Id header must be provided with the value of the clinic entity id for which you are running the API requests. You can get the entity id by calling the Clinic endpoint. If authorization fails, the request returns HTTP status 401 and the response body is one of the messages below. Missing X-Integration-Public-Key header - the public key header is absent from the request. Missing X-Integration-Private-Key header - the private key header is absent from the request. Missing X-Clinic-Id header - the clinic identifier header is absent, and the endpoint is clinic scoped. Incorrect API keys provided - both key headers were supplied, but the public key matches no integration, or the private key is not valid for that integration. Integration not enabled for the provided clinic - the key pair is valid, but the integration is not enabled and active for the clinic supplied in X-Clinic-Id. NEW: Each API call will count against your RPH and RPM limits. Once you exhaust those limits, requests will start returning HTTP status 429. The RPH is set to 12000 and RPM to 800 (subject to change). Where an endpoint supports searchQuery, a query longer than 500 characters may return HTTP status 400 with ERROR_MESSAGES.SEARCH_PHRASE.TOO_LONG, and a query with more than 10 words may return HTTP status 400 with ERROR_MESSAGES.SEARCH_PHRASE.TOO_MANY_PHRASES. NOTE: Since this API is WIP, we would be happy to hear any feedback and to implement additional filtering/sorting options etc. **Endpoints:

    All endpoints are POST requests that accept JSON bodies. The common request properties for all endpoints are:**


    rpp::int - The number of items to return per page. The max is 1000. Defaults to 10. page::int - The page number. Defaults to 1. sort::string - Which field to sort by. Needs to be in "field|order" format, where order is either "asc" or "desc". All top-level properties should be sortable, only some nested-fields work and you should probably not use them until this API reaches production and we settle on which nested-field sortings we will support. Default depends on endpoint, usually "id|asc". embed::string - Comma-separated values for nested-fields you want to fetch (eg. "clientPhones,clientPhones.phoneType" on Client endpoint). If a specific embed is not requested, the response will contain either null or an empty array for that value. No default. dateCreatedFrom::date

    dateCreatedTo::date

    dateUpdatedFrom::date

    dateUpdatedTo::date

    - Date range filters for either the creation date or last update date. - You can pass in either one end or both of them. *


    * Only the date filters listed on an endpoint''s request model are supported; sending another one, or a ''From'' later than its ''To'', returns HTTP status 400. The request responses will come back as a JSON object. The common response properties for all endpoints are:


    embed::string - Lists the embed used in the request. This may sometimes be different from what you sent in, if in the future we add that some embeds get set automatically on certain endpoints

    links::object[] - Always empty, a leftover from the internal framework we use on our web API. Will be removed in the future if possible so do not rely on this

    page::int - Which page was fetched.'
servers:
- url: https://open-api.shepherd.vet
tags:
- name: SoapImaging
paths:
  /pav2/open-api-soap-imaging/file-presigned-upload-url:
    post:
      tags:
      - SoapImaging
      summary: Generates a presigned upload Url for a Soap image file.
      description: 'Example Request

        {

        "filename": "dog.png",

        "patientId": "cd9e67e7-dc5e-4e21-8855-b8123456abcd"

        }


        Example Response

        {

        "contentType": "image/png",

        "fileName": "dog",

        "path": "/PAV2Module/A1b2C3d4Ef5Gh6Ij7Klm8n/OzLIJh67BcXW0098JhZqTg/Assessment/K9uYTcvbX12mkzAsDFqP0t.png",

        "url": "example.bucket/MediaVault/PAV2/PAV2Module/A1b2C3d4Ef5Gh6Ij7Klm8n/OzLIJh67BcXW0098JhZqTg/Assessment/"

        }'
      operationId: OpenApiSoapImagingFileGet
      parameters:
      - name: x-integration-public-key
        in: header
        description: Your public API key
        required: true
        schema:
          type: string
      - name: x-integration-private-key
        in: header
        description: Your private API key
        required: true
        schema:
          type: string
      - name: x-clinic-id
        in: header
        description: The clinic uuid identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The presigned upload URL and the path to send to file-entry-write.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapImagingController.PresignedUrlResponseModel'
            text/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapImagingController.PresignedUrlResponseModel'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapImagingController.PresignedUrlResponseModel'
        '401':
          description: 'Authorization failed. One of: Missing X-Integration-Public-Key header, Missing X-Integration-Private-Key header, Missing X-Clinic-Id header, Incorrect API keys provided, or Integration not enabled for the provided clinic.'
        '429':
          description: Request rate limit exceeded. Please wait before making further requests. Returned once the integration passes its configured hourly or per-minute request allowance.
        '400':
          description: "A validation rule failed. The response body is one of:\n             \"Request model is missing.\" - the request body is missing.\n             \"The request is invalid.\" with modelState - fileName or patientId is missing. modelState names the offending field.\n             \"Patient Id is not valid\" - patientId is not a GUID, or is the empty GUID.\n             \"The provided PatientId does not belong to the clinic.\" - patientId does not refer to a patient in the caller's clinic."
        '404':
          description: '"No active soap found" - the patient has no SOAP in Active, Boarding, Lab pending or In Review status in the caller''s clinic.'
        '409':
          description: '"Patient is deleted" - the patient has been deleted.'
        '500':
          description: The response body is the server's error message - the upload URL could not be generated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapImagingController.FileUploadPresignedUrlRequestModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapImagingController.FileUploadPresignedUrlRequestModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapImagingController.FileUploadPresignedUrlRequestModel'
        required: true
  /pav2/open-api-soap-imaging/file-entry-write:
    post:
      tags:
      - SoapImaging
      summary: After a file has been successfuly uploaded to S3 bucket with the generated…
      description: 'Example Request

        {

        "filename": "dog",

        "height": 400,

        "path": "/PAV2Module/XzT9PoF3RqXkLfJuBv7cMa/7glhV98RtZKYe3uNfXpWdr/Assessment/UyTrEwqL92kjHtZcPgVb55.png",

        "patientId": "cd9e67e7-dc5e-4e21-8855-b8123456abcd",

        "width": 600

        }'
      operationId: OpenApisoapimagingwrite
      parameters:
      - name: x-integration-public-key
        in: header
        description: Your public API key
        required: true
        schema:
          type: string
      - name: x-integration-private-key
        in: header
        description: Your private API key
        required: true
        schema:
          type: string
      - name: x-clinic-id
        in: header
        description: The clinic uuid identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The created SOAP imaging file entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapImagingController.SoapImageEntryModel'
            text/json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapImagingController.SoapImageEntryModel'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OpenApiSoapImagingController.SoapImageEntryModel'
        '401':
          description: 'Authorization failed. One of: Missing X-Integration-Public-Key header, Missing X-Integration-Private-Key header, Missing X-Clinic-Id header, Incorrect API keys provided, or Integration not enabled for the provided clinic.'
        '429':
          description: Request rate limit exceeded. Please wait before making further requests. Returned once the integration passes its configured hourly or per-minute request allowance.
        '400':
          description: "A validation rule failed. The response body is one of:\n             \"Request model is missing.\" - the request body is missing.\n             \"The request is invalid.\" with modelState - fileName, path or patientId is missing. modelState names the offending field.\n             \"Patient Id is not valid\" - patientId is not a GUID.\n             \"PatientId is required and cannot be empty.\" - patientId is the empty GUID.\n             \"The provided PatientId does not belong to the clinic.\" - patientId does not refer to a patient in the caller's clinic.\n             \"Uploaded file exceedes the upload file size limit: {limit}. Uploaded file has been deleted from the S3 bucket.\" - the uploaded file is larger than the configured limit, in bytes."
        '404':
          description: '"No active soap found" - the patient has no SOAP in Active, Boarding, Lab pending or In Review status in the caller''s clinic.'
        '409':
          description: '"Patient is deleted" - the patient has been deleted.'
        '500':
          description: "The file could not be linked. The response body is the server's error message. One of:\n             \"Specified argument was out of the range of valid values.\\r\\nParameter name: Extension not allowed: {extension}\" - the extension of path is missing or is not an allowed document, image or video extension.\n             (the S3 error message) - no file was uploaded to the presigned URL for path.\n             (the database error message) - path is already linked to a file, or fileName is longer than 500 characters."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapImagingController.SoapImageEntryModel'
          text/json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapImagingController.SoapImageEntryModel'
          application/hal+json:
            schema:
              $ref: '#/components/schemas/OpenApiSoapImagingController.SoapImageEntryModel'
        required: true
components:
  schemas:
    OpenApiSoapImagingController.PresignedUrlResponseModel:
      description: 'The response model which will return the upload URL for a file upload to S3 bucket along with the Path and

        FileName which are needed for creating an entry in our database making the uploaded file accessible via application.'
      type: object
      properties:
        contentType:
          description: The type of the content that will be uploaded to S3 bucket.
          type: string
        fileName:
          description: The name of the file that will be uploaded.
          type: string
        path:
          description: The key used to link the uploaded file with the database record.
          type: string
        url:
          description: The Presigned upload URL used for direct file upload to the S3 bucket.
          type: string
    OpenApiSoapImagingController.SoapImageEntryModel:
      description: Soap file entry write model.
      required:
      - fileName
      - path
      - patientId
      type: object
      properties:
        fileName:
          description: The name of the uploaded file without the file type extension (e.g., "examplefile").
          type: string
        height:
          format: int32
          description: The height of the uploaded image in pixels. Required for image uploads. Defaults to 0 if not provided.
          type: integer
        path:
          description: The key generated in the presigned URL response. Required for making the file accessible via the application.
          type: string
        patientId:
          description: Unique identifier of the patient for whom the file is uploaded.
          type: string
        width:
          format: int32
          description: The width of the uploaded image in pixels. Required for image uploads. Defaults to 0 if not provided.
          type: integer
    OpenApiSoapImagingController.FileUploadPresignedUrlRequestModel:
      description: 'A model containing properties required for the Presigned upload URL generation. Both properties are required in

        order to generate the URl.'
      required:
      - fileName
      - patientId
      type: object
      properties:
        fileName:
          description: The name of the file to be uploaded once the presigned URL is generated. Must include the file type extension (e.g., "examplefile.jpg").
          type: string
        patientId:
          description: The unique identifier of the Patient under which a file will be uploaded once the presigned URL is generated.
          type: string