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

ParameterTypeDescription
agent_idstringThe 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
}
ParameterTypeRequiredDescription
messagesstring | object | arrayYesCan be a string, a message object, or an array of message objects
thread_idstringNoOptional thread ID for continuing a conversation
callback_urlstringNoURL 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

ParameterTypeDescription
agent_idstringThe 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.

ParameterTypeRequiredDescription
start_datestringNo*Start date for the query range in YYYY-MM-DD format
end_datestringNo*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"
}
FieldTypeDescription
agent_idstringThe agent's unique identifier
time_rangeobjectStart and end timestamps for the queried period
usage.total_credits_usednumberTotal credits consumed in the time period
usage.daily_breakdownarrayDaily credit usage breakdown, sorted by date (newest first)
daily_breakdown[].datestringDate in YYYY-MM-DD format
daily_breakdown[].credits_usednumberCredits consumed on this specific date
notestringOptional 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

ParameterTypeDescription
agent_idstringThe 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"
        }
      ]
    }
  ]
}
ParameterTypeRequiredDescription
recipient_phone_numberstringYesRecipient's phone number with country code
template_namestringYesName of the WhatsApp template to use
languagestringYesLanguage code (e.g., en_US, en, nl_NL)
customer_namestringNoName of the customer (for new customers)
parametersarrayNoTemplate 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"
}