API Reference

1. Initialize a session

1. Create Session

This endpoint initializes a new agent session and begins the agent’s tasks.

Request Method:

• POST

Request URL:

POST https://api.assisfy.ai/api/v1sessions

Request Headers:

Header	Description	Type	Required
Authorization	API Key for Assisfy account	Bearer <API_KEY>	Yes
Content-Type	Application/json	application/json	Yes

Request Body:

Parameter	Type	Description	Required	Example
start_url	string	The URL where the agent’s task starts	Yes	https://example.com
max_actions	number	Maximum number of actions the agent can perform	Yes	10
goal	string	The goal for the agent's session	Yes	Research competitor pricing

Response:

Field	Type	Description
session_id	string	Unique identifier for the session
status	string	Current status of the session (e.g., started, in_progress, complete)
start_time	string	Timestamp when the session started
end_time	string	Timestamp when the session ended (if applicable)
error	string	Error message (if any)

2. Communication Channel: WebSocket

The Assisfy SDK uses WebSocket to send and receive real-time events for session management, agent interactions, and external resource requests. Developers will establish a WebSocket connection to communicate with the Assisfy service.

WebSocket Connection Setup

To establish a connection, you need to provide the following parameters:

• API Key: Your Assisfy API key.

• Session ID: A unique identifier for the agent session.

WebSocket Request:

URL: wss://api.assisfy.ai/v1/connect

Required connection Payload:

{
  "apiKey": "your_api_key",
  "sessionId": "your_session_id"
}

Once the connection is established, the system will emit various events that can be handled in your application.

3. Event Payloads

Below are the events you can subscribe to, including the payload structure and data types for each event. These events are emitted from the Assisfy platform to notify your application about the session and agent activities.

Event Name	Description	Payload Structure
started	Emitted when the session is successfully connected.	{ "sessionId": string, "start_url": string }
browser_started	Emitted when the agent successfully connects to a browser.	{ "url": string, "action_session_id": string }
action_run	Emitted when an action is about to be performed by the agent.	{ "name": string, "action_session_id": string, "content": string }
thoughts_and_memories	Emitted to give insight into the agent’s thoughts and memories.	{ "thought": string, "memory": string }
complete	Emitted when the agent finishes its execution.	{ "response": string, "type": string, "total_cost": number, "session_id": string }
error	Emitted when an error occurs during session execution.	{ "error": string }
external_resource_requested	Emitted when the agent requests external input or approval.	{ "resource_type": string, "reason": string, "action_session_id": string, "field_name": string }
external_resource_granted	Emitted when an external resource is granted.	{ "granted": boolean, "input": string }

---

4. Event Details and Data Types

started Event

• Description: Emitted when the session is successfully connected with the agent.

• Payload:

  {
    "sessionId": "abc123",
    "start_url": "https://example.com/start"
  }

  • sessionId: string — A unique identifier for the session.

  • start_url: string — The URL from which the session starts.

browser_started Event

• Description: Emitted when the agent connects to a browser.

• Payload:

  {
    "url": "https://example.com",
    "action_session_id": "action_123"
  }

  • url: string — The URL the agent is currently on.

  • action_session_id: string — A unique identifier for the action session.

action_run Event

• Description: Emitted when the agent is about to perform an action. This is a chargeable event.

• Payload:

  {
    "name": "Click Button",
    "action_session_id": "action_123",
    "content": "Clicking the 'Submit' button on the page"
  }

  • name: string — The name of the action being performed.

  • action_session_id: string — The ID of the action session.

  • content: string — Contextual information about the action (e.g., a description of what the agent is doing).

thoughts_and_memories Event

• Description: Provides insights into the agent's thought process and memory.

• Payload:

  {
    "thought": "The agent is considering the next step in the task.",
    "memory": "The agent remembers that it previously clicked the 'Submit' button."
  }

  • thought: string — Describes the agent’s current thoughts.

  • memory: string — Describes the memory from the agent’s past actions.

complete Event

• Description: Emitted when the agent has completed its execution.

• Payload:

  {
    "response": "Agent has completed the task successfully.",
    "type": "STRING",
    "total_cost": 5.0,
    "session_id": "abc123"
  }

  • response: string — A textual or formatted response providing details about the session outcome.

  • type: string — The type of response, e.g., STRING, JSON, or MARKDOWN.

  • total_cost: number — The cost of the session in your billing system.

  • session_id: string — The ID of the session.

error Event

• Description: Emitted when an error occurs in the session.

• Payload:

  {
    "error": "An unexpected error occurred during the session."
  }

  • error: string — A message describing the error encountered during session execution.

external_resource_requested Event

• Description: Emitted when the agent needs external input (e.g., a form field or an admin approval).

• Payload:

  {
    "resource_type": "request_user_input",
    "reason": "The agent needs input for form submission.",
    "action_session_id": "action_123",
    "field_name": "email"
  }

  • resource_type: string — The type of resource requested, e.g., request_user_input or admin_permission_request.

  • reason: string — The reason why the resource is requested.

  • action_session_id: string — The ID of the action session.

  • field_name: string — The name of the field for which the agent is requesting input (if applicable).

external_resource_granted Event

• Description: Emitted when an external resource is granted.

• Payload:

  {
    "granted": true,
    "input": "user_input_value"
  }

  • granted: boolean — Whether the external resource request was granted or denied.

  • input: string — The input text provided (if granted).

---