---
title: "Native API for AI Agents | Hostman Docs"
description: "Integrate AI agents into your applications with the Native API. Discover authentication methods, agent configuration, message requests, conversation continuity, and API response formats with practical code examples."
---

> For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt).

You can interact with AI agents using the Native API.

## Authentication

Each request must include [the API token](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/). 

The token is passed in the following format:

```shell
--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:

```shell
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 Access ID

To interact with an agent, you also need its **Access ID**, which can be found in the agent's **Dashboard** tab.

![7aedefc8 8a23 4372 99b5 4d0f39c9396e](https://content.hostman.com/assets/e3f387f9-c157-431e-9631-68325398cda6.png?width=1560&height=1410)

## Agent Configuration

When using the Native API, the agent uses the settings [defined in the Playground](https://hostman.com/docs/ai-agents/manage-agents/playground/).

## Sending a Message to the Agent

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

**Request**:

```shell
POST /api/v1/cloud-ai/agents/{access_id}/call
```

**cURL:**

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

**Python:**

```py
import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/<access_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:**

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/<access_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**:

```shell
{
  "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](https://hostman.com/docs/ai-agents/manage-agents/playground/#modify-agent-settings), 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.