Agents API — Create, Update, and Chat with Agents

The Agents API lets you create, configure, and interact with AI agents entirely through code. Each agent is connected to one or more knowledge bases and responds to user messages by retrieving relevant content and generating natural-language replies. Use these endpoints to build custom chat interfaces, integrate agents into your product, or automate agent configuration as part of your deployment pipeline.

POST /v1/agents

Create a new AI agent and connect it to one or more knowledge bases. Once created, the agent is immediately available to receive chat messages.

Request Body

string

required

A descriptive name for the agent. This name appears in the dashboard and in API responses.

array

required

An array of knowledge base IDs that this agent will search when generating replies. Provide at least one ID. For example: ["kb_abc123", "kb_def456"].

string

The message the agent sends when a user starts a new conversation session. Leave blank to skip an opening message.

string

The message the agent sends when it cannot find a relevant answer in the knowledge base. Defaults to a generic “I don’t know” response if not set.

string

Persona and behavior instructions that shape how the agent responds. Use this to define tone, role, and any constraints you want to enforce.

string

default:"medium"

Controls the verbosity of agent replies. One of short, medium, or detailed.

Example Request

curl -X POST https://api.beenossolutions.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "knowledge_base_ids": ["kb_abc123"],
    "welcome_message": "Hi! Ask me anything about our products.",
    "system_prompt": "You are a helpful support agent. Be concise and friendly.",
    "response_length": "medium"
  }'

Response

string

The unique identifier for this agent (for example, agt_abc123). Use this ID in all subsequent requests targeting this agent.

string

The name you assigned to the agent.

string

The agent’s operational status. active agents accept chat messages. inactive agents are paused and will return a 403 response to chat requests.

string

ISO 8601 timestamp indicating when the agent was created.

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

GET /v1/agents/:id

Retrieve the full configuration and status of an existing agent.

Path Parameter

string

required

The unique ID of the agent to retrieve (for example, agt_abc123).

Example Request

curl https://api.beenossolutions.com/v1/agents/agt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

string

The unique identifier for this agent (for example, agt_abc123).

string

The name assigned to this agent.

string

The agent’s operational status: active or inactive.

array

The list of knowledge base IDs connected to this agent.

string

The message the agent sends at the start of a new conversation, if configured.

string

The message the agent sends when it cannot find a relevant answer in the knowledge base.

string

The persona and behavior instructions configured for this agent.

string

The configured verbosity setting for agent replies: short, medium, or detailed.

string

ISO 8601 timestamp indicating when the agent was created.

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "status": "active",
    "knowledge_base_ids": ["kb_abc123"],
    "welcome_message": "Hi! Ask me anything about our products.",
    "fallback_message": "I'm sorry, I don't have an answer for that.",
    "system_prompt": "You are a helpful support agent. Be concise and friendly.",
    "response_length": "medium",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

PATCH /v1/agents/:id

Update the configuration of an existing agent. Send only the fields you want to change — all other fields remain unchanged. You can use this endpoint to rename an agent, swap its knowledge bases, update its system prompt, or change any other setting defined in POST /v1/agents.

Path Parameter

string

required

The unique ID of the agent to update.

Request Body

All fields are optional. Include only the fields you want to change — unspecified fields remain unchanged.

string

A new descriptive name for the agent.

array

A replacement array of knowledge base IDs for the agent to search. This replaces the existing list entirely.

string

A new opening message for new conversation sessions.

string

A new fallback message to send when the agent cannot find a relevant answer.

string

Updated persona and behavior instructions for the agent.

string

Updated verbosity setting. One of short, medium, or detailed.

Example Request

curl -X PATCH https://api.beenossolutions.com/v1/agents/agt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "welcome_message": "Hello! How can I help you today?",
    "response_length": "detailed"
  }'

Response

Returns the full updated agent object. The response shape is identical to GET /v1/agents/:id.

string

The unique identifier for this agent.

string

The current name of the agent after the update.

string

The agent’s current operational status: active or inactive.

array

The current list of knowledge base IDs connected to this agent.

string

ISO 8601 timestamp indicating when the agent was last updated.

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "status": "active",
    "knowledge_base_ids": ["kb_abc123"],
    "welcome_message": "Hello! How can I help you today?",
    "fallback_message": "I'm sorry, I don't have an answer for that.",
    "system_prompt": "You are a helpful support agent. Be concise and friendly.",
    "response_length": "detailed",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T09:00:00Z"
  },
  "meta": {
    "request_id": "req_ghi789",
    "timestamp": "2024-01-16T09:00:00Z"
  }
}

POST /v1/agents/:id/chat

Send a message to an agent and receive a generated reply. The agent searches its connected knowledge bases for relevant content and returns a grounded response along with the source documents it used.

Path Parameter

string

required

The unique ID of the agent to send the message to.

Request Body

string

required

The user’s message or question. Plain natural language works best.

string

A unique identifier for the conversation session. Providing a consistent session_id across multiple turns enables the agent to maintain conversational context. We strongly recommend always supplying this value. If you omit it, each request is treated as a standalone, context-free message.

Example Request

curl -X POST https://api.beenossolutions.com/v1/agents/agt_abc123/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the return policy?",
    "session_id": "user-session-42"
  }'

Response

string

The agent’s generated response to the user’s message.

array

The list of knowledge base source documents the agent used when generating its reply. Each item in the array contains:

Show Source object fields

string

The unique ID of the source document.

string

The human-readable name of the source document.

string

The specific text excerpt from the source that was most relevant to the query.

string

The session identifier for this conversation turn. Matches the value you provided in the request, or a newly generated ID if you did not supply one.

number

A relevance score between 0.0 and 1.0 indicating how confident the agent is in its answer based on the retrieved content. Scores below 0.5 suggest the knowledge base may not contain enough information to answer the question well.

{
  "data": {
    "reply": "You can return any item within 30 days of purchase for a full refund...",
    "sources": [
      {
        "id": "src_xyz789",
        "name": "Return Policy",
        "snippet": "Items may be returned within 30 days of purchase..."
      }
    ],
    "session_id": "user-session-42",
    "confidence": 0.94
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-15T10:32:00Z"
  }
}

Store the session_id on the client side and pass it with every subsequent message in the same conversation. This allows the agent to reference earlier messages, making multi-turn conversations significantly more coherent.

GET /v1/agents/:id/conversations

List all conversation sessions for an agent, ordered by most recent activity. Use this endpoint to build conversation history views or audit chat logs.

Path Parameter

string

required

The unique ID of the agent whose conversations you want to retrieve.

Query Parameters

integer

default:"20"

The number of conversation sessions to return per page. Maximum 100.

string

A pagination cursor from a previous response’s next_cursor field.

string

Filter results to a specific conversation session by its ID.

Example Request

curl "https://api.beenossolutions.com/v1/agents/agt_abc123/conversations?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

array

A paginated array of conversation session objects, ordered by most recent activity first.

Show Conversation object fields

string

The unique identifier for this conversation session.

integer

The total number of messages exchanged in this session.

string

ISO 8601 timestamp indicating when the first message in this session was sent.

string

ISO 8601 timestamp indicating when the most recent message in this session was sent.

string

A pagination cursor to pass as the cursor query parameter in your next request to retrieve the following page. Absent when you have reached the last page.

{
  "data": [
    {
      "session_id": "user-session-42",
      "message_count": 7,
      "started_at": "2024-01-15T10:30:00Z",
      "last_activity_at": "2024-01-15T10:45:00Z"
    },
    {
      "session_id": "user-session-41",
      "message_count": 3,
      "started_at": "2024-01-14T14:00:00Z",
      "last_activity_at": "2024-01-14T14:05:00Z"
    }
  ],
  "meta": {
    "request_id": "req_jkl012",
    "timestamp": "2024-01-15T11:00:00Z",
    "next_cursor": "cur_mno345"
  }
}

Overview

Endpoints

Agents API — Create, Update, and Chat with Agents

POST /v1/agents

Request Body

Example Request

Response

GET /v1/agents/:id

Path Parameter

Example Request

Response

PATCH /v1/agents/:id

Path Parameter

Request Body

Example Request

Response

POST /v1/agents/:id/chat

Path Parameter

Request Body

Example Request

Response

GET /v1/agents/:id/conversations

Path Parameter

Query Parameters

Example Request

Response

​POST /v1/agents

​Request Body

​Example Request

​Response

​GET /v1/agents/:id

​Path Parameter

​Example Request

​Response

​PATCH /v1/agents/:id

​Path Parameter

​Request Body

​Example Request

​Response

​POST /v1/agents/:id/chat

​Path Parameter

​Request Body

​Example Request

​Response

​GET /v1/agents/:id/conversations

​Path Parameter

​Query Parameters

​Example Request

​Response

POST /v1/agents

Request Body

Example Request

Response

GET /v1/agents/:id

Path Parameter

Example Request

Response

PATCH /v1/agents/:id

Path Parameter

Request Body

Example Request

Response

POST /v1/agents/:id/chat

Path Parameter

Request Body

Example Request

Response

GET /v1/agents/:id/conversations

Path Parameter

Query Parameters

Example Request

Response