Spaces:
Running
Running
| openapi: 3.1.0 | |
| info: | |
| title: SEL Chat Coach API | |
| description: | | |
| Social-Emotional Learning Chat Coach API for teachers to practice conversations | |
| with simulated ADHD student agents and consult coaching agents. | |
| All endpoints require Basic Auth unless otherwise specified. | |
| version: 1.0.0 | |
| contact: | |
| name: API Support | |
| servers: | |
| - url: http://localhost:3000 | |
| description: Local development server | |
| - url: https://sel-chat-coach.example.com | |
| description: Production server (update with actual URL) | |
| security: | |
| - basicAuth: [] | |
| tags: | |
| - name: Health | |
| description: Service health check | |
| - name: Auth | |
| description: User authentication and registration | |
| - name: Conversations | |
| description: Conversation management | |
| - name: Messages | |
| description: Conversation messages | |
| - name: System Messages | |
| description: System-level contextual messages | |
| - name: Coach | |
| description: Coach interactions | |
| - name: Stats | |
| description: Statistics and analytics | |
| paths: | |
| /api/health: | |
| get: | |
| tags: [Health] | |
| summary: Health check | |
| description: Check if the API is running | |
| security: [] | |
| responses: | |
| '200': | |
| description: Service is healthy | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| status: | |
| type: string | |
| example: healthy | |
| timestamp: | |
| type: string | |
| format: date-time | |
| /api/auth/register: | |
| post: | |
| tags: [Auth] | |
| summary: Register a new user | |
| description: Create a new user account with username. Use BASIC_AUTH_PASSWORD to authenticate subsequent requests. | |
| security: [] | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| required: [username, email, name] | |
| properties: | |
| username: | |
| type: string | |
| example: teacher_wang | |
| email: | |
| type: string | |
| format: email | |
| example: wang@example.com | |
| name: | |
| type: string | |
| example: 王老師 | |
| responses: | |
| '200': | |
| description: User created successfully | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| user: | |
| type: object | |
| properties: | |
| id: | |
| type: string | |
| format: uuid | |
| username: | |
| type: string | |
| message: | |
| type: string | |
| example: "User registered successfully. Use password 'cz-2025' to login." | |
| '400': | |
| $ref: '#/components/responses/BadRequest' | |
| /api/conversations: | |
| get: | |
| tags: [Conversations] | |
| summary: List all conversations | |
| description: Get all conversations for the authenticated user | |
| responses: | |
| '200': | |
| description: List of conversations | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| conversations: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/Conversation' | |
| '401': | |
| $ref: '#/components/responses/Unauthorized' | |
| /api/conversations/create: | |
| post: | |
| tags: [Conversations] | |
| summary: Create a new conversation | |
| description: Create a new conversation with a student personality and coach pairing | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| required: [studentPromptId, coachPromptId] | |
| properties: | |
| studentPromptId: | |
| type: string | |
| enum: [grade_1, grade_2, grade_3, grade_4, grade_5, grade_6, grade_7, grade_8, grade_9, coach_direct] | |
| description: Student grade level or 'coach_direct' for direct coach chat | |
| example: grade_3 | |
| coachPromptId: | |
| type: string | |
| enum: [empathetic, structured, balanced] | |
| example: empathetic | |
| title: | |
| type: string | |
| example: 數學課專注力問題 | |
| include3ConversationSummary: | |
| type: boolean | |
| description: Include summary of last 3 conversations with this student | |
| responses: | |
| '200': | |
| description: Conversation created | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| conversation: | |
| $ref: '#/components/schemas/Conversation' | |
| message: | |
| type: string | |
| '400': | |
| $ref: '#/components/responses/BadRequest' | |
| '401': | |
| $ref: '#/components/responses/Unauthorized' | |
| /api/conversations/{conversationId}: | |
| get: | |
| tags: [Conversations] | |
| summary: Get conversation details | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| responses: | |
| '200': | |
| description: Conversation details | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/Conversation' | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| put: | |
| tags: [Conversations] | |
| summary: Update conversation | |
| description: Update conversation title | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| title: | |
| type: string | |
| example: 更新的對話標題 | |
| responses: | |
| '200': | |
| description: Conversation updated | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/Conversation' | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| delete: | |
| tags: [Conversations] | |
| summary: Delete conversation | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| responses: | |
| '200': | |
| description: Conversation deleted | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| message: | |
| type: string | |
| deletedCount: | |
| type: number | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| /api/conversations/{conversationId}/messages: | |
| get: | |
| tags: [Messages] | |
| summary: Get conversation messages | |
| description: Retrieve all messages for a conversation | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| responses: | |
| '200': | |
| description: List of messages | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| messages: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/Message' | |
| total: | |
| type: number | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| /api/conversations/{conversationId}/message: | |
| post: | |
| tags: [Messages] | |
| summary: Send a message | |
| description: | | |
| Send a message in the conversation. Returns a streaming response. | |
| Uses Vercel AI SDK message format. | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| required: [messages] | |
| properties: | |
| messages: | |
| type: array | |
| description: Array of messages in AI SDK format | |
| items: | |
| type: object | |
| properties: | |
| id: | |
| type: string | |
| role: | |
| type: string | |
| enum: [user, assistant, system] | |
| content: | |
| type: string | |
| parts: | |
| type: array | |
| items: | |
| type: object | |
| properties: | |
| type: | |
| type: string | |
| example: text | |
| text: | |
| type: string | |
| metadata: | |
| type: object | |
| properties: | |
| speaker: | |
| type: string | |
| enum: [student, coach] | |
| description: Who is being addressed (student) or who is responding (coach) | |
| quotedText: | |
| type: string | |
| quotedMessageId: | |
| type: string | |
| example: | |
| messages: | |
| - id: msg-1 | |
| role: user | |
| content: 你好，我有數學問題 | |
| parts: | |
| - type: text | |
| text: 你好，我有數學問題 | |
| metadata: | |
| speaker: student | |
| responses: | |
| '200': | |
| description: Streaming response with AI-generated message | |
| content: | |
| text/event-stream: | |
| schema: | |
| type: string | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| /api/conversations/{conversationId}/system-messages: | |
| post: | |
| tags: [System Messages] | |
| summary: Create system message | |
| description: | | |
| Add a system message to the conversation for context. | |
| Use cases: student background info, medication status, session notes, milestones. | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| required: [content] | |
| properties: | |
| content: | |
| type: string | |
| example: 學生剛吃了ADHD藥物（30分鐘前） | |
| responses: | |
| '200': | |
| description: System message created | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| message: | |
| $ref: '#/components/schemas/Message' | |
| success: | |
| type: boolean | |
| '400': | |
| $ref: '#/components/responses/BadRequest' | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| /api/conversations/{conversationId}/system-messages/{messageId}: | |
| put: | |
| tags: [System Messages] | |
| summary: Update system message | |
| description: Update the content of an existing system message | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| - $ref: '#/components/parameters/MessageId' | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| required: [content] | |
| properties: | |
| content: | |
| type: string | |
| example: 學生剛吃了ADHD藥物（1小時前） | |
| responses: | |
| '200': | |
| description: System message updated | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| message: | |
| $ref: '#/components/schemas/Message' | |
| success: | |
| type: boolean | |
| '400': | |
| description: Bad request (e.g., trying to update non-system message) | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| delete: | |
| tags: [System Messages] | |
| summary: Delete system message | |
| parameters: | |
| - $ref: '#/components/parameters/ConversationId' | |
| - $ref: '#/components/parameters/MessageId' | |
| responses: | |
| '200': | |
| description: System message deleted | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| success: | |
| type: boolean | |
| message: | |
| type: string | |
| '400': | |
| description: Bad request (e.g., trying to delete non-system message) | |
| '404': | |
| $ref: '#/components/responses/NotFound' | |
| /api/coach/types: | |
| get: | |
| tags: [Coach] | |
| summary: List available coaches | |
| description: Get list of available coach personalities | |
| responses: | |
| '200': | |
| description: List of coaches | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| coaches: | |
| type: array | |
| items: | |
| type: object | |
| properties: | |
| id: | |
| type: string | |
| example: empathetic | |
| name: | |
| type: string | |
| example: 王老師 | |
| description: | |
| type: string | |
| /api/stats: | |
| get: | |
| tags: [Stats] | |
| summary: Get user statistics | |
| description: Get conversation and message statistics for the authenticated user | |
| responses: | |
| '200': | |
| description: User statistics | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| totalConversations: | |
| type: number | |
| totalMessages: | |
| type: number | |
| conversationsByStudent: | |
| type: object | |
| components: | |
| securitySchemes: | |
| basicAuth: | |
| type: http | |
| scheme: basic | |
| description: Use username and the password from BASIC_AUTH_PASSWORD env var (default 'cz-2025') | |
| parameters: | |
| ConversationId: | |
| name: conversationId | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| format: uuid | |
| description: Conversation ID | |
| MessageId: | |
| name: messageId | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| format: uuid | |
| description: Message ID | |
| schemas: | |
| Conversation: | |
| type: object | |
| properties: | |
| id: | |
| type: string | |
| format: uuid | |
| userId: | |
| type: string | |
| format: uuid | |
| studentPromptId: | |
| type: string | |
| example: grade_3 | |
| studentName: | |
| type: string | |
| example: 小三學生 | |
| description: "Derived from student prompt template (not stored in database). Generated from student-prompts.ts based on studentPromptId." | |
| coachPromptId: | |
| type: string | |
| enum: [empathetic, structured, balanced] | |
| coachName: | |
| type: string | |
| example: 王老師 | |
| description: "Derived from coach prompt template (not stored in database). Generated from coach-prompts.ts based on coachPromptId." | |
| title: | |
| type: string | |
| titleSource: | |
| type: string | |
| enum: [auto, auto-locked, user] | |
| summary: | |
| type: string | |
| systemPrompt: | |
| type: string | |
| sourceConversationId: | |
| type: string | |
| format: uuid | |
| description: "ID of conversation this was branched from (null if not a branch)" | |
| branchedFromMessageId: | |
| type: string | |
| format: uuid | |
| description: "ID of message where this branch was created (null if not a branch)" | |
| createdAt: | |
| type: string | |
| format: date-time | |
| updatedAt: | |
| type: string | |
| format: date-time | |
| lastActiveAt: | |
| type: string | |
| format: date-time | |
| Message: | |
| type: object | |
| properties: | |
| id: | |
| type: string | |
| format: uuid | |
| conversationId: | |
| type: string | |
| format: uuid | |
| role: | |
| type: string | |
| enum: [user, assistant, system] | |
| speaker: | |
| type: string | |
| enum: [student, coach] | |
| description: Who is speaking in this message | |
| content: | |
| type: string | |
| responseId: | |
| type: string | |
| description: OpenAI Responses API response ID | |
| timestamp: | |
| type: string | |
| format: date-time | |
| quotedText: | |
| type: string | |
| description: Selected text being replied to | |
| quotedMessageId: | |
| type: string | |
| description: ID of message being replied to | |
| responses: | |
| BadRequest: | |
| description: Bad request | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| error: | |
| type: string | |
| example: Invalid input | |
| Unauthorized: | |
| description: Unauthorized | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| error: | |
| type: string | |
| example: Unauthorized | |
| NotFound: | |
| description: Resource not found | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| error: | |
| type: string | |
| example: Conversation not found | |