API Usage

We support two types of API for AI agents:

• OpenAI-compatible API: suitable for integration with external libraries and UIs, using the standard request structure.

• Native API: simpler and easier to use, especially when a quick result is needed without external dependencies.

Example Requests

OpenAI-compatible API

Example request:

POST https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "temperature": 1,
  "max_tokens": 100,
  "stream": false
}

Example response:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hi! How can I help you?"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 14,
    "total_tokens": 26
  }
}

Native API

Example request: 

POST https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/call
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "message": "Hello",
  "parentmessageid": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}

Example response:

{
  "message": "Hi! How can I help you?",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}

Key Differences

Which API to Choose

Use the OpenAI-compatible API if you:

• Want to integrate the agent with external libraries (e.g., LangChain, Open WebUI)
• Already use OpenAI and want to simply replace the URL
• Need usage statistics (tokens, model)
• Require streaming responses
• Plan to use multimodal messages

Use the Native API if you:

• Need built-in message history without explicitly passing context
• Are building a simple app with minimal external dependencies
• Want responses in a simple format
• Need fast and lightweight integration, for example, for an MVP