openapi: 3.0.3
info:
  title: Spruce Public Contacts Messages API
  description: 'The Spruce Public API connects a Spruce Health organization to internal tools, electronic health records (EHRs), practice management systems, and other external systems so practices can automate workflows, sync data, and receive real-time events. It is a RESTful API over HTTPS with a base URL of https://api.sprucehealth.com/v1 and Bearer token authentication (Authorization: Bearer <your-token>); tokens are generated by administrators from the "API Access" section of Settings after Spruce Support enables API access for the organization (API access is part of the Communicator plan).


    Grounding note: the base URL and Bearer auth are confirmed from the Spruce developer documentation, and the following paths are confirmed directly from the API reference: GET /contacts, GET /conversations, POST /conversations/{conversationId}/messages, GET /webhooks/endpoints, POST /webhooks/endpoints, and GET /internalendpoints. The remaining paths and all request/response schemas are honestly MODELED from the published operation catalog (developer.sprucehealth.com/llms.txt) and documented behavior; exact request/response bodies should be reconciled against the live reference and the machine-readable OpenAPI Spruce publishes.'
  version: '1.0'
  contact:
    name: Spruce Health
    url: https://developer.sprucehealth.com
  x-endpointsModeled: true
servers:
- url: https://api.sprucehealth.com/v1
  description: Spruce Public API
security:
- bearerAuth: []
tags:
- name: Messages
  description: Conversation items, messages, media, endpoints, and scheduled messages.
paths:
  /conversations/{conversationId}/messages:
    parameters:
    - name: conversationId
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: postConversationMessage
      tags:
      - Messages
      summary: Post a message to a conversation
      description: Posts a new message into a conversation. Confirmed path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreate'
      responses:
        '200':
          description: The created conversation item (message).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationItem'
        '403':
          $ref: '#/components/responses/Forbidden'
  /conversations/{conversationId}/items:
    parameters:
    - name: conversationId
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: conversationItems
      tags:
      - Messages
      summary: List conversation items
      description: Lists the items (messages, calls, faxes, events) in a conversation. Modeled.
      responses:
        '200':
          description: Conversation items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversationItem'
  /conversations/{conversationId}/items/{itemId}:
    parameters:
    - name: conversationId
      in: path
      required: true
      schema:
        type: string
    - name: itemId
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: conversationItem
      tags:
      - Messages
      summary: Get a conversation item
      description: Gets a conversation item for a given id. Modeled path (operation confirmed).
      responses:
        '200':
          description: The conversation item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationItem'
    delete:
      operationId: deleteConversationItem
      tags:
      - Messages
      summary: Delete a conversation item
      description: Deletes a conversation item. Modeled.
      responses:
        '204':
          description: Item deleted.
  /internalendpoints:
    get:
      operationId: internalEndpoints
      tags:
      - Messages
      summary: List internal endpoints
      description: Lists all internal endpoints (phone lines / addresses) an organization can communicate with. Confirmed path.
      responses:
        '200':
          description: Internal endpoints.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Endpoint'
  /internalendpoints/{endpointId}/messages:
    parameters:
    - name: endpointId
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: postMessageFromEndpoint
      tags:
      - Messages
      summary: Send a message from an internal endpoint
      description: Sends a message (e.g. SMS/secure) from a given internal endpoint. Modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreate'
      responses:
        '200':
          description: The created conversation item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationItem'
  /proxy-calls:
    post:
      operationId: postCreateProxyCall
      tags:
      - Messages
      summary: Create a proxy call
      description: Creates a proxy (bridge) call between a member and a contact. Modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created proxy call.
  /media:
    post:
      operationId: uploadMedia
      tags:
      - Messages
      summary: Upload media
      description: Uploads media for use as a message attachment. Modeled.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The uploaded media reference.
  /scheduled-messages:
    get:
      operationId: listScheduledMessages
      tags:
      - Messages
      summary: List scheduled messages
      description: Lists scheduled messages for the organization. Modeled.
      responses:
        '200':
          description: Scheduled messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
  /conversations/{conversationId}/scheduled-messages:
    parameters:
    - name: conversationId
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listConversationScheduledMessages
      tags:
      - Messages
      summary: List a conversation's scheduled messages
      description: Lists scheduled messages for a conversation. Modeled.
      responses:
        '200':
          description: Scheduled messages for the conversation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
    post:
      operationId: scheduleConversationMessage
      tags:
      - Messages
      summary: Schedule a message in a conversation
      description: Schedules a message to be sent in a conversation at a future time. Modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreate'
      responses:
        '200':
          description: The scheduled message.
  /scheduled-messages/{scheduledMessageId}:
    parameters:
    - name: scheduledMessageId
      in: path
      required: true
      schema:
        type: string
    delete:
      operationId: deleteScheduledMessage
      tags:
      - Messages
      summary: Delete a scheduled message
      description: Deletes a scheduled message before it is sent. Modeled.
      responses:
        '204':
          description: Scheduled message deleted.
  /saved-messages:
    get:
      operationId: listSavedMessages
      tags:
      - Messages
      summary: List saved messages
      description: Lists saved (canned/template) messages for the organization. Modeled.
      responses:
        '200':
          description: Saved messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
components:
  responses:
    Forbidden:
      description: Missing, incorrect, or disabled API token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    MessageCreate:
      type: object
      properties:
        body:
          type: string
        mediaIds:
          type: array
          items:
            type: string
    ConversationItem:
      type: object
      properties:
        id:
          type: string
        conversationId:
          type: string
        type:
          type: string
          description: Item type, e.g. message, call, fax, or secure conversation event.
        body:
          type: string
        createdAt:
          type: string
          format: date-time
    Endpoint:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        type:
          type: string
        value:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization API token generated in Settings after Spruce Support enables API access.