# API Basics

Navigating the Karabo.ai API involves a few fundamental concepts critical for secure and effective interaction with our system. These include Authentication, understanding the Base URL, and familiarizing yourself with common API Error Codes. Authentication is essential for accessing chatbot functionalities, ensuring that interactions are securely managed through Token-based authentication. Every request requires a unique token, serving as a key to your account's secure access. This introductory section lays the groundwork for working with the Karabo.ai API, providing you with the essential knowledge needed to start building and managing your chatbots efficiently.

# Authentication

For each request to our API, the Authorization header must be populated with your valid token. This token acts as a digital key, granting you access to your chatbot endpoints and ensuring that your interactions with the API are secure and authenticated.

# Including Your Token in Requests

When preparing your API request, include the Authorization header followed by your token. This header is critical for the API to recognize and validate your access rights.

Example:

Authorization: Token abcdefghijkl.....

Here, abcdefghijkl..... represents your unique, valid token. It's essential to replace this placeholder with your actual token provided upon successful authentication.

See Postman example screenshot for the correct way to authenticate your API requests: Postman Karabo Authentication

TIP

Always keep your token confidential to prevent unauthorized access to your account. If you believe your token has been compromised, we recommend regenerating it immediately through the API's token management endpoints.

# Base URL

The base URL serves as the foundational web address for accessing the Karabo.ai API. It is the initial part of the URL that is common across all the endpoints, providing a consistent starting point for constructing requests to the API. For Karabo.ai, the base URL is:

https://karabo.ai/api/v1.0/

This URL is crucial for developers as it precedes the specific endpoint paths that allow for various operations related to chatbots, such as creation, editing, fetching information, adding documents, and more. When you're crafting a request to any of Karabo.ai's API endpoints, you'll start with this base URL and append the endpoint-specific path to complete the request URL.

# Example Usage

When accessing a specific feature of the API, such as creating a new chatbot, the base URL is combined with the endpoint path to form the full request URL. For instance, to create a chatbot, you might append api-knowledge-retrieval/ to the base URL, resulting in:

https://karabo.ai/api/v1.0/api-knowledge-retrieval/

Similarly, to add documents to a chatbot's knowledge base, you would append chatbot-document-add/<str:uniqueId>/ to the base URL:

https://karabo.ai/api/v1.0/chatbot-document-add/uniqueId123/

# Importance of the Base URL

Consistency: Provides a standard prefix for all API requests, ensuring uniformity.
Version Control: The inclusion of the version number (v1.0) in the base URL allows for version-specific interactions with the API. This is critical for maintaining backward compatibility and making version upgrades smooth for users.
Simplicity: Simplifies the construction of API request URLs by providing a clear and concise starting point.

Ensure that you use the correct base URL for the version of the API you intend to interact with, as this can change with major updates or revisions to the API. Always refer to the most current version of the Karabo.ai API documentation for the latest base URL and endpoint information.

# API Error Codes

When working with APIs, understanding the meaning behind various error codes can significantly streamline the troubleshooting process. Error codes provide insight into what went wrong with a request, allowing developers to quickly identify and address issues. Below are common API error codes you may encounter while interacting with the Karabo.ai API, along with their meanings:

# 400 Bad Request

This error indicates that the server cannot process the request due to client-side issues, such as malformed request syntax, invalid request message parameters, or deceptive request routing.

Common Causes:

Missing required parameters in the request.
Invalid format of request data.

# 401 Unauthorized

This error signifies that the request lacks valid authentication credentials for the target resource or that the provided credentials have not been accepted.

Common Causes:

Missing or invalid API token.
Attempting to access a resource that requires authentication without providing credentials.

# 403 Forbidden

This error means the server understands the request but refuses to authorize it. Unlike a 401 Unauthorized response, authenticating will not make a difference.

Common Causes:

Permissions not sufficient to access the requested resource.
Accessing a feature not included in your subscription plan.

# 404 Not Found

This error is returned when the server cannot find the requested resource. This can happen if the endpoint is incorrect or the resource (e.g., a specific chatbot) does not exist.

Common Causes:

Typo in the endpoint URL.
Referencing a non-existent chatbot ID.

# 405 Method Not Allowed

This error indicates that the request method is known by the server but is not supported by the target resource.

Common Causes:

Using a POST request on an endpoint that only accepts GET requests, and vice versa.

# 408 Request Timeout

This error suggests that the server would like to shut down an unused connection. It occurs when a client fails to complete a request within the server's allotted timeout period.

Common Causes:

Slow client connection.
Request complexity exceeding server processing capabilities within a reasonable timeframe.

# 429 Too Many Requests

This error signifies that the user has sent too many requests in a given amount of time ("rate limiting").

Common Causes:

Hitting an API rate limit.
Excessive API calls in a short period.

# 500 Internal Server Error

This generic error message indicates an unexpected condition encountered by the server, preventing it from fulfilling the request.

Common Causes:

Server-side bugs or issues.
Unhandled exceptions within server-side processing.

# 503 Service Unavailable

This error is returned when the server is not ready to handle the request, usually due to maintenance or overload.

Common Causes:

Server maintenance or upgrades.
Server overload leading to temporary unavailability.

Understanding these common API error codes and their causes can help developers diagnose and fix issues more efficiently, leading to a smoother development experience and more reliable application behavior.

# Rate Limits

Karabo.ai API's rate limits are implemented to ensure equitable access and optimal performance across our services. By setting thresholds on the number of requests users can make, we prevent excessive use that could affect service availability and quality. Our rate limiting mechanism differentiates between anonymous users, authenticated users, and specific actions requiring heightened security measures.

# Understanding Rate Limits

Our API employs rate limits as follows:

Anonymous Rate Throttle: This limit applies to users who are not authenticated, restricting the number of API requests they can make. It's designed to encourage users to authenticate, thus enabling more personalized interactions and a secure experience.
User Rate Throttle: For authenticated users, the API permits a greater number of requests. This acknowledges the necessity for more frequent access as users interact with personalized data and functionalities.
Subscription Rate Throttle: This throttle is exclusively for code verification endpoints. It is implemented to safeguard against brute force attacks by limiting the attempts a user can make. This ensures the integrity and security of user authentication processes.

# Key Rate Limit Details

The specific rate limits enforced are:

Anonymous users: Limited to 20 requests per day. This encourages users to authenticate for a more comprehensive access.
Authenticated users: Allowed up to 100 requests per day, facilitating regular use of the API for various operations.
Code Verification Attempts: Capped at 5 attempts per day under the Subscription Rate Throttle, specifically to protect against brute force attacks on code verification endpoints.

# Managing Within Limits

If you exceed the allotted number of requests, the API will return a 429 Too Many Requests error. To avoid hitting these limits, consider the following strategies:

Utilize caching for repeated requests to minimize your call count.
Opt for batch processing when possible, to reduce the number of requests.
Plan API interactions strategically to distribute requests evenly and avoid peak times.

These limits are constantly under review, if you require higher limits please send a message to hello[at]karano.ai with your request.

Creating a New Account →