AssistLoop/Docs
Dashboard
Getting StartedIntegrationsAPI
API Reference

Conversations

Create visitor threads, send messages, and operate the inbox. Visitor send and action-result only work on conversations created through this API (`origin` is `public_api`). List, get, human reply, mode, close, and delete apply to every conversation on the agent, including widget and email threads.

List conversations

Lists the agent's conversations (public API, widget, and email), newest first.

Scope: conversation:read · Rate limit: Read (120/min)

GET/agents/{agent}/conversations

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid

Query Parameters

status?string

Filter by open or closed.

Value in"open" | "closed"
response_mode?string

Filter by ai or human.

Value in"ai" | "human"
page?integer

Page number.

Default1
Range1 <= value
per_page?integer

Items per page.

Default25
Range1 <= value <= 100

Response Body

curl -X GET "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations?status=open&response_mode=ai&page=1&per_page=25"
{
  "data": [
    {
      "id": "3f1a9c2e-8b4d-4e6a-9c1f-2a3b4c5d6e7f",
      "session_id": "7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "origin": "public_api",
      "status": "open",
      "response_mode": "ai",
      "chat_user": {
        "id": "user-123",
        "name": null,
        "email": null,
        "identity_verified": false
      },
      "created_at": "2026-09-05T10:15:30.000000Z",
      "updated_at": "2026-09-05T10:15:30.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1,
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  },
  "links": {
    "first": "https://api.assistloop.ai/api/public/v1/agents/AGENT/conversations?page=1",
    "last": "https://api.assistloop.ai/api/public/v1/agents/AGENT/conversations?page=1",
    "prev": null,
    "next": null
  }
}
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "The content field is required.",
    "details": [
      {
        "field": "content",
        "message": "The content field is required."
      }
    ]
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Create a conversation

Creates an open conversation with origin set to public_api. response_mode is human when the agent is human-only, otherwise ai. When the agent is not human-only, an assistant greeting is stored and does not consume message credits.

If this chat_user_id already has an open public API conversation on this agent, the request returns 409 conversation_conflict with that conversation id. Open widget or email threads do not count. Omitting chat_user_id mints a new visitor, so 409 does not apply.

Scope: conversation:create · Rate limit: Write (60/min)

POST/agents/{agent}/conversations

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid

Request Body

chat_user_id?string

Optional visitor identifier, unique per agent. Omit to mint a new visitor UUID.

Lengthlength <= 255
identity_token?string

Optional HS256 JWT signed with the agent's identity secret (aud = agent UUID) — the same token the widget uses. Required when the agent's identity mode is required.

Response Body

curl -X POST "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations" \  -H "Content-Type: application/json" \  -d '{    "chat_user_id": "user-123"  }'
{
  "data": {
    "id": "3f1a9c2e-8b4d-4e6a-9c1f-2a3b4c5d6e7f",
    "session_id": "7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "origin": "public_api",
    "status": "open",
    "response_mode": "ai",
    "chat_user": {
      "id": "user-123",
      "name": null,
      "email": null,
      "identity_verified": false
    },
    "created_at": "2026-09-05T10:15:30.000000Z",
    "updated_at": "2026-09-05T10:15:30.000000Z"
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "conversation_conflict",
    "message": "An open public API conversation already exists for this visitor.",
    "details": [
      {
        "field": "chat_user_id",
        "conversation_id": "3f1a9c2e-8b4d-4e6a-9c1f-2a3b4c5d6e7f"
      }
    ]
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "The content field is required.",
    "details": [
      {
        "field": "content",
        "message": "The content field is required."
      }
    ]
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "agent_unavailable",
    "message": "Agent is currently disabled.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Retrieve a conversation

Returns any conversation that belongs to the agent, including widget and email threads. A UUID that belongs to another agent returns 404 resource_not_found.

Scope: conversation:read · Rate limit: Read (120/min)

GET/agents/{agent}/conversations/{conversation}

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid
conversationstring

The conversation UUID.

Formatuuid

Response Body

curl -X GET "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
    "origin": "string",
    "status": "open",
    "response_mode": "ai",
    "chat_user": {
      "id": "string",
      "name": "string",
      "email": "string",
      "identity_verified": true
    },
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "266ea41d-adf5-480b-af50-15b940c2b846"
  }
}
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "resource_not_found",
    "message": "Source not found.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Update a conversation

Partial update. Send status, response_mode, or both. Works on widget and email threads as well as public API threads. Changing mode on an already-closed conversation returns 422 conversation_closed unless you also reopen it (status: open) in the same request. Mode is applied before close, so one PATCH can set mode and close.

Scope: conversation:edit · Rate limit: Write (60/min)

PATCH/agents/{agent}/conversations/{conversation}

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid
conversationstring

The conversation UUID.

Formatuuid

Request Body

status?string
Value in"open" | "closed"
response_mode?string
Value in"ai" | "human"

Response Body

curl -X PATCH "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "status": "closed"  }'
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
    "origin": "string",
    "status": "open",
    "response_mode": "ai",
    "chat_user": {
      "id": "string",
      "name": "string",
      "email": "string",
      "identity_verified": true
    },
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "266ea41d-adf5-480b-af50-15b940c2b846"
  }
}
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "resource_not_found",
    "message": "Source not found.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

{
  "error": {
    "code": "conversation_closed",
    "message": "This conversation is closed.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

{
  "error": {
    "code": "agent_unavailable",
    "message": "Agent is currently disabled.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Delete a conversation

Soft-deletes the conversation and its messages. Allowed for widget and email threads as well as public API threads.

Scope: conversation:delete · Rate limit: Write (60/min)

DELETE/agents/{agent}/conversations/{conversation}

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid
conversationstring

The conversation UUID.

Formatuuid

Response Body

curl -X DELETE "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08"
Empty
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "resource_not_found",
    "message": "Source not found.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

List messages

Lists messages oldest first. Works for any conversation on the agent. Metered under the polling limit so you can poll after a visitor send. The assistant reply is asynchronous — poll again, or wait for the webhook, before treating it as stored.

Scope: conversation:read · Rate limit: Polling (200/min)

GET/agents/{agent}/conversations/{conversation}/messages

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid
conversationstring

The conversation UUID.

Formatuuid

Query Parameters

page?integer

Page number.

Default1
Range1 <= value
per_page?integer

Items per page.

Default25
Range1 <= value <= 100

Response Body

curl -X GET "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages?page=1&per_page=25"
{
  "data": [
    {
      "id": "9e8d7c6b-5a4f-4302-91b0-1c2d3e4f5a6b",
      "content": "Hello! How can I help you today?",
      "role": "assistant",
      "action_required": false,
      "action": null,
      "created_at": "2026-09-05T10:15:30.000000Z"
    },
    {
      "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071",
      "content": "Hello from the API",
      "role": "visitor",
      "action_required": false,
      "action": null,
      "created_at": "2026-09-05T10:16:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 2,
    "last_page": 1,
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  },
  "links": {
    "first": "https://api.assistloop.ai/api/public/v1/agents/AGENT/conversations/CONVERSATION/messages?page=1",
    "last": "https://api.assistloop.ai/api/public/v1/agents/AGENT/conversations/CONVERSATION/messages?page=1",
    "prev": null,
    "next": null
  }
}
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "resource_not_found",
    "message": "Source not found.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Send a visitor message

Sends visitor text on an open public API conversation. Returns the visitor message. The AI reply is not in this response — poll messages or handle the public_api_message_created webhook.

Widget or email threads return 404 resource_not_found. Closed conversations return 422 conversation_closed. Attachments are not supported.

When the send will dispatch AI, the organization's message credit cap is enforced. Over cap returns 422 subscription_limit_exceeded. Human-mode, human-only, and bring-your-own-key agents skip that cap.

Scope: conversation:create · Rate limit: Write (60/min)

POST/agents/{agent}/conversations/{conversation}/messages

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid
conversationstring

The conversation UUID.

Formatuuid

Request Body

contentstring

Visitor text. Attachments are not supported.

Lengthlength <= 10000

Response Body

curl -X POST "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages" \  -H "Content-Type: application/json" \  -d '{    "content": "Hello from the API"  }'
{
  "data": {
    "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071",
    "content": "Hello from the API",
    "role": "visitor",
    "action_required": false,
    "action": null,
    "created_at": "2026-09-05T10:16:00.000000Z"
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "resource_not_found",
    "message": "Source not found.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

{
  "error": {
    "code": "conversation_closed",
    "message": "This conversation is closed.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

{
  "error": {
    "code": "agent_unavailable",
    "message": "Agent is currently disabled.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Send a human reply

Posts a human-assistant message as the API key owner and sets response_mode to human. Allowed on widget and email threads as well as public API threads.

Scope: conversation:edit · Rate limit: Write (60/min)

POST/agents/{agent}/conversations/{conversation}/human-messages

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid
conversationstring

The conversation UUID.

Formatuuid

Request Body

contentstring

Reply text. Attachments are not supported.

Lengthlength <= 10000

Response Body

curl -X POST "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08/human-messages" \  -H "Content-Type: application/json" \  -d '{    "content": "We will help you."  }'
{
  "data": {
    "id": "b2c3d4e5-f6a7-4819-8b2c-3d4e5f607182",
    "content": "We will help you.",
    "role": "human",
    "action_required": false,
    "action": null,
    "created_at": "2026-09-05T10:18:00.000000Z"
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "resource_not_found",
    "message": "Source not found.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "The content field is required.",
    "details": [
      {
        "field": "content",
        "message": "The content field is required."
      }
    ]
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "agent_unavailable",
    "message": "Agent is currently disabled.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Submit an action result

Completes a pending tool call (for example lead collection) and continues the agent chat. Only public API conversations are accepted; widget or email threads return 404. Use the assistant message UUID where action_required is true — from list messages or the public_api_message_created webhook.

Scope: conversation:create · Rate limit: Write (60/min)

POST/agents/{agent}/conversations/{conversation}/messages/{message}/action-result

Authorization

AuthorizationBearer <token>

Bearer API key. Create one in your dashboard (Settings → API Keys); the full value is shown only once. Requires the organization owner on a premium or active AppSumo plan.

In: header

Path Parameters

agentstring

The agent's UUID.

Formatuuid
conversationstring

The conversation UUID.

Formatuuid
messagestring

The message UUID. Must belong to the conversation in the path.

Formatuuid

Request Body

actionstring

Action slug (for example collect_lead). action_slug or action_name may be sent as aliases; action is still required.

resultarray<object>

Array of field maps, for example name and email objects.

agent_action_uuid?string

Optional action UUID when the slug is ambiguous.

Response Body

curl -X POST "https://api.assistloop.ai/api/public/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages/497f6eca-6276-4993-bfeb-53cbbbba6f08/action-result" \  -H "Content-Type: application/json" \  -d '{    "action": "collect_lead",    "result": [      {        "name": "Jane Doe"      },      {        "email": "jane@example.com"      }    ]  }'

{
  "data": [
    {
      "name": "Jane Doe"
    },
    {
      "email": "jane@example.com"
    }
  ],
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

{
  "message": "Unauthenticated."
}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: source:create",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "resource_not_found",
    "message": "Source not found.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "The content field is required.",
    "details": [
      {
        "field": "content",
        "message": "The content field is required."
      }
    ]
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "error": {
    "code": "agent_unavailable",
    "message": "Agent is currently disabled.",
    "details": []
  },
  "meta": {
    "request_id": "b7f0b9c2-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Agents

Create, read, update, and delete AI agents.

Webhooks

Subscribe to AI replies, human replies, and human handoff on public API threads.