# 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**:

```json
{
  "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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**:

  ```json
  {
    "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).

***

###


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://assisfy.gitbook.io/assisfy.ai/getting-started/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.