Overview

Checkout out the Botanalytics Postman documentation. We hope it makes it easier to explore the Botanalytics REST API and we’re also keen to hear any feedback that you might have on our feedback forum.

Introduction

The Botanalytics API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API token in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

Be sure to subscribe to Botanalytics's API announce mailing list to receive information on new additions and changes to Botanalytics's API and language libraries.

Authentication

The Botanalytics API authentication is organized around JWT authentication. Authenticate your account by including your JWT token in API requests. You can manage your API tokens for the each channel in the Project settings. Your JWT API token carry many privileges, so it's crucial to keep them secure. Avoid sharing your API token in public areas like GitHub or client-side code and so forth. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. It's important to note that API requests without proper authentication will also fail.

Supported Authentication Methods

The Botanalytics REST API uses Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a channel creation request. The client must send this token in the Authorization header when making requests to protected resources. Follow the steps below to obtain and use an API key:

1. Obtaining an API Key:

To obtain an API key, sign up for a Botanalytics account at. Once you have created an account, navigate to your project settings or dashboard to generate an API key.

2. Including the API Key:

To include the API key in your requests:

• Request Header:

Include the API key in the Authorization header as a Bearer token. The header should be formatted as follows:

Authorization: Bearer BOTANALYTICS_API_KEY

Please note the following security best practices for API key usage:

• Keep API Keys Secure: Treat your API key as a sensitive credential and keep it confidential. Do not expose your API key in client-side code or publicly accessible websites.

• Secure Storage: Store your API key securely, following industry best practices. Consider using encryption or secure key management systems to protect your API key.

• Transmitting API Keys: When transmitting the API key over the network, ensure that you use secure channels such as HTTPS to encrypt the communication.

• Scoped Access: Depending on the API design, certain endpoints or actions may require specific permissions or scopes. Review the API documentation to understand any additional authorization requirements for specific API functionalities.

If you encounter authentication errors or issues, the API will respond with appropriate error codes and messages. Ensure that you handle these errors gracefully.

Remember to adapt the instructions and examples to match the specific details and conventions of the Botanalytics API authentication process.

Errors

When you interact with the Botanalytics API , it's important to handle errors gracefully to ensure a smooth integration and provide a good user experience. The API returns appropriate HTTP response codes and error messages to indicate and describe any errors that occur.

Botanalytics uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Botanalytics's servers.

HTTP Response Codes

Status Code	Status Name	Description
200, 201	OK	Everything worked as expected (some API calls may return 201 instead).
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	You forgot to include your API token or it is wrong.
404	Not Found	The requested resource doesn't exist.
500, 502, 503, 504	Server Errors	Something went wrong on Botanalytics's end. Try again later. (These are rare.)

Error Messages

In addition to the HTTP response codes, the API provides detailed error messages in the response body to help you identify and troubleshoot issues. Error messages are returned in JSON format and typically include information such as the error code and a descriptive message.

Make sure you read the response body to extract and handle error messages appropriately. The error messages can provide insights into the specific issue you encountered and guide you in resolving it.

API libraries

Official libraries for the Botanalytics API are available in several languages such as Node.js and Python.