API Reference

The HelpFaster API lets you integrate your AI chatbot programmatically. Use it to create chatbots, send messages, retrieve conversations, manage leads, and pull analytics data from your own applications.

Authentication

All API requests require an API key. Generate one from Settings > API Keys in the dashboard. Pass the key in the x-api-key header:

x-api-key: hf_live_abc123...

Keep your API key secret. Do not expose it in client-side code. If a key is compromised, revoke it immediately from the dashboard and generate a new one.

Base URL

All endpoints are relative to:

https://api.helpfaster.ai/v1

Key Endpoints

Chatbots

| Method | Path | Description | |---|---|---| | GET | /chatbots | List all chatbots in your organization. | | GET | /chatbots/:id | Get details for a specific chatbot. | | POST | /chatbots | Create a new chatbot. | | PATCH | /chatbots/:id | Update chatbot settings. |

Conversations

| Method | Path | Description | |---|---|---| | GET | /chatbots/:id/conversations | List conversations for a chatbot. Supports pagination and date filters. | | GET | /conversations/:id | Get a single conversation with all messages. |

Messages

| Method | Path | Description | |---|---|---| | POST | /chatbots/:id/chat | Send a message and receive an AI response. Requires message in the request body. |

Example Request

curl -X POST https://api.helpfaster.ai/v1/chatbots/bot_123/chat \
  -H "x-api-key: hf_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I reset my password?"}'

Example Response

{
  "reply": "To reset your password, go to Settings > Security and click Reset Password...",
  "sources": [
    { "title": "Account Security Guide", "url": "/docs/security", "snippet": "..." }
  ],
  "conversationId": "conv_456"
}

Leads

| Method | Path | Description | |---|---|---| | GET | /chatbots/:id/leads | List captured leads. Supports pagination. | | GET | /leads/:id | Get a single lead with conversation history. |

Analytics

| Method | Path | Description | |---|---|---| | GET | /chatbots/:id/analytics | Get analytics summary. Accepts from and to query parameters (ISO 8601 dates). | | GET | /chatbots/:id/analytics/topics | Get topic clustering data. |

Rate Limits

API rate limits depend on your plan:

| Plan | Requests per minute | |---|---| | Free | 20 | | Starter | 60 | | Growth | 120 | | Scale | 300 |

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Error Responses

All errors follow a consistent format:

{
  "error": "not_found",
  "message": "Chatbot not found."
}

Common status codes: 400 (bad request), 401 (unauthorized), 404 (not found), 429 (rate limited), 500 (server error).

Webhooks

For real-time event delivery, configure webhooks in Settings > Webhooks. Events include conversation.created, conversation.escalated, lead.captured, and message.sent. Each webhook payload includes the full event data and a signature header for verification.