Native API

You can interact with AI agents using the Native API.

Authentication

If the agent is configured with a private API type, each request must include the API token. For a public API type, no token is required to send requests.

The token is passed in the following format:

--header "authorization: Bearer $TOKEN"

In cURL examples, you can:

• Provide the token manually by replacing $TOKEN with your actual token in each request, or
• Use an environment variable so you don’t have to insert the token every time:

export TOKEN=your_access_token

In this case, the $TOKEN variable will be automatically substituted.

In Python and Node.js examples, the token is specified directly in the code as {{token}}. We recommend storing it in environment variables or configuration files rather than in code to prevent leaks.

Agent ID

To interact with an agent, you also need its ID, which can be found in the Dashboard tab of the agent’s control panel.

Agent Configuration

When using the Native API, the agent uses the settings defined in the Playground.

Sending a Message to the Agent

This method allows you to send a message to the AI agent and receive a response.

Request:

POST /api/v1/cloud-ai/agents/{agent_id}/call

cURL:

curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/<agent_id>/call \
  --header "authorization: Bearer $TOKEN" \
  --header "content-type: application/json" \
  --data '{ "message": "Hello!", "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24" }'

Python:

import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/<agent_id>/call"

payload = {
    "message": "Hi",
    "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}
headers = {
    "content-type": "application/json",
    "authorization": "Bearer {{token}}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Node.js:

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/<agent_id>/call',
  headers: {'content-type': 'application/json', authorization: 'Bearer {{token}}'},
  body: {message: 'Hi', parent_message_id: '3adfea84-bcdb-44b5-8914-92035e75ec24'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Parameters:

• message: the text of the message to the agent
• parent_message_id: optional. The ID of a message to continue a conversation. Can be the last message or any other message ID from the chat

Example Response:

{
  "message": "agent's reply",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}

The id value in the response can be used as parent_message_id in subsequent requests.

The finish_reason field indicates why the response generation ended. Possible values:

• stop: response was fully generated without errors.
• length: response exceeded the maximum token limit, generation was cut off.
• content_filter: a filter from the AI provider (e.g., OpenAI, xAI) triggered, stopping generation. Filters may include content moderation by the provider.
• error: an error occurred during generation. To investigate, contact the support and include the response body.