Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maia.ai/llms.txt

Use this file to discover all available pages before exploring further.

Custom Connectors allows you to streamline your interactions with external data sources or services using API endpoints. In the Custom Connector setup, you can define one or more API endpoints. Each of these endpoints represents a specific place or action you want to connect to. You just need to provide some details like the way you want to communicate with the API (e.g., using GET or POST), the path to the API (the URL), any special requests you want to make, and the authentication you need to access it securely. Once you have identified the external API endpoint you wish to set up, you can use it within the dashboard to send HTTP requests to the API. For detailed information on configuring API endpoints in Custom Connector and understanding how it works, read the article further.

​
Configuring the request

  1. Determine the appropriate request method (e.g., GET or POST) based on the requirements of the third-party API.
  2. Paste or input the API’s endpoint URL as needed.

​
GET and POST requests

The custom connector requests consist of several key components: HTTP Method: The custom connectors primarily support two HTTP methods: GET and POST. These methods are essential for interacting with external services and data sources.
  • GET: This method is used to retrieve data from an external resource or API.
  • POST: This method is used to retrieve data from an API when the query parameters are too large, complex, or sensitive to be safely passed in a URL, allowing them to be sent securely within the request body.
Endpoint (URI): The endpoint refers to the URL or URI that specifies the location of the external resource or API you want to access. This endpoint is vital for directing your connector to the right destination. Headers: Headers in Custom Connector serve various purposes, such as providing authentication credentials, defining the response format, or conveying specific information relevant to your integration.
  • Authentication headers: These headers can include API keys or tokens required to authenticate your connection with the external resource.
  • Content-Type headers: These specify the format of the data being sent or received, such as JSON in the case of Custom Connector.
  • Custom headers: You can add custom headers to convey any additional information necessary for your integration.
Body: When making a POST request, the request body may contain parameters for the API you are requesting data from. The format should be consistent with the Content-Type header.

​
Responses

Each response can either be empty—for example in case of an update that returns an HTTP 204 response and does not need to return additional information—or a JSON object. Success Response (JSON Object): 
{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}
Error Response (JSON Object): 
{
  "error": {
    "code": "400",
    "description": "Bad Request: Invalid input data."
  }
}
For error responses, the API returns a JSON object as well. This object features an “error” key, which points to an error object containing two main attributes: an “error code” and a “description” of the encountered issue. In this illustration, the error code is “400,” indicating a bad request, and the description elaborates on the error, specifying that it resulted from invalid input data. Such structured error responses are beneficial for diagnosing and addressing issues during API interactions.

​
Error handling

Common error HTTP status codes include:
  • 400 Bad Request: This means that client-side input fails validation.
  • 401 Unauthorized: This means the user is not authorized to access a resource. It usually returns when the user isn’t authenticated.
  • 403 Forbidden: This means the user is authenticated, but it is not allowed to access a resource.
  • 404 Not Found: This indicates that a resource was not found.
  • 500 Internal server error: This is a generic server error. It should not be explicitly raised.
  • 502 Bad Gateway: This indicates an invalid response from an upstream server.
  • 503 Service Unavailable: This indicates that something unexpected happened on the server side (it can be anything like server overload, some parts of the system failed, etc.).