Agent
REST reference

Agent API

Talk to and configure the AI agent (the API channel).

View as Markdown

Send a message to the AI agent

POST/v1/agent/messages

Synchronous turn against the AI agent over the API channel. Omit conversation_id to start a new conversation. Consumes AI credits (essential=1, pro=4, ultra=8) only when a reply is produced.

Required scope: agent:chat. Subject to the chat rate-limit tier (20/60s).

Request body
messagestringrequired

The customer's message.

conversation_idstring

Continue an existing API-channel conversation. Omit to start a new one.

customerobject

Identifying info used to create or match a customer.

attachmentsarray of object

Optional attachments passed to the agent.

Request
cURL
curl -X POST "https://api.asks.app/v1/agent/messages" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "string",
    "conversation_id": "string",
    "customer": {
      "email": "customer@example.com",
      "phone": "string",
      "name": "string",
      "external_id": "string"
    },
    "attachments": [
      {}
    ]
  }'
Response 200
JSON
{
  "object": "agent_response",
  "conversation_id": "string",
  "messages": [
    "string"
  ],
  "quick_replies": [
    "string"
  ],
  "buttons": [
    {
      "text": "string",
      "url": "string"
    }
  ],
  "images": [
    "string"
  ],
  "sources": [
    "string"
  ],
  "escalated": true,
  "credits_used": 1,
  "model_tier": "essential"
}

Get agent configuration

GET/v1/agent

Returns the AI agent configuration. If none is configured, a disabled default is returned (never 404).

Required scope: agent:read.

Request
cURL
curl "https://api.asks.app/v1/agent" \
  -H "Authorization: Bearer $ASKS_API_KEY"
Response 200
JSON
{
  "object": "agent",
  "name": "string",
  "avatar_url": {},
  "is_enabled": true,
  "tone": "professional",
  "response_length": "concise",
  "custom_instructions": {},
  "model_tier": "essential",
  "escalation": {
    "enabled": true,
    "keywords": [
      "string"
    ],
    "after_replies": {}
  },
  "deployed_channels": {}
}

Update agent configuration

PATCH/v1/agent

Updates (and upserts) the agent configuration. Only provided fields change; deployed_channels is shallow-merged.

Required scope: agent:write.

Request body
namestring
is_enabledboolean
tonestring

One of: professional, friendly, casual.

response_lengthstring

One of: concise, balanced, detailed.

custom_instructionsstringnull
model_tierstring

One of: essential, pro, ultra.

escalationobject
deployed_channelsobject
Request
cURL
curl -X PATCH "https://api.asks.app/v1/agent" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "is_enabled": true,
    "tone": "professional",
    "response_length": "concise",
    "custom_instructions": {},
    "model_tier": "essential",
    "escalation": {
      "enabled": true,
      "keywords": [
        "string"
      ],
      "after_replies": {}
    },
    "deployed_channels": {}
  }'
Response 200
JSON
{
  "object": "agent",
  "name": "string",
  "avatar_url": {},
  "is_enabled": true,
  "tone": "professional",
  "response_length": "concise",
  "custom_instructions": {},
  "model_tier": "essential",
  "escalation": {
    "enabled": true,
    "keywords": [
      "string"
    ],
    "after_replies": {}
  },
  "deployed_channels": {}
}

Search the knowledge base

POST/v1/agent/search

Semantic search over AI-enabled, published knowledge base content only. Returns an unpaginated list.

Required scope: agent:read.

Request body
querystringrequired
top_kinteger
Request
cURL
curl -X POST "https://api.asks.app/v1/agent/search" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "string",
    "top_k": 8
  }'
Response 200
JSON
{
  "object": "list",
  "data": [
    {
      "object": "knowledge_result",
      "knowledge_base_id": {},
      "filename": {},
      "text": {}
    }
  ],
  "has_more": true,
  "next_cursor": {}
}
← Previous
Widget developer guide
Next →
Conversations