Send Message to Agent

Send a single message to an agent and receive a complete response. This is the simplest way to interact with an agent programmatically.

Endpoint

POST /api/v1/agents/basic/{agentId}

Authentication

This endpoint requires API key authentication. Include your API key in the Authorization header using the Bearer scheme.

Header Format:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Request

Path Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The unique identifier of the agent

Headers

Header	Type	Required	Description
Authorization	string	Yes	Your API key in the format Bearer pk_xxx:sk_xxx
Content-Type	string	Yes	Must be application/json

Request Body

Field	Type	Required	Description
message	string	Yes	The message to send to the agent
identifier	string	Yes	A unique identifier for the external user (used for conversation tracking)

Example Request Body:

{
  "message": "What are your business hours?",
  "identifier": "user-123"
}

Response

Success Response

Status Code: 200 OK

Response Body:

{
  "success": true,
  "response": "Our business hours are Monday to Friday, 9 AM to 6 PM EST. We're also available on Saturday from 10 AM to 2 PM."
}

If the agent returns structured JSON data, the response will be automatically parsed:

{
  "success": true,
  "response": {
    "hours": {
      "weekdays": "9 AM - 6 PM EST",
      "saturday": "10 AM - 2 PM EST",
      "sunday": "Closed"
    }
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
response	string | object	The agent's response (string or parsed JSON object)

Error Responses

400 Bad Request

{
  "error": "Message and identifier are required"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

402 Payment Required

No active subscription:

{
  "error": "No active subscription found"
}

No credits remaining:

{
  "error": "No credits remaining"
}

404 Not Found

{
  "error": "Agent not found or unauthorized"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Example Usage

cURL

curl -X POST https://agentsgt.com/api/v1/agents/basic/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "identifier": "user-123"
  }'

JavaScript (Fetch API)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

fetch(`https://agentsgt.com/api/v1/agents/basic/${agentId}`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'What are your business hours?',
    identifier: 'user-123'
  })
})
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('Agent says:', data.response);
    } else {
      console.error('Error:', data.error);
    }
  })
  .catch(error => {
    console.error('Error:', error);
  });

Python (Requests)

import requests

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
agent_id = '550e8400-e29b-41d4-a716-446655440000'

headers = {
    'Authorization': f'Bearer {public_key}:{secret_key}',
    'Content-Type': 'application/json'
}

response = requests.post(
    f'https://agentsgt.com/api/v1/agents/basic/{agent_id}',
    headers=headers,
    json={
        'message': 'What are your business hours?',
        'identifier': 'user-123'
    }
)

if response.status_code == 200:
    data = response.json()
    print(f"Agent says: {data['response']}")
else:
    print(f"Error: {response.status_code} - {response.json()}")

Node.js (Axios)

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

axios.post(`https://agentsgt.com/api/v1/agents/basic/${agentId}`, {
  message: 'What are your business hours?',
  identifier: 'user-123'
}, {
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    console.log('Agent says:', response.data.response);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Notes

• The identifier field is used to track conversations per user. Use a consistent identifier for the same user to maintain conversation context
• This endpoint returns the complete response at once (not streamed). For streaming responses, use the Chat endpoint instead
• If the agent returns JSON wrapped in markdown code blocks, it will be automatically parsed into a JSON object
• Each message consumes credits based on the agent's model and token usage
• The agent must have an active subscription with available credits

Related Endpoints

• Chat - Streaming chat endpoint for real-time responses
• Get Agent Details - Get information about an agent
• Check Balance - Check available credits before sending messages