API Reference

Learn how to integrate FlowGent agents into your application using our REST API.

API Setup

Endpoint

https://api.flowgent.ai/agent

Authorization

Place the api key in the Authorization header.

headers: {
  'Content-Type': 'application/json',
  'Authorization': 'YOUR_API_KEY'
},
Your API key can be created by users with admin access in the app settings page.

[POST] Send a message

The messages object can be populated in 3 ways:

Option 1: Single message string

{
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "messages": "Hello, how are you?"
}

Option 2: Single message object

{
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "messages": {
    "role": "user",
    "content": "Hello, how are you?"
  }
}

Option 3: Array of message objects

{
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "messages": [
    { "role": "user", "content": "Hi there!" },
    { "role": "assistant", "content": "Hello!" }
  ]
}

Optional Parameters:

  • callback_url: For asynchronous processing
  • thread_id: Will continue the same conversation with an agent. The thread_id is returned inside the metadata object from the api response.

Example Body:

{
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "messages": "Hello!",
  "callback_url": "https://your-callback-url.com",
  "thread_id": "123e4567-e89b-12d3-a456-426614174000"
}

Note: Ensure your request body is valid JSON and the agent_id is a non-empty string.

Example Successful Response:

{
  "statusCode": 200,
  "body": {
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "conversation_history": [
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "I will help you perform the task"
          },
          {
            "type": "tool-call",
            "toolCallId": "toolu_01WWRVfGbeCPguMu5X5xhFKt",
            "toolName": "executeTask",
            "args": {
              "task": "The task to perform"
            }
          }
        ],
        "id": "msg-zkuU6LIBHKf3D4xCVzcOac7s"
      },
      {
        "role": "tool",
        "content": [ 
          {
            "type": "tool-result",
            "toolCallId": "toolu_01WWRVfGbeCPguMu5X5xhFKt",
            "toolName": "executeTask",
            "result": {
              "task": "The task to perform"
            }
          }
        ],
        "id": "msg-V24JChAMnqJjoGYPUzb3DEcr"
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "The task was performed successfully"
          }
        ],
        "id": "msg-AwPMIXdBwPJ9rDY55T95pouD"
      }
    ],
    "metadata": {
      "id": "msg_01HMY7a8U4zsR3SHZEC6rEqA",
      "timestamp": "2025-02-19T12:19:25.959Z",
      "tool_calls": [],
      "execution_time": "2.62",
      "used_credits": 2,
      "thread_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

Code Examples

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{"messages": "YOUR_MESSAGE_FOR_THE_AGENT", "agent_id": "123e4567-e89b-12d3-a456-426614174000"}' \
  https://api.flowgent.ai/agent