openapi: 3.0.3
info:
  title: Spruce Public Contacts Conversations 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: Conversations
  description: Conversations (message threads) in a Spruce organization.
paths:
  /conversations:
    get:
      operationId: listConversations
      tags:
      - Conversations
      summary: List conversations
      description: Lists conversations in the organization. Confirmed path and parameters.
      parameters:
      - name: pageSize
        in: query
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 200
        description: How many conversations to return at one time (max 200).
      - name: paginationToken
        in: query
        schema:
          type: string
        description: Token to fetch subsequent pages; cannot be combined with startFrom.
      - name: orderBy
        in: query
        required: true
        schema:
          type: string
          enum:
          - created
          - last_message
        description: Order results by creation time or last message.
      - name: startFrom
        in: query
        schema:
          type: string
          format: date-time
        description: Only return conversations whose ordering field value is at or after this RFC 3339 timestamp.
      responses:
        '200':
          description: A list of conversations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createConversation
      tags:
      - Conversations
      summary: Create a conversation
      description: Creates a new conversation. Modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Conversation'
      responses:
        '200':
          description: The created conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
  /conversations/{conversationId}:
    parameters:
    - name: conversationId
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: conversation
      tags:
      - Conversations
      summary: Get a conversation
      description: Retrieves a single conversation by ID. Modeled.
      responses:
        '200':
          description: The requested conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
    patch:
      operationId: updateConversation
      tags:
      - Conversations
      summary: Update a conversation
      description: Updates an existing conversation. Modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Conversation'
      responses:
        '200':
          description: The updated conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
  /conversations/tags:
    get:
      operationId: conversationTags
      tags:
      - Conversations
      summary: List conversation tags
      description: Lists the tags that can be applied to conversations. Modeled.
      responses:
        '200':
          description: Conversation tags.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
    post:
      operationId: createConversationTag
      tags:
      - Conversations
      summary: Create a conversation tag
      description: Creates a new conversation tag. Modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tag'
      responses:
        '200':
          description: The created conversation tag.
components:
  responses:
    Forbidden:
      description: Missing, incorrect, or disabled API token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    Conversation:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        createdAt:
          type: string
          format: date-time
        lastMessageAt:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string
    Tag:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization API token generated in Settings after Spruce Support enables API access.