Skip to main content

Introduction to Synthreo Builder API

Welcome to the Synthreo Builder API documentation. This guide provides developers and end-users with the necessary information to integrate and operate AI agents built on the Synthreo platform via our web API. Whether you're looking to execute cognitive diagrams, manage AI agents, or integrate Synthreo's powerful AI capabilities into your applications, this documentation will serve as your comprehensive resource.

What is the Synthreo Builder API?​

The Synthreo Builder API allows programmatic interaction with the Synthreo platform, enabling you to extend the functionality of your AI agents beyond the visual builder environment. This means you can:

  • Execute AI Cognitive Diagrams: Trigger and interact with your pre-built AI workflows from any external application.
  • Manage AI Agents: Programmatically create, update, and delete your AI agents.
  • Integrate with Existing Systems: Seamlessly connect Synthreo AI capabilities with your websites, mobile applications, backend services, and other tools.
  • Automate Workflows: Leverage AI agents to automate complex tasks and processes within your own systems.

Key Concepts​

Before diving into the API, it's helpful to understand some core concepts within the Synthreo platform:

Cognitive Diagrams​

Cognitive diagrams are the visual workflows you design within the Synthreo builder. They define the flow of information and logic for your AI agents, orchestrating how user input is processed through various AI nodes (e.g., Azure OpenAI, custom data processing, external APIs) to generate responses or perform actions. Each diagram represents a unique AI agent or a specific AI-driven task.

AI Agents​

Within the Synthreo ecosystem, AI agents are intelligent entities powered by cognitive diagrams. These agents can be designed for a multitude of purposes, from customer service chatbots to data analysis assistants. The Builder API provides the means to interact with these agents programmatically, allowing them to function as an integral part of your applications.

Template Variables​

Template variables are placeholders within your cognitive diagrams that allow you to dynamically inject data from your API calls. By sending JSON data via the API, you can populate these variables, enabling your AI agents to process context-rich information and generate highly personalized or relevant responses. For example, a {{userSays}} variable might capture the user's message, while {{userName}} could provide the user's name for a personalized greeting.

API Architecture Overview​

The Synthreo API is structured into two main components:

  • Auth API (AuthServerApi): Handles user authentication, login, token management, and tenant management. This is your gateway to obtaining the necessary credentials to interact with the main Builder API.
  • Builder API (botx_api): Contains the core platform functionality, including robot (AI agent) management, user management, integrations, payments, and more. This is where the majority of your interactions with Synthreo AI agents will occur.

This documentation will guide you through authenticating with the Auth API and then utilizing the various endpoints of the Builder API to harness the full power of your Synthreo AI agents.

Getting Started​

To begin using the Synthreo Builder API, you will need:

  1. A Synthreo account with access to the platform.
  2. At least one published cognitive diagram or AI agent within your Synthreo account.
  3. Your Synthreo user credentials (email, password, and user ID).
  4. The ID of the cognitive diagram or AI agent you wish to interact with.

Let's proceed to the next section to understand how to authenticate and obtain an access token for your API calls.