{"openapi":"3.1.0","info":{"title":"POST /api/v1/client-messages/conversations","version":"1.0.0","description":"Create a conversation"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/client-messages/conversations":{"post":{"tags":["client-messages"],"summary":"Create a conversation","description":"Start a new conversation with the advisory firm.","operationId":"create_conversation","parameters":[{"name":"x-business-id","in":"header","required":true,"schema":{"type":"string","title":"X-Business-Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConversationRequest"},"example":{"category":"tax_question","message":"Hi, I wanted to check on the status of our Q4 estimated tax payment.","subject":"Question about Q4 tax filing"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_ConversationDetailResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_conversation_api_v1_client_messages_conversations_post"}}},"components":{"schemas":{"ConversationCategory":{"type":"string","enum":["general","document_request","tax_question","payment_question","other"],"title":"ConversationCategory"},"ConversationDetailResponse":{"properties":{"id":{"type":"string","title":"Id"},"business_id":{"type":"string","title":"Business Id"},"advisory_firm_id":{"type":"string","title":"Advisory Firm Id"},"subject":{"type":"string","title":"Subject"},"category":{"$ref":"#/components/schemas/ConversationCategory"},"status":{"$ref":"#/components/schemas/ConversationStatus"},"created_by_user_id":{"type":"string","title":"Created By User Id"},"created_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Name"},"business_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Name"},"messages":{"items":{"$ref":"#/components/schemas/app__api__v1__schemas__client_messages__MessageResponse"},"type":"array","title":"Messages"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","business_id","advisory_firm_id","subject","category","status","created_by_user_id","created_at","updated_at"],"title":"ConversationDetailResponse","description":"Full conversation with messages."},"ConversationStatus":{"type":"string","enum":["open","waiting_on_client","resolved"],"title":"ConversationStatus"},"CreateConversationRequest":{"properties":{"subject":{"type":"string","maxLength":500,"minLength":1,"title":"Subject","description":"Conversation subject"},"category":{"$ref":"#/components/schemas/ConversationCategory","description":"Conversation category","default":"general"},"message":{"type":"string","maxLength":10000,"minLength":1,"title":"Message","description":"Initial message body"}},"type":"object","required":["subject","message"],"title":"CreateConversationRequest","description":"Create a new conversation (client-initiated).","example":{"category":"tax_question","message":"Hi, I wanted to check on the status of our Q4 estimated tax payment.","subject":"Question about Q4 tax filing"},"examples":[{"category":"tax_question","message":"Hi, I wanted to check on the status of our Q4 estimated tax payment.","subject":"Question about Q4 tax filing"}]},"SenderRole":{"type":"string","enum":["client","advisor"],"title":"SenderRole"},"SuccessEnvelope_ConversationDetailResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/ConversationDetailResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[ConversationDetailResponse]"},"app__api__v1__schemas__client_messages__MessageResponse":{"properties":{"id":{"type":"string","title":"Id"},"conversation_id":{"type":"string","title":"Conversation Id"},"sender_user_id":{"type":"string","title":"Sender User Id"},"sender_role":{"$ref":"#/components/schemas/SenderRole"},"sender_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Name"},"body":{"type":"string","title":"Body"},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","conversation_id","sender_user_id","sender_role","body","created_at"],"title":"MessageResponse","description":"A single message within a conversation."},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}