API Docs

FlowGent API Reference

Learn how to integrate FlowGent's powerful AI agents into your applications using our REST API.

Introduction

Welcome to the FlowGent API documentation. This API allows you to integrate FlowGent's powerful AI agent capabilities into your own applications.

Base URL

https://flowgent.ai/api/public/

What You Can Do

With the FlowGent API, you can:

Create and configure AI agents
Send messages to agents and receive responses
Monitor agent activity and performance
Send templated whatsapp messages

Authentication

Authentication with the FlowGent API is done using API keys. Your API key should be included in the Authorization header of all requests.

API Keys

You can create API keys in the FlowGent Settings. API keys are sensitive credentials and should be kept secure.

Authorization Header

Authorization: YOUR_API_KEY

Security Notice

Never expose your API keys in client-side code or commit them to version control. Consider using environment variables or a secure secrets management system.

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  https://flowgent.ai/api/public/agent

[POST] Chat

Endpoint

/api/public/agent/:agent_id/chat

Description

Send messages to an agent and get a response. This endpoint supports both synchronous and asynchronous processing through an optional callback URL.

Authentication

Requires an API key in the Authorization header.

Authorization: YOUR_API_KEY

Path Parameters

Parameter	Type	Description
agent_id	string	The agent&aposs unique identifier

Request Body

The messages field can be provided in three different formats:

Option 1: Single message string

{
  "messages": "Hello, I have a question about my order",
  "thread_id": "thread_123456",  // Optional
  "callback_url": "https://your-domain.com/webhook"  // Optional
}

Option 2: Single message object

{
  "messages": {
    "role": "user",
    "content": "Hello, I have a question about my order"
  },
  "thread_id": "thread_123456",  // Optional
  "callback_url": "https://your-domain.com/webhook"  // Optional
}

Option 3: Array of message objects

{
  "messages": [
    {
      "role": "user",
      "content": "Hello, I have a question about my order"
    }
  ],
  "thread_id": "thread_123456",  // Optional
  "callback_url": "https://your-domain.com/webhook"  // Optional
}

Parameter	Type	Required	Description
messages	string \| object \| array	Yes	Can be a string, a message object, or an array of message objects
thread_id	string	No	Optional thread ID for continuing a conversation
callback_url	string	No	URL to receive the response asynchronously

Response Structures

⚠️ Important: Always Check Response Body

This endpoint may return HTTP 200 status even when there are errors in the execution. Always check the response body forstatusCode and the results of any tool executions.

Success Response (200 OK)

{
  "statusCode": 200,
  "body": {
    "agent_id": "agent_123abc",
    "conversation_history": [
      {
        "role": "user",
        "content": "Hello, I have a question about my order"
      },
      {
        "role": "assistant",
        "content": "I'd be happy to help with your order. Could you please provide your order number?"
      }
    ],
    "metadata": {
      "id": "meta_xyz789",
      "model": "gpt-4",
      "timestamp": "2024-03-21T14:30:00Z",
      "tool_calls": {},
      "execution_time": 2500,
      "used_credits": 1,
      "thread_id": "thread_123456"
    }
  }
}

No Credits Available (402 Payment Required)

{
  "statusCode": 402,
  "body": {
    "agent_id": "agent_123abc",
    "message": "No credits available",
    "error": "No credits available"
  }
}

Service Temporarily Unavailable (503)

{
  "statusCode": 503,
  "body": {
    "agent_id": "agent_123abc",
    "message": "Service temporarily unavailable",
    "error": "AI provider is currently experiencing high traffic"
  }
}

Internal Server Error (500)

{
  "statusCode": 500,
  "body": {
    "error": "An unexpected error occurred while processing your request"
  }
}

Asynchronous Response

When using the callback_url parameter, you'll receive an immediate acknowledgement:

{
  "message": "Request accepted and being processed asynchronously",
  "status": "processing"
}

[GET] Usage

Endpoint

/api/public/agent/:agent_id/usage

Description

Get credit usage statistics for an agent. By default, returns data for the last 7 days (ending yesterday). You can optionally specify a custom date range using query parameters.

Note: Usage tracking is only active from May 28, 2025 onwards. Data before this date will show 0 credits used.

Authentication

Requires an API key in the Authorization header.

Authorization: YOUR_API_KEY

Path Parameters

Parameter	Type	Description
agent_id	string	The agent's unique identifier

Query Parameters

Optional parameters to specify a custom date range. If not provided, defaults to the last 7 days ending yesterday.

Parameter	Type	Required	Description
start_date	string	No*	Start date for the query range in YYYY-MM-DD format
end_date	string	No*	End date for the query range in YYYY-MM-DD format

* If only start_date is provided, yesterday will be used as end_date. If only end_date is provided, an error will be returned. The date range cannot exceed 31 days, and the end_date cannot be today or in the future (data is only available up to yesterday).

Example Requests

// Default (last 7 days)
GET /api/public/agent/66a72b17-cb03-4397-ab2a-1eef13847737/usage

// Custom date range (both dates)
GET /api/public/agent/66a72b17-cb03-4397-ab2a-1eef13847737/usage?start_date=2025-05-20&end_date=2025-05-26

// Start date only (end_date will be yesterday)
GET /api/public/agent/66a72b17-cb03-4397-ab2a-1eef13847737/usage?start_date=2025-05-20

Response

{
  "agent_id": "66a72b17-cb03-4397-ab2a-1eef13847737",
  "time_range": {
    "start": "2025-05-20T00:00:00.000Z",
    "end": "2025-05-26T23:59:59.999Z"
  },
  "usage": {
    "total_credits_used": 3,
    "daily_breakdown": [
      {
        "date": "2025-05-26",
        "credits_used": 1
      },
      {
        "date": "2025-05-25",
        "credits_used": 0
      },
      {
        "date": "2025-05-24",
        "credits_used": 2
      },
      {
        "date": "2025-05-23",
        "credits_used": 0
      },
      {
        "date": "2025-05-22",
        "credits_used": 0
      },
      {
        "date": "2025-05-21",
        "credits_used": 0
      },
      {
        "date": "2025-05-20",
        "credits_used": 0
      }
    ]
  },
  "note": "Endpoint active from 28 May 2025 onwards"
}

Field	Type	Description
agent_id	string	The agent's unique identifier
time_range	object	Start and end timestamps for the queried period
usage.total_credits_used	number	Total credits consumed in the time period
usage.daily_breakdown	array	Daily credit usage breakdown, sorted by date (newest first)
daily_breakdown[].date	string	Date in YYYY-MM-DD format
daily_breakdown[].credits_used	number	Credits consumed on this specific date
note	string	Optional note about data availability (appears when querying dates before May 28, 2025)

Error Responses

// Missing API Key (401)
{
  "error": "API key is required",
  "message": "Please provide an API key in the Authorization header"
}

// Invalid API Key (401)
{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

// Access Denied (403)
{
  "error": "Access denied",
  "message": "This agent does not belong to your organisation"
}

// Invalid Agent ID (400)
{
  "error": "agent_id is required and must be a non-empty string"
}

// Missing Start Date When End Date Provided (400)
{
  "error": "Invalid date range",
  "message": "start_date is required when end_date is provided (format: YYYY-MM-DD)"
}

// Invalid Date Format (400)
{
  "error": "Invalid date format",
  "message": "Dates must be in YYYY-MM-DD format"
}

// Invalid Dates (400)
{
  "error": "Invalid dates",
  "message": "Provided dates are not valid"
}

// Start Date After End Date (400)
{
  "error": "Invalid date range",
  "message": "start_date must not be after end_date"
}

// End Date Too Recent (400)
{
  "error": "Invalid end date",
  "message": "end_date cannot be today or in the future. Data is only available up to yesterday."
}

// Date Range Too Large (400)
{
  "error": "Date range too large",
  "message": "Date range cannot exceed 31 days"
}

// Internal Server Error (500)
{
  "error": "Internal server error"
}

Notes

Default behavior: Without query parameters, returns the last 7 days ending yesterday (UTC)
Custom date ranges: Use start_date and/or end_date parameters in YYYY-MM-DD format. If only start_date is provided, yesterday is used as end_date
Date range limits: Maximum 31 days, end_date cannot be today or in the future
Data completeness: All days in the range are included, even with 0 usage
Credit counting: Only positive credit transactions (actual usage) are counted
Sort order: Results are sorted by date in descending order (newest first)
Data availability: Usage tracking is only active from May 28, 2025 onwards - dates before this will show 0 usage
Historical data note: A "note" field is included when the queried range includes dates before May 28, 2025

[POST] WhatsApp template

Endpoint

/api/public/agent/:agent_id/waba

Description

Send WhatsApp templates using your agent through the WhatsApp Business API.

Authentication

Requires an API key in the Authorization header.

Authorization: YOUR_API_KEY

Path Parameters

Parameter	Type	Description
agent_id	string	The agent's unique identifier

Request Body

{
  "recipient_phone_number": "31612345678",
  "template_name": "order_update",
  "language": "en_US",
  "customer_name": "John Doe",
  "parameters": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "image",
          "image": {
            "link": "https://whatsapp_image_template"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "ABC123"
        },
        {
          "type": "text",
          "text": "Shipped"
        }
      ]
    }
  ]
}

Parameter	Type	Required	Description
recipient_phone_number	string	Yes	Recipient's phone number with country code
template_name	string	Yes	Name of the WhatsApp template to use
language	string	Yes	Language code (e.g., en_US, en, nl_NL)
customer_name	string	No	Name of the customer (for new customers)
parameters	array	No	Template parameters for dynamic content

For detailed information about formatting template parameters, please refer to the WhatsApp Cloud API documentation.

Example Response

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID"
    }],
  "messages": [{
      "id": "wamid.ID"
    }]
}

Error Responses

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

{
  "error": "Missing required fields",
  "message": "recipient_phone_number and template_name are required"
}

{
  "error": "WhatsApp connection not found",
  "message": "No WhatsApp connection found for this agent"
}

{
  "error": "Internal server error"
}