API Reference

The CraftChat REST API lets you programmatically interact with your CraftChat instance. You can list conversations, send chat messages, retrieve analytics data, trigger content crawls, and manage settings.

API access is available on the Pro plan and above.

Authentication

All API requests must include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can find your API key in the CraftChat dashboard under Settings → API Keys. Each account can have up to 5 active API keys. Keys can be revoked at any time from the dashboard.

All requests must use HTTPS. Requests over plain HTTP are rejected with a 301 redirect.

Base URL

https://api.craftchat.net/v1

All endpoint paths in this document are relative to this base URL. For example, GET /conversations means GET https://api.craftchat.net/v1/conversations.

Endpoints

GET /conversations

Retrieves a paginated list of chat conversations for your site.

Parameters

Example Request

curl -X GET "https://api.craftchat.net/v1/conversations?page=1&per_page=10&status=active" \
  -H "Authorization: Bearer cc_live_xxxxx"

Example Response

{
  "data": [
    {
      "id": "conv_abc123",
      "visitor_id": "vis_xyz789",
      "domain": "example.com",
      "status": "active",
      "message_count": 4,
      "started_at": "2026-03-07T10:30:00Z",
      "last_message_at": "2026-03-07T10:32:15Z",
      "messages": [
        {
          "id": "msg_001",
          "role": "user",
          "content": "What are your business hours?",
          "timestamp": "2026-03-07T10:30:00Z"
        },
        {
          "id": "msg_002",
          "role": "assistant",
          "content": "We're open Monday through Friday, 9 AM to 6 PM JST.",
          "timestamp": "2026-03-07T10:30:02Z"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 142,
    "total_pages": 15
  }
}

POST /chat

Sends a message to the AI chatbot and receives a response. This endpoint is primarily used for custom integrations (e.g., embedding CraftChat in a mobile app or external system).

Request Body

Example Request

curl -X POST "https://api.craftchat.net/v1/chat" \
  -H "Authorization: Bearer cc_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What products do you recommend for beginners?",
    "domain": "example.com",
    "visitor_id": "user_12345",
    "language": "en"
  }'

Example Response

{
  "conversation_id": "conv_def456",
  "message": {
    "id": "msg_003",
    "role": "assistant",
    "content": "For beginners, I'd recommend starting with our Starter Kit ($29.99) which includes everything you need to get going. We also have a comprehensive Getting Started Guide available on our blog.",
    "timestamp": "2026-03-07T10:35:02Z",
    "sources": [
      {
        "title": "Starter Kit - Product Page",
        "url": "https://example.com/products/starter-kit"
      },
      {
        "title": "Getting Started Guide",
        "url": "https://example.com/blog/getting-started"
      }
    ],
    "products": [
      {
        "id": "prod_001",
        "name": "Starter Kit",
        "price": "$29.99",
        "url": "https://example.com/products/starter-kit",
        "image": "https://example.com/images/starter-kit.jpg",
        "in_stock": true
      }
    ]
  },
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 87,
    "total_tokens": 1337
  }
}

GET /analytics

Retrieves analytics data for your CraftChat instance, including conversation counts, response metrics, and popular topics.

Parameters

Example Request

curl -X GET "https://api.craftchat.net/v1/analytics?period=30d&granularity=day" \
  -H "Authorization: Bearer cc_live_xxxxx"

Example Response

{
  "period": {
    "start": "2026-02-05T00:00:00Z",
    "end": "2026-03-07T23:59:59Z"
  },
  "summary": {
    "total_conversations": 1842,
    "total_messages": 5521,
    "avg_messages_per_conversation": 3.0,
    "avg_response_time_ms": 1250,
    "unique_visitors": 1203,
    "responses_used": 3680,
    "responses_limit": 10000
  },
  "daily": [
    {
      "date": "2026-03-07",
      "conversations": 62,
      "messages": 186,
      "unique_visitors": 45
    }
  ],
  "top_topics": [
    { "topic": "Pricing", "count": 312 },
    { "topic": "Shipping", "count": 287 },
    { "topic": "Product availability", "count": 198 },
    { "topic": "Returns policy", "count": 156 },
    { "topic": "Technical support", "count": 134 }
  ],
  "satisfaction": {
    "positive": 78,
    "neutral": 18,
    "negative": 4
  }
}

POST /crawl

Triggers a content crawl for your site. Use this to programmatically refresh the AI’s knowledge base after deploying content changes.

Request Body

Example Request

curl -X POST "https://api.craftchat.net/v1/crawl" \
  -H "Authorization: Bearer cc_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "full": false,
    "urls": [
      "https://example.com/products/new-arrival",
      "https://example.com/blog/latest-post"
    ],
    "callback_url": "https://example.com/webhooks/crawl-complete"
  }'

Example Response

{
  "crawl_id": "crawl_ghi789",
  "status": "queued",
  "type": "partial",
  "urls_queued": 2,
  "estimated_duration_seconds": 15,
  "created_at": "2026-03-07T10:40:00Z"
}

The crawl runs asynchronously. You can poll the crawl status using GET /crawl/:crawl_id or use the callback_url parameter to receive a notification when it completes.

GET /settings

Retrieves the current configuration settings for your CraftChat instance.

Parameters

This endpoint takes no query parameters.

Example Request

curl -X GET "https://api.craftchat.net/v1/settings" \
  -H "Authorization: Bearer cc_live_xxxxx"

Example Response

{
  "site_name": "My Store",
  "domain": "example.com",
  "plan": "pro",
  "widget": {
    "position": "bottom-right",
    "primary_color": "#4F46E5",
    "text_color": "#FFFFFF",
    "user_message_color": "#4F46E5",
    "welcome_message": {
      "en": "Hi there! How can I help you today?",
      "ja": "こんにちは！何かお手伝いできることはありますか？"
    },
    "icon": "default"
  },
  "crawl": {
    "frequency": "on_publish",
    "include_patterns": ["*"],
    "exclude_patterns": ["/cart", "/checkout", "/my-account/*"],
    "post_types": ["post", "page", "product"],
    "last_crawl_at": "2026-03-07T08:00:00Z",
    "indexed_pages": 87
  },
  "woocommerce": {
    "enabled": true,
    "sync_frequency": "realtime",
    "include_out_of_stock": true,
    "product_count": 234
  },
  "response_length": "balanced",
  "data_retention_days": 90,
  "monthly_usage": {
    "responses_used": 3680,
    "responses_limit": 10000,
    "period_start": "2026-03-01T00:00:00Z",
    "period_end": "2026-03-31T23:59:59Z"
  }
}

Rate Limits

API requests are rate-limited to ensure fair usage and platform stability. Limits are applied per API key:

When you exceed a rate limit, the API returns a 429 Too Many Requests response with the following headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709805600
Retry-After: 45

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with details:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401
  }
}