API Usage

Last updated February 20, 2026

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
Copy link

OpenAI-compatible API
Copy link

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
Copy link

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
Copy link

Feature

OpenAI-compatible API

Native API

Request format

messages[] array

message field with parentMessageId

Message history

Not stored, passed in request

Stored between requests (using parentMessageId)

Streaming responses

Supported (stream: true)

Not supported

Multimodality

Partially supported

Text only

Usage info

Available (usage, model)

Not available

Response format

choices, usage, model, id

message, id, response_id

Which API to Choose
Copy link

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