Agents

The Agents API allows you to create, manage, and interact with Smart Agents programmatically.

List Agents

Retrieve a list of all agents accessible to the authenticated user.

GET /v1/agents

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of agents per page (max 100)
`cursor`	string	—	Pagination cursor
`category`	string	—	Filter by category
`status`	string	—	Filter by status: `active`, `inactive`, `draft`
`search`	string	—	Search agents by name or description

Example Request

curl -X GET "https://api.agent.net.ai/v1/agents?status=active&limit=10" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": [
    {
      "id": "agent_01H8X3Y4Z5",
      "name": "Financial Reporter",
      "description": "Generates financial reports from GL data",
      "category": "Finance",
      "status": "active",
      "model": "Smart",
      "created_at": "2026-03-15T09:00:00Z",
      "updated_at": "2026-04-01T14:30:00Z"
    },
    {
      "id": "agent_01H8X3Y4Z6",
      "name": "Inventory Tracker",
      "description": "Monitors stock levels and suggests reorders",
      "category": "Inventory",
      "status": "active",
      "model": "Fast",
      "created_at": "2026-03-20T11:00:00Z",
      "updated_at": "2026-03-20T11:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "next_cursor": "eyJpZCI6MTJ9",
    "request_id": "req_abc123"
  }
}

Get Agent

Retrieve details for a specific agent.

GET /v1/agents/{agent_id}

Path Parameters

Parameter	Type	Description
`agent_id`	string	The unique agent identifier

Example Request

curl -X GET "https://api.agent.net.ai/v1/agents/agent_01H8X3Y4Z5" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": {
    "id": "agent_01H8X3Y4Z5",
    "name": "Financial Reporter",
    "description": "Generates financial reports from GL data",
    "category": "Finance",
    "status": "active",
    "model": "Smart",
    "system_prompt": "You are a financial reporting assistant...",
    "data_scope": {
      "tables": ["G/L Entry", "Customer", "Vendor"],
      "read_only": true
    },
    "output_preferences": {
      "default_format": "table",
      "chart_enabled": true
    },
    "welcome_message": "Hello! I can help you with financial reports.",
    "suggested_prompts": [
      "Show me aged receivables over 90 days",
      "What is the cash flow forecast for next month?"
    ],
    "created_at": "2026-03-15T09:00:00Z",
    "updated_at": "2026-04-01T14:30:00Z",
    "created_by": "user_abc123"
  }
}

Create Agent

Create a new custom agent.

POST /v1/agents

Required scope: agents:write

Request Body

Field	Type	Required	Description
`name`	string	Yes	Agent display name (max 100 characters)
`system_prompt`	string	Yes	Instructions for the AI model
`data_scope`	object	Yes	Tables and fields the agent can access
`description`	string	No	Brief description
`category`	string	No	Category for organization
`model`	string	No	Model tier: `Fast`, `Smart`, `Expert`, `Premium` (default: `Fast`)
`welcome_message`	string	No	Initial message shown to users
`suggested_prompts`	string[]	No	Pre-written prompts (max 5)
`output_preferences`	object	No	Default output format settings

Example Request

curl -X POST https://api.agent.net.ai/v1/agents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Pipeline Analyzer",
    "description": "Analyzes sales pipeline and forecasts revenue",
    "category": "Sales",
    "model": "Smart",
    "system_prompt": "You are a sales analytics assistant. Focus on pipeline stages, conversion rates, and revenue forecasting. Always present data in tables with clear column headers.",
    "data_scope": {
      "tables": ["Sales Header", "Sales Line", "Customer", "Opportunity"],
      "read_only": true
    },
    "welcome_message": "Hello! I can help you analyze your sales pipeline.",
    "suggested_prompts": [
      "Show me the current sales pipeline by stage",
      "What is the win rate for deals over $10,000?"
    ]
  }'

Example Response

{
  "data": {
    "id": "agent_01H8X3Y4Z7",
    "name": "Sales Pipeline Analyzer",
    "status": "draft",
    "created_at": "2026-04-12T10:00:00Z"
  }
}

Status code: 201 Created

Update Agent

Update an existing agent's configuration.

PATCH /v1/agents/{agent_id}

Required scope: agents:write

Request Body

Include only the fields you want to update. All fields from the create endpoint are accepted.

Example Request

curl -X PATCH "https://api.agent.net.ai/v1/agents/agent_01H8X3Y4Z7" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "model": "Premium"
  }'

Example Response

{
  "data": {
    "id": "agent_01H8X3Y4Z7",
    "name": "Sales Pipeline Analyzer",
    "status": "active",
    "model": "Premium",
    "updated_at": "2026-04-12T10:15:00Z"
  }
}

Delete Agent

Delete an agent. This action is irreversible.

DELETE /v1/agents/{agent_id}

Required scope: agents:write

Example Request

curl -X DELETE "https://api.agent.net.ai/v1/agents/agent_01H8X3Y4Z7" \
  -H "Authorization: Bearer <token>"

Status code: 204 No Content

Send Message

Send a message to an agent and receive a response.

POST /v1/agents/{agent_id}/messages

Required scope: agents:chat

Request Body

Field	Type	Required	Description
`message`	string	Yes	The user's message text
`conversation_id`	string	No	Existing conversation ID to continue a thread
`context`	object	No	Additional context (e.g., current page, selected record)

Example Request

curl -X POST "https://api.agent.net.ai/v1/agents/agent_01H8X3Y4Z5/messages" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Show me aged receivables over 90 days",
    "conversation_id": "conv_xyz789"
  }'

Example Response

{
  "data": {
    "id": "msg_01H8X3Y4Z8",
    "conversation_id": "conv_xyz789",
    "role": "assistant",
    "content": "Here are the aged receivables over 90 days:\n\n| Customer | Amount | Days Outstanding |\n|----------|--------|------------------|\n| Contoso Ltd | $15,230.00 | 105 |\n| Fabrikam Inc | $8,450.00 | 97 |\n| Northwind Traders | $3,200.00 | 92 |",
    "content_type": "markdown",
    "credits_consumed": 3,
    "model_used": "Smart",
    "created_at": "2026-04-12T10:20:00Z"
  }
}

List Conversations

Retrieve conversations for the authenticated user.

GET /v1/agents/{agent_id}/conversations

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of conversations per page
`cursor`	string	—	Pagination cursor

Example Request

curl -X GET "https://api.agent.net.ai/v1/agents/agent_01H8X3Y4Z5/conversations?limit=5" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": [
    {
      "id": "conv_xyz789",
      "agent_id": "agent_01H8X3Y4Z5",
      "message_count": 8,
      "total_credits": 18,
      "created_at": "2026-04-10T09:00:00Z",
      "last_message_at": "2026-04-12T10:20:00Z"
    }
  ],
  "meta": {
    "total": 23,
    "next_cursor": "eyJpZCI6MjN9"
  }
}

On this page