API Reference

Integrate InnFuse into your applications with the REST API

Authentication

All API requests require a Bearer token. Generate an API key from your dashboard under Settings > API Keys.

Authorization: Bearer YOUR_API_KEY

Include the token in the Authorization header of every request: Authorization: Bearer YOUR_API_KEY

Important Never expose your API key in client-side code. Always make API calls from your server.

Rate Limits

API requests are rate-limited per API key to ensure fair usage.

60 requests per minute (default endpoints)
10 concurrent connections (streaming endpoints)
30 requests per minute (management endpoints)

Inbound Messages

Send messages to an agent programmatically. The agent processes the message and returns a response.

POST /api/innfuse/v1/messages

curl -X POST https://innconnect.io/api/innfuse/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_abc123",
    "message": "How do I reset my password?",
    "channel": "api",
    "metadata": {
        "user_id": "user_456",
        "language": "nl"
    }
}'

Response Format

{
    "id": "msg_xyz789",
    "conversation_id": "conv_abc123",
    "role": "assistant",
    "content": "You can reset your password by...",
    "agent": "support-agent",
    "tokens_used": 342,
    "tools_invoked": ["kb_search"],
    "created_at": "2026-03-27T10:30:00Z"
}

Server-Sent Events (SSE)

Stream agent responses in real time using Server-Sent Events. This provides a typing-like experience for end users.

POST /api/innfuse/v1/messages/stream

curl -N -X POST https://innconnect.io/api/innfuse/v1/messages/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_abc123",
    "message": "Explain quantum computing"
}'

Event Types

event: message_start
data: {"conversation_id": "conv_abc123", "agent": "support-agent"}

event: content_delta
data: {"delta": "Quantum computing uses "}

event: content_delta
data: {"delta": "quantum-mechanical phenomena..."}

event: tool_use
data: {"tool": "kb_search", "query": "quantum computing basics"}

event: message_end
data: {"tokens_used": 512, "stop_reason": "end_turn"}

Tip Use SSE for user-facing interfaces where real-time streaming improves the experience. For backend integrations, the standard REST endpoint is simpler.

Conversation Endpoints

Access and manage conversations across all channels.

Method	Endpoint	Description
`GET`	`/api/innfuse/v1/conversations`	GET /api/v1/conversations — List conversations
`GET`	`/api/innfuse/v1/conversations/{id}`	GET /api/v1/conversations/{id} — Get conversation details
`PATCH`	`/api/innfuse/v1/conversations/{id}`	PUT /api/v1/conversations/{id} — Update conversation status
`GET`	`/api/innfuse/v1/conversations/{id}/messages`	GET /api/v1/conversations/{id}/messages — Get conversation messages

Agent Endpoints

Manage agents programmatically. Create, update, and configure agents via the API.

Method	Endpoint	Description
`GET`	`/api/innfuse/v1/agents`	GET /api/v1/agents — List all agents
`GET`	`/api/innfuse/v1/agents/{id}`	GET /api/v1/agents/{id} — Get agent details
`POST`	`/api/innfuse/v1/agents`	POST /api/v1/agents — Create a new agent
`PUT`	`/api/innfuse/v1/agents/{id}`	PUT /api/v1/agents/{id} — Update an agent

Webhooks

Receive real-time notifications when events occur in your InnFuse workspace. Configure webhook URLs in Settings > Webhooks.

Event	Description
`conversation.created`	conversation.created — New conversation started
`conversation.resolved`	conversation.resolved — Conversation marked as resolved
`message.received`	message.received — New message in a conversation
`agent.handoff`	agent.handoff — Agent transferred conversation to another agent or human
`tool.approval_needed`	tool.approval_required — Tool execution requires human approval

Webhook Payload

{
    "event": "conversation.resolved",
    "timestamp": "2026-03-27T14:22:00Z",
    "data": {
        "conversation_id": "conv_abc123",
        "agent": "support-agent",
        "duration_seconds": 245,
        "messages_count": 8,
        "satisfaction_score": 4.5
    },
    "signature": "sha256=..."
}

Security Verify webhook signatures using the HMAC-SHA256 hash in the X-InnFuse-Signature header. Compare it against the payload signed with your webhook secret.