{"owner":"langbot-app","repo":"LangBot","hasSpec":true,"specFile":"docs/http-bot-openapi.json","branch":"HEAD","format":"json","version":"3.0.3","title":"LangBot HTTP Bot Adapter","description":"Server-to-server HTTP integration for a LangBot pipeline. Inbound messages are POSTed to the unified webhook route; replies are delivered to a configured callback URL (one POST per reply part). All requests are HMAC-SHA256 signed. See docs/platforms/http-bot.md.","pathsCount":3,"endpoints":[{"method":"POST","path":"/bots/{bot_uuid}","summary":"Push a message into the pipeline (fire-and-collect)"},{"method":"POST","path":"/bots/{bot_uuid}/sync","summary":"Push a message and wait for the collapsed reply"},{"method":"POST","path":"/bots/{bot_uuid}/reset","summary":"Reset a session's conversation"}],"spec":{"openapi":"3.0.3","info":{"title":"LangBot HTTP Bot Adapter","version":"1.0.0","description":"Server-to-server HTTP integration for a LangBot pipeline. Inbound messages are POSTed to the unified webhook route; replies are delivered to a configured callback URL (one POST per reply part). All requests are HMAC-SHA256 signed. See docs/platforms/http-bot.md."},"paths":{"/bots/{bot_uuid}":{"post":{"summary":"Push a message into the pipeline (fire-and-collect)","description":"Returns 202 immediately. Replies arrive asynchronously on the configured callback URL. Reuse the same session_id within the aggregation window to merge multiple messages into one turn (N->1).","parameters":[{"$ref":"#/components/parameters/BotUuid"},{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/Signature"},{"$ref":"#/components/parameters/Idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundMessage"}}}},"responses":{"202":{"description":"Accepted (queued for the pipeline)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"}}}},"/bots/{bot_uuid}/sync":{"post":{"summary":"Push a message and wait for the collapsed reply","description":"Blocking convenience mode. Waits for is_final and returns all reply parts collapsed into one array. Lossy (no sequence/streaming). One in-flight sync per session_id.","parameters":[{"$ref":"#/components/parameters/BotUuid"},{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/Signature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundMessage"}}}},"responses":{"200":{"description":"The collapsed reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/bots/{bot_uuid}/reset":{"post":{"summary":"Reset a session's conversation","parameters":[{"$ref":"#/components/parameters/BotUuid"},{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/Signature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id"],"properties":{"session_id":{"type":"string"},"session_type":{"type":"string","enum":["person","group"]}}}}}},"responses":{"200":{"description":"Reset done"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}}},"components":{"parameters":{"BotUuid":{"name":"bot_uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Timestamp":{"name":"X-LB-Timestamp","in":"header","required":true,"description":"Unix seconds; rejected if more than +/-300s from server time.","schema":{"type":"string"}},"Signature":{"name":"X-LB-Signature","in":"header","required":true,"description":"sha256=<hex> of HMAC-SHA256(secret, \"{timestamp}.\" + raw_body).","schema":{"type":"string"}},"Idempotency":{"name":"X-LB-Idempotency-Key","in":"header","required":false,"description":"Dedup key; a repeat within the dedup window returns 409.","schema":{"type":"string"}}},"schemas":{"Segment":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Plain","Image","Voice","File","At","Quote"]},"text":{"type":"string","description":"For type=Plain."},"url":{"type":"string","description":"For media types."},"base64":{"type":"string","description":"For media types (data URI or raw base64)."}}},"InboundMessage":{"type":"object","required":["session_id","message"],"properties":{"session_id":{"type":"string","description":"Caller-defined; maps 1:1 to a LangBot session."},"session_type":{"type":"string","enum":["person","group"],"default":"person"},"sender":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"group_name":{"type":"string","description":"For session_type=group."}}},"message":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}}},"AcceptedResponse":{"type":"object","properties":{"code":{"type":"integer","example":0},"msg":{"type":"string","example":"accepted"},"data":{"type":"object","properties":{"session_id":{"type":"string"},"accepted_message_id":{"type":"string","example":"in_01H..."},"aggregating":{"type":"boolean"}}}}},"SyncResponse":{"type":"object","properties":{"code":{"type":"integer","example":0},"msg":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"session_id":{"type":"string"},"reply_to":{"type":"string"},"message":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}}}}},"Callback":{"type":"object","description":"Delivered by LangBot to your callback_url, one POST per reply part. Signed with the outbound secret.","properties":{"session_id":{"type":"string"},"reply_to":{"type":"string","description":"The accepted_message_id this answers."},"sequence":{"type":"integer","description":"1-based ordinal within the turn."},"is_final":{"type":"boolean","description":"True on the last part of the turn."},"stream":{"type":"boolean"},"message":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"timestamp":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","properties":{"code":{"type":"integer","example":40101},"msg":{"type":"string","example":"invalid signature: signature_mismatch"},"data":{"nullable":true}}}},"responses":{"Error":{"description":"Error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}