Complete API documentation for the Self-Service Agent system based on the actual codebase implementation.
- Base URLs
- Authentication
- Request Manager Endpoints
- Integration Dispatcher Endpoints
- Request/Response Schemas
- Error Responses
- Health Checks
- Local Development:
http://localhost:8080(with port-forward) - Production:
https://your-request-manager-url
- Local Development:
http://localhost:8081(with port-forward) - Production:
https://your-integration-dispatcher-url
Authorization: Bearer <jwt-token>Authorization: Bearer <api-key>x-api-key: <tool-api-key>x-slack-signature: <signature>
x-slack-request-timestamp: <timestamp>x-user-id: <user-id>
x-user-email: <email>
x-user-groups: <comma-separated-groups>Handle web-based requests with authentication.
Authentication: Required (JWT or API Key)
Request Body:
{
"user_id": "string",
"content": "string",
"client_ip": "string" (optional)
}Response:
{
"request_id": "string",
"session_id": "string",
"status": "completed",
"response": {
"content": "string",
"agent_id": "string",
"metadata": {},
"processing_time_ms": 0,
"requires_followup": false,
"followup_actions": []
}
}Example:
curl -X POST https://your-request-manager/api/v1/requests/web \
-H "Authorization: Bearer web-test-user" \
-H "Content-Type: application/json" \
-d '{
"user_id": "web-test-user",
"content": "I need help with my laptop",
"client_ip": "192.168.1.100"
}'Handle CLI tool requests with authentication.
Authentication: Required (JWT or API Key)
Request Body:
{
"user_id": "string",
"content": "string",
"metadata": {
"terminal": "string" (optional),
"command": "string" (optional)
}
}Response:
{
"request_id": "string",
"session_id": "string",
"status": "completed",
"response": {
"content": "string",
"agent_id": "string",
"metadata": {},
"processing_time_ms": 0,
"requires_followup": false,
"followup_actions": []
}
}Example:
curl -X POST https://your-request-manager/api/v1/requests/cli \
-H "Authorization: Bearer cli-user" \
-H "Content-Type: application/json" \
-d '{
"user_id": "cli-user",
"content": "Check my system status",
"metadata": {
"terminal": "bash",
"command": "systemctl status"
}
}'Handle system-to-system tool requests.
Authentication: Required (Tool API Key)
Request Body:
{
"user_id": "string",
"content": "string",
"tool_id": "string",
"tool_instance_id": "string" (optional),
"trigger_event": "string",
"tool_context": {
"key": "value"
} (optional),
"metadata": {
"correlation_id": "string" (optional),
"automation_rule": "string" (optional),
"triggered_by": "string" (optional)
} (optional)
}Response:
{
"request_id": "string",
"session_id": "string",
"status": "completed",
"response": {
"content": "string",
"agent_id": "string",
"metadata": {},
"processing_time_ms": 0,
"requires_followup": false,
"followup_actions": []
}
}Example:
curl -X POST https://your-request-manager/api/v1/requests/tool \
-H "x-api-key: snow-integration-key" \
-H "Content-Type: application/json" \
-d '{
"user_id": "alice.johnson",
"content": "Automated notification: Laptop refresh due",
"tool_id": "snow-integration",
"trigger_event": "asset.refresh.due",
"tool_context": {
"asset_tag": "LAPTOP-12345",
"target_agent_id": "laptop-refresh-agent"
}
}'Handle generic requests without authentication.
Authentication: None
Request Body:
{
"integration_type": "string",
"user_id": "string",
"content": "string"
}Response:
{
"request_id": "string",
"session_id": "string",
"status": "completed",
"response": {
"content": "string",
"agent_id": "string",
"metadata": {},
"processing_time_ms": 0,
"requires_followup": false,
"followup_actions": []
}
}Example:
curl -X POST https://your-request-manager/api/v1/requests/generic \
-H "Content-Type: application/json" \
-d '{
"integration_type": "web",
"user_id": "anonymous-user",
"content": "Test message"
}'All endpoints use LangGraph state machine for advanced conversation management with persistent thread management and context.
Supported Endpoints:
/api/v1/requests/web- Web interface/api/v1/requests/cli- CLI tool/api/v1/requests/tool- Tool integration/api/v1/requests/generic- Generic requests
Request Body:
{
"user_id": "string",
"content": "string",
"request_manager_session_id": "string" (optional),
"user_email": "string" (optional),
"session_name": "string" (optional),
"metadata": {} (optional)
}Response:
{
"request_id": "string",
"session_id": "string",
"status": "completed",
"response": {
"content": "string",
"agent_id": "string",
"metadata": {},
"processing_time_ms": 0,
"requires_followup": false,
"followup_actions": []
}
}Example (Web endpoint):
curl -X POST https://your-request-manager/api/v1/requests/web \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{
"user_id": "user123",
"content": "I need help with my laptop",
"user_email": "user@example.com",
"session_name": "Laptop Support Session"
}'Retrieve conversations for review, audit, and quality assurance purposes.
Authentication: None. No headers required (matches generic endpoint).
Query Parameters:
session_id(optional, string) - Get specific session's conversationstart_date(optional, string) - ISO 8601 datetime (e.g.,2026-01-01T00:00:00Z)end_date(optional, string) - ISO 8601 datetimeuser_id(optional, string) - UUID or email address to filter by useruser_email(optional, string) - Email address to filter by user (alternative to user_id)integration_type(optional, string) - Filter by channel where the conversation started (session record).integration_types(optional, list of strings) - Only include sessions that used at least one of these channels; returned conversations are full. E.g.?integration_types=CLI&integration_types=SLACK.agent_id(optional, string) - Only include sessions that used this agent at least once; returned conversations are full (routing + specialist + etc.). E.g.laptop-refresh.limit(optional, integer, default: 100, max: 1000) - Number of resultsoffset(optional, integer, default: 0) - Pagination offsetrandom(optional, boolean, default: false) - Random sampling instead of orderedinclude_messages(optional, boolean, default: true) - Include full conversation messages
Response:
{
"sessions": [
{
"integration_type": "CLI",
"integration_types": ["CLI"],
"session_id": "uuid",
"user_id": "uuid",
"user_email": "user@example.com",
"status": "ACTIVE",
"created_at": "2026-01-26T10:00:00Z",
"last_request_at": "2026-01-26T10:05:00Z",
"total_requests": 5,
"current_agent_id": "laptop-refresh",
"current_thread_id": "langgraph-thread-id",
"conversation": [
{
"request_id": "string",
"timestamp": "2026-01-26T10:00:00Z",
"integration_type": "CLI",
"user_message": "hi",
"agent_response": "Hello! I'm the routing agent...",
"agent_id": "routing-agent",
"thread_id": "langgraph-thread-id",
"thread_id_source": "metadata",
"processing_time_ms": 1234,
"completed_at": "2026-01-26T10:00:01Z"
}
]
}
],
"count": 10,
"total": 150,
"limit": 100,
"offset": 0
}integration_type: Per session, channel where the conversation started (session record).integration_types: Per session, sorted list of channels used in that session (from messages; wheninclude_messages=false, derived from the session record). Single-channel sessions have one element; multi-channel sessions have multiple (e.g.["CLI", "SLACK"]).- Each conversation item includes
integration_type(channel for that message).
Examples:
Get random sample of conversations:
curl -X GET "https://your-request-manager/api/v1/conversations?random=true&limit=10&start_date=2026-01-01T00:00:00Z&end_date=2026-01-26T23:59:59Z"Get conversations for specific user by email:
curl -X GET "https://your-request-manager/api/v1/conversations?user_email=user@example.com&start_date=2026-01-01T00:00:00Z"Get conversations for specific user by UUID:
curl -X GET "https://your-request-manager/api/v1/conversations?user_id=550e8400-e29b-41d4-a716-446655440000"Get specific session conversation:
curl -X GET "https://your-request-manager/api/v1/conversations?session_id=session-uuid&include_messages=true"Get conversations that started on CLI (without full messages for faster listing):
curl -X GET "https://your-request-manager/api/v1/conversations?integration_type=CLI&limit=50&include_messages=false"Get conversations that used at least one of several channels (full conversation):
curl -X GET "https://your-request-manager/api/v1/conversations?integration_types=CLI&integration_types=SLACK"Get conversations that used a given agent (full conversation, including routing):
curl -X GET "https://your-request-manager/api/v1/conversations?agent_id=laptop-refresh&start_date=2026-01-01T00:00:00Z"Error Responses:
400 Bad Request (invalid start_date or end_date format):
{
"detail": "Invalid start_date format. Use ISO 8601 (e.g., 2026-01-01T00:00:00Z)"
}(The same pattern is used for invalid end_date.)
400 Bad Request (invalid integration type):
{
"detail": "Invalid integration_type: INVALID. Valid values: CLI, WEB, SLACK, ..."
}400 Bad Request (invalid integration_types value):
{
"detail": "Invalid integration_types value: INVALID. Valid values: CLI, WEB, SLACK, ..."
}Notes:
- Each session has
integration_type(channel where the conversation started) andintegration_types(channels used in that session). Each conversation item hasintegration_type(channel for that message). - Thread IDs are extracted from
response_metadatawhen available, otherwise fall back to session'scurrent_thread_id - The
thread_id_sourcefield indicates whether the thread_id came frommetadataorsession - For performance, set
include_messages=falsewhen you only need session metadata (thenintegration_typesis derived from the session's single type). - Random sampling uses PostgreSQL's
random()function for efficient sampling
Handle incoming CloudEvents from Integration Dispatcher and Agent Service.
Authentication: None
Request Body: CloudEvent format
Supported Event Types:
com.self-service-agent.request.created- Request events from Integration Dispatcher (Slack/Email)com.self-service-agent.agent.response-ready- Agent response events from Agent Service
Response:
{
"status": "success",
"message": "CloudEvent processed"
}Note: This endpoint handles internal service-to-service communication via CloudEvents. External clients should use /api/v1/requests/* endpoints instead.
Health check endpoint for Request Manager.
Authentication: None
Response:
{
"status": "healthy",
"service": "request-manager",
"version": "0.1.0",
"timestamp": "2024-01-01T00:00:00Z"
}Handle Slack events (messages, mentions, etc.).
Authentication: Required (Slack Signature Verification)
Request Body: Slack event payload
Response:
{
"status": "ok"
}Handle Slack interactive components (buttons, modals, etc.).
Authentication: Required (Slack Signature Verification)
Request Body: Slack interactive payload
Response:
{
"text": "Response text"
}Handle Slack slash commands.
Authentication: Required (Slack Signature Verification)
Request Body: Slack slash command payload
Response:
{
"text": "Response text"
}Receives Zammad Trigger → Webhook POSTs so ticket creates and updates can flow into Request Manager. Deployment and Operator setup are described in README.md.
Authentication: Required — HMAC-SHA1 over the raw body in X-Hub-Signature, using ZAMMAD_WEBHOOK_SECRET. Verification is always enforced; an unset or empty secret still fails verification (401). The signature may be sent as a hex string or prefixed with sha1=.
Required headers:
| Header | Description |
|---|---|
X-Hub-Signature |
HMAC-SHA1 of the request body (hex, optional sha1= prefix). |
X-Zammad-Delivery |
Unique id for this delivery (deduplication). If missing → 400 with "Missing X-Zammad-Delivery header". |
Optional headers:
| Header | Description |
|---|---|
X-Zammad-Trigger |
Trigger identifier when present. |
Request body: JSON from Zammad (typically includes ticket and article). Malformed JSON → 400 with "Invalid JSON body".
Successful response:
{
"status": "ok"
}Errors: 401 with detail Invalid signature (bad/missing HMAC, or unset/empty webhook secret); 400 missing X-Zammad-Delivery or invalid JSON (detail as returned by the handler); 500 on unexpected failures (detail Internal server error).
Handle direct delivery requests.
Authentication: None
Request Body:
{
"request_id": "string",
"session_id": "string",
"user_id": "string",
"agent_id": "string",
"subject": "string",
"content": "string",
"template_variables": {}
}Response:
{
"status": "success",
"request_id": "string",
"deliveries": []
}Handle notification CloudEvents (request acknowledgments, status updates).
Authentication: None
Request Body: CloudEvent format
Response:
{
"status": "success",
"message": "Notification processed"
}Get system-wide integration default configurations.
Authentication: None
Response:
{
"default_integrations": {
"SLACK": {
"enabled": true,
"priority": 1,
"retry_count": 3,
"retry_delay_seconds": 60,
"config": {
"thread_replies": false,
"mention_user": false,
"include_agent_info": true
}
},
"EMAIL": {
"enabled": true,
"priority": 2,
"retry_count": 3,
"retry_delay_seconds": 60,
"config": {
"include_agent_info": true
}
}
}
}Get user's effective integration configuration.
Authentication: None
Response:
{
"user_id": "string",
"user_overrides": {
"EMAIL": {
"enabled": true,
"priority": 1,
"retry_count": 5,
"retry_delay_seconds": 30,
"config": {
"email_address": "user@company.com",
"format": "html"
}
}
},
"effective_configs": {
"EMAIL": {
"enabled": true,
"priority": 1,
"retry_count": 5,
"retry_delay_seconds": 30,
"config": {
"email_address": "user@company.com",
"format": "html"
}
},
"SLACK": {
"enabled": true,
"priority": 1,
"retry_count": 3,
"retry_delay_seconds": 60,
"config": {
"thread_replies": false,
"mention_user": false,
"include_agent_info": true
}
}
},
"using_integration_defaults": false
}Create or update user integration configuration.
Authentication: None
Request Body:
{
"integration_type": "EMAIL",
"enabled": true,
"config": {
"email_address": "user@company.com",
"format": "html"
},
"priority": 1,
"retry_count": 5,
"retry_delay_seconds": 30
}Response:
{
"id": 1,
"user_id": "string",
"integration_type": "EMAIL",
"enabled": true,
"priority": 1,
"retry_count": 5,
"retry_delay_seconds": 30,
"config": {
"email_address": "user@company.com",
"format": "html"
},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}Update user integration configuration.
Authentication: None
Request Body:
{
"enabled": false,
"retry_count": 10
}Response:
{
"id": 1,
"user_id": "string",
"integration_type": "EMAIL",
"enabled": false,
"priority": 1,
"retry_count": 10,
"retry_delay_seconds": 30,
"config": {
"email_address": "user@company.com",
"format": "html"
},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}Delete user integration configuration.
Authentication: None
Response:
{
"status": "success",
"message": "Integration configuration deleted"
}Reset user to system integration defaults.
Authentication: None
Response:
{
"status": "success",
"message": "User configuration reset to defaults"
}List user's custom integration configurations.
Authentication: None
Response:
{
"user_id": "string",
"integrations": [
{
"id": 1,
"integration_type": "EMAIL",
"enabled": true,
"priority": 1,
"retry_count": 5,
"retry_delay_seconds": 30,
"config": {
"email_address": "user@company.com",
"format": "html"
},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
]
}Get user's delivery history.
Authentication: None
Query Parameters:
limit(optional): Number of records to return (default: 50)offset(optional): Number of records to skip for pagination (default: 0)
Response:
[
{
"id": 1,
"request_id": "string",
"session_id": "string",
"user_id": "string",
"integration_type": "EMAIL",
"subject": "string",
"content": "string",
"status": "DELIVERED",
"error_message": null,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
]Health check endpoint for Integration Dispatcher.
Authentication: None
Response:
{
"status": "healthy",
"service": "integration-dispatcher",
"version": "0.1.0",
"timestamp": "2024-01-01T00:00:00Z"
}enum IntegrationType {
SLACK = "SLACK",
WEB = "WEB",
CLI = "CLI",
TOOL = "TOOL",
EMAIL = "EMAIL",
SMS = "SMS",
WEBHOOK = "WEBHOOK",
TEAMS = "TEAMS",
DISCORD = "DISCORD",
TEST = "TEST"
}enum SessionStatus {
ACTIVE = "ACTIVE",
INACTIVE = "INACTIVE",
EXPIRED = "EXPIRED",
ARCHIVED = "ARCHIVED"
}enum DeliveryStatus {
PENDING = "PENDING",
DELIVERED = "DELIVERED",
FAILED = "FAILED",
RETRYING = "RETRYING",
EXPIRED = "EXPIRED"
}interface NormalizedRequest {
request_id: string;
session_id: string;
user_id: string;
integration_type: IntegrationType;
request_type: string;
content: string;
integration_context: Record<string, any>;
user_context: Record<string, any>;
target_agent_id?: string;
requires_routing: boolean;
created_at: string;
}interface DeliveryRequest {
request_id: string;
session_id: string;
user_id: string;
agent_id: string;
content: string;
metadata: Record<string, any>;
created_at: string;
}All error responses follow the ErrorResponse schema with error, error_code, and optional request_id fields.
{
"error": "Validation failed",
"error_code": "HTTP_400",
"request_id": "optional-request-id"
}{
"error": "Authentication required",
"error_code": "HTTP_401"
}{
"error": "User ID mismatch",
"error_code": "HTTP_403"
}{
"error": "Resource not found",
"error_code": "HTTP_404"
}{
"error": "Internal server error",
"error_code": "INTERNAL_ERROR"
}Both Request Manager and Integration Dispatcher provide two health check endpoints:
Lightweight health check without database dependency. Returns basic service status:
status: Service health statusservice: Service nameversion: Service versiontimestamp: Current timestamp
Detailed health check with database connectivity verification. Returns:
status: Service health statustimestamp: Current timestampversion: Service versiondatabase_connected: Database connectivity statusservices: Additional service-specific status information
Note: The simple /health endpoint is recommended for container liveness probes as it doesn't depend on database connectivity.
The Integration Dispatcher's /health/detailed endpoint includes integration availability information. The system automatically determines which integrations are available based on:
- SLACK: Bot token and signing secret configuration
- EMAIL: SMTP server configuration
- TEST: Test integration configuration
- WEBHOOK: Always available (no health check)
- SMS: Not implemented (always disabled)
- Integration Guide - Complete integration and request management guide
- Guardrails Guide - Content moderation and safety configuration
- Architecture Diagrams - System architecture and flow diagrams
- Authentication Guide - Authentication setup and configuration