openapi: 3.2.0 info: title: Happyrobot Public Chat API description: Public API endpoints for Happyrobot version: 0.1.1 servers: - url: https://platform.happyrobot.ai/api/v2 security: - bearerAuth: [] tags: - name: Chat paths: /chat/tokens/: post: summary: Create a chat client token tags: - Chat description: Generates a scoped JWT for browser-side chat operations. Call this from your backend with your API key, then pass the token to the frontend. requestBody: content: application/json: schema: type: object properties: workflow_id: type: string minLength: 1 description: Workflow UUID or slug to scope the token to data: description: Payload data to pass to the chat agent as trigger variables type: object additionalProperties: {} env: default: production description: Environment to use for session initialization type: string enum: - production - staging - development ttl_seconds: default: 3600 description: Token lifetime in seconds. Defaults to 3600 (1 hour). Min 60s, max 24h. type: integer minimum: 60 maximum: 86400 required: - workflow_id required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: token: type: string expires_at: type: string description: ISO 8601 timestamp required: - token - expires_at additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false /chat/sessions/: post: summary: Create a chat session tags: - Chat description: Creates a new chat session for the workflow scoped in the client token. security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: session_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string required: - session_id - status additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false /chat/sessions/{id}/messages: post: summary: Send a chat message tags: - Chat description: Sends a user message to the chat session. The AI response will arrive via WebSocket. requestBody: content: application/json: schema: type: object properties: content: type: string description: Message text content artifacts: description: Attached file references type: array items: type: object properties: type: default: raw type: string media_id: type: string s3_key: type: string mime_type: type: string presigned_url: type: string filename: type: string size_bytes: type: number artifact_text: type: string required: - media_id - mime_type required: - content required: true parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: id required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: message: type: object properties: id: type: string session_id: type: string content: type: string role: type: string created_at: type: string required: - id - session_id - content - role - created_at additionalProperties: false required: - message additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false /chat/sessions/{id}/close: post: summary: Close a chat session tags: - Chat description: Ends the chat session, stopping the AI agent. The session cannot be resumed after this call. parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: id required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: status: type: string session_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - status - session_id additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false /chat/sessions/{id}/history: get: summary: Get chat session history tags: - Chat description: Retrieves message history for a chat session. Useful for page reloads or reconnects. parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: id required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: session_id: type: string status: type: string started_at: type: string last_activity: type: string messages: type: array items: type: object properties: id: type: string role: type: string content: type: string timestamp: type: string metadata: type: object additionalProperties: {} artifacts: type: array items: type: object properties: media_id: type: string filename: type: string mime_type: type: string file_size: type: number presigned_url: type: string required: - media_id - filename - mime_type additionalProperties: false required: - id - role - content - timestamp additionalProperties: false metadata: type: object additionalProperties: {} required: - session_id - status - started_at - last_activity - messages additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false /chat/upload/presigned: get: summary: Get presigned upload URL tags: - Chat description: Returns a presigned S3 URL for direct file upload from the browser. After uploading, call POST /chat/upload/complete to register the artifact. parameters: - schema: type: string in: query name: filename required: true - schema: type: string in: query name: mime_type required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: artifact_id: type: string upload_url: type: string s3_uri: type: string max_file_size: type: number required: - artifact_id - upload_url - s3_uri - max_file_size additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '503': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false /chat/upload/complete: post: summary: Complete file upload tags: - Chat description: Registers an uploaded artifact after direct S3 upload. Call this after uploading the file to the presigned URL. requestBody: content: application/json: schema: type: object properties: artifact_id: type: string s3_uri: type: string filename: type: string mime_type: type: string size_bytes: type: number exclusiveMinimum: 0 required: - artifact_id - s3_uri - filename - mime_type - size_bytes required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: artifact_id: type: string status: type: string required: - artifact_id - status additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '413': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false '503': description: Default Response content: application/json: schema: type: object properties: error: type: string statusCode: type: number required: - error additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Opaque