Support SPI endpoint reference

This page documents every endpoint in the Support SPI (full spec required) using the OpenAPI definition in openapi/spi-care.yaml.

Note: reads are scoped with customerId query param. Product context is inferred from the configured Base URL.

GET /care/conversations

List conversations for a given customer.

Required query params: customerId
Returns: { conversations: CareConversationSummary[] }

json

200 OK
{
  "conversations": [
    {
      "id": "c_123",
      "subject": "Can't log in",
      "status": "waiting-for-agent",
      "isOpen": true,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "updatedAt": "2025-01-01T12:10:00.000Z"
    }
  ]
}

POST /care/conversations

Create a new conversation.

Required JSON body: customerId, subject, body
Returns: conversationId and createdAt

Request
{
  "customerId": "cust_001",
  "subject": "Billing question",
  "body": "Can I get an invoice?"
}

Response
200 OK
{
  "conversationId": "c_456",
  "createdAt": "2025-01-01T12:00:00.000Z"
}

GET /care/conversations/{conversationId}

Fetch a conversation with all messages.

Required path param: conversationId
Required query params: customerId
Returns: CareConversationDetail (includes messages array)

json

200 OK
{
  "id": "c_456",
  "subject": "Billing question",
  "status": "waiting-for-agent",
  "isOpen": true,
  "createdAt": "2025-01-01T12:00:00.000Z",
  "updatedAt": "2025-01-01T12:10:00.000Z",
  "messages": [
    {
      "id": "m_1",
      "body": "Can I get an invoice?",
      "author": "Customer",
      "createdAt": "2025-01-01T12:00:00.000Z",
      "isCustomer": true
    }
  ]
}

POST /care/conversations/{conversationId}/messages

Add a message to an existing conversation.

Required path param: conversationId
Required JSON body: customerId, conversationId, body
Returns: messageId and createdAt

Request
{
  "customerId": "cust_001",
  "conversationId": "c_456",
  "body": "Here is more information..."
}

Response
200 OK
{
  "messageId": "m_2",
  "createdAt": "2025-01-01T12:12:00.000Z"
}

POST /care/conversations/{conversationId}/close

Close (or resolve) an existing conversation.

Required path param: conversationId
Required JSON body: customerId, conversationId, action
Action must be resolve or close
Returns: 204 No Content

Request
{
  "customerId": "cust_001",
  "conversationId": "c_456",
  "action": "resolve"
}

Response
204 No Content

Important implementation notes

All IDs must be stable; don't recycle IDs.
Enforce customerId scoping on every call.
Use consistent timestamps and update updatedAt when messages/status change.
Support nullable message body per schema (but prefer strings).

SPI Endpoints