Smartwebchat API

REST API for creating and managing AI chatbots. Designed for agent-to-agent communication.

Authentication

1. Get an API Key

Create a key in the dashboard at https://smartwebchat.eu/dashboard/agenten (account owner only). You choose two things there:

Read only or read and write. A read-only key answers GET requests and returns 403 for every write.
A validity of 30, 90 or 365 days — or none.

The key is shown once and never again.

2. Use the API Key

Pass your API key in the Authorization header:

Authorization: Bearer swc_a1b2c3d4e5f6...

Response Format

All endpoints return JSON with a consistent structure:

Success

{
  "data": { ... },
  "error": null
}

Error

{
  "data": null,
  "error": "Error message"
}

Chatbot Endpoints

POST/api/v1/chatbots

Create a new AI chatbot for your business.

curl -X POST https://smartwebchat.eu/api/v1/chatbots \
  -H "Authorization: Bearer swc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Practice Assistant",
    "businessName": "Dr. Taylor Dental Practice",
    "industry": "Zahnarzt",
    "description": "Dental practice in central Berlin",
    "personality": "freundlich",
    "faqs": [
      {
        "question": "What are your opening hours?",
        "answer": "Mon-Fri 8:00-18:00, Sat 9:00-13:00"
      }
    ]
  }'

GET/api/v1/chatbots

List all your chatbots.

curl https://smartwebchat.eu/api/v1/chatbots \
  -H "Authorization: Bearer swc_YOUR_KEY"

GET/api/v1/chatbots/{id}

Get chatbot details including message count and lead count.

curl https://smartwebchat.eu/api/v1/chatbots/BOT_ID \
  -H "Authorization: Bearer swc_YOUR_KEY"

PUT/api/v1/chatbots/{id}

Update a chatbot's configuration (name, FAQs, personality, etc.).

curl -X PUT https://smartwebchat.eu/api/v1/chatbots/BOT_ID \
  -H "Authorization: Bearer swc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New name",
    "businessName": "Dr. Taylor Dental Practice",
    "industry": "Zahnarzt",
    "personality": "professionell"
  }'

DELETE/api/v1/chatbots/{id}

Permanently delete a chatbot and all its data.

curl -X DELETE https://smartwebchat.eu/api/v1/chatbots/BOT_ID \
  -H "Authorization: Bearer swc_YOUR_KEY"

Chat Endpoint

POST/api/v1/chatbots/{id}/chat

Send a message to a chatbot and receive an AI-generated reply. This is the core endpoint for agent-to-chatbot communication. Pass a sessionId to continue a conversation.

curl -X POST https://smartwebchat.eu/api/v1/chatbots/BOT_ID/chat \
  -H "Authorization: Bearer swc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your opening hours?",
    "sessionId": "optional-session-id"
  }'

# Response:
# {
#   "data": {
#     "reply": "Our opening hours are Mon-Fri 8:00-18:00...",
#     "sessionId": "abc-123"
#   },
#   "error": null
# }

Leads & Conversations

GET/api/v1/chatbots/{id}/leads

Get leads captured by a chatbot. Leads are automatically created when users request callbacks, appointments, or provide contact details.

curl "https://smartwebchat.eu/api/v1/chatbots/BOT_ID/leads?limit=50" \
  -H "Authorization: Bearer swc_YOUR_KEY"

GET/api/v1/chatbots/{id}/conversations

Get chat conversations grouped by session. Returns messages in chronological order within each session.

curl "https://smartwebchat.eu/api/v1/chatbots/BOT_ID/conversations?limit=20" \
  -H "Authorization: Bearer swc_YOUR_KEY"

API Key Generation

POST/api/v1/api-keyCookie Auth

Retired on 25 August 2026 — always returns 410. This endpoint issued keys that could not be limited to read-only access and never expired. Create keys in the dashboard at https://smartwebchat.eu/dashboard/agenten instead.

curl -X POST https://smartwebchat.eu/api/v1/api-key
# 410 Gone

Webhook Events

Configure a webhook URL on your account to receive real-time event notifications. Smartwebchat sends POST requests with JSON payloads to your URL.

lead.created

Fired when a chatbot captures a new lead (contact request, appointment, callback).

message.received

Fired when a user sends a message to one of your chatbots.

chatbot.created

Fired when a new chatbot is created via the API.

Payload Format

{
  "event": "lead.created",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "data": {
    "lead": {
      "id": "...",
      "chatbotId": "...",
      "name": "Max Sample",
      "email": "max@example.com",
      "phone": "+49 170 1234567",
      "type": "callback",
      "status": "new"
    }
  }
}

Headers

Content-Type: application/json
User-Agent: Smartwebchat-Webhooks/1.0
X-Smartwebchat-Event: lead.created

OpenAPI Spec

The full OpenAPI 3.1 specification is available at /api/openapi.json. Import it into tools like Postman, Insomnia, or any OpenAPI-compatible client. It is generated from the code and is the only specification of this API.

AI agent discovery metadata is available at /.well-known/ai-plugin.json.

For AI Agents

Machine-readable entry point with published product data, the available agent interfaces and an explicit status for everything not published yet: https://smartwebchat.eu/agents/start.

MCP server over Streamable HTTP: https://smartwebchat.eu/api/mcp. Authenticate with the same API key as the REST API (Authorization: Bearer swc_...). The same server also runs locally over stdio.

Connecting Claude: when adding the connector, choose to sign in now in the authentication section and, in the OAuth client section, your own OAuth client with the client ID swcc_iTMNpUXolYz5QY8z9pZoqw. You will then be taken to the Smartwebchat sign-in and decide there whether Claude gets access to your account.

smartwebchat_service_info — answers without an API key
smartwebchat_list_chatbots
smartwebchat_create_chatbot
smartwebchat_chat
smartwebchat_get_leads
smartwebchat_update_lead
smartwebchat_diagnose
smartwebchat_get_fit — answers without an API key
smartwebchat_get_quote — answers without an API key
smartwebchat_prepare_handoff — answers without an API key