API Reference

This page provides comprehensive documentation for all available endpoints in the NeuralTalk AI API.

Authentication

All API requests require authentication using an API key via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

All API endpoints use the following base URL:

https://api.neuraltalk.ai/v1

Endpoints

Chatbots

List Chatbots

GET /chatbots

Returns a list of all chatbots associated with your account.

Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number for pagination (default: 1)
limit	integer	No	Number of results per page (default: 10)

Response:

{
  "status": "success",
  "data": {
    "chatbots": [
      {
        "id": "bot_123abc",
        "name": "Customer Support Bot",
        "created_at": "2023-04-15T10:30:45Z",
        "status": "active"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10
  }
}

Get Chatbot

GET /chatbots/{chatbot_id}

Returns details for a specific chatbot.

Parameters:

Parameter	Type	Required	Description
chatbot_id	string	Yes	The ID of the chatbot

Response:

{
  "status": "success",
  "data": {
    "id": "bot_123abc",
    "name": "Customer Support Bot",
    "description": "Provides answers to common customer inquiries",
    "created_at": "2023-04-15T10:30:45Z",
    "updated_at": "2023-05-20T14:25:10Z",
    "status": "active",
    "settings": {
      "language": "en",
      "tone": "professional",
      "response_length": "balanced"
    }
  }
}

Conversations

Create Conversation

POST /conversations

Creates a new conversation with a chatbot.

Request Body:

{
  "chatbot_id": "bot_123abc",
  "user_id": "user_456"
}

Response:

{
  "status": "success",
  "data": {
    "conversation_id": "conv_789xyz",
    "created_at": "2023-06-20T14:22:33Z"
  }
}

Send Message

POST /conversations/{conversation_id}/messages

Sends a message to an existing conversation.

Request Body:

{
  "text": "What services do you offer?",
  "user_id": "user_456"
}

Response:

{
  "status": "success",
  "data": {
    "message_id": "msg_abc123",
    "conversation_id": "conv_789xyz",
    "text": "We offer a range of services including web development, mobile app development, and digital marketing...",
    "sender_type": "bot",
    "sent_at": "2023-06-20T14:22:45Z"
  }
}

Error Handling

The API uses conventional HTTP status codes to indicate the success or failure of a request:

• 2xx: Success
• 4xx: Client error (invalid request)
• 5xx: Server error

Error responses include a descriptive message:

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "The chatbot_id field is required"
  }
}

Rate Limits

To ensure fair usage of the API, rate limits are applied:

Plan	Rate Limit
Free	100 requests/hour
Basic	1,000 requests/hour
Professional	10,000 requests/hour
Enterprise	Custom

When you exceed your rate limit, the API will return a 429 Too Many Requests response.

---

For additional information or questions about the API, please contact our support team.