actionbook__actionbook/docs/api-reference/evaluate-api.mdx

---
title: 'Evaluate API'
---

## What You Can Do

- Run GEO evaluation workflows against your target prompts.
- Run concurrent evaluations across multiple real AI web pages and sessions.
- Compare the same prompt across different AI providers and web experiences.

## Request Access

<CardGroup cols={2}>
  <Card title="Private Beta" icon="flask">
    Evaluate API is currently available by request during private beta. We
    enable access for approved workspaces.
  </Card>
  <Card
    title="Apply Now"
    icon="envelope"
    href="mailto:hello@actionbook.dev?subject=Evaluate%20API%20Private%20Beta%20Request&body=Hi%20Actionbook%20team%2C%0A%0AI%E2%80%99d%20like%20to%20request%20access%20to%20the%20Evaluate%20API.%0A%0ACompany%3A%0AWebsite%20to%20test%3A%0AUse%20case%3A%0A%0AThanks."
  >
    Email `hello@actionbook.dev` with your company, the website you want to
    test, and your use case.
  </Card>
</CardGroup>

## Quick Start

Get started in 3 minutes: create a profile, complete login, and run your first
evaluate request.

### Step 1: Get Your API Key

Create an Actionbook API key from the [Actionbook dashboard](https://actionbook.app/dashboard). All endpoints on this page require it in the `x-api-key` header.

```bash
export API_KEY="your_api_key"
```

### Step 2: Create Profile

```bash
curl -sS "https://api.actionbook.dev/api/profiles" \
  -X POST \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json"
```

Example live response:

```json
{
  "success": true,
  "data": {
    "profile_id": "gp_xxxxxxxx",
    "profile_login_url": "https://app.hyperbrowser.ai/live?token=<redacted>&liveDomain=https://connect-us-east-1.hyperbrowser.ai"
  },
  "code": 0,
  "error": "",
  "message": ""
}
```

### Step 3: Complete Profile Login

Open the returned `profile_login_url`, complete the login flow, then persist the
profile with the finish endpoint.

```bash
export PROFILE_ID="gp_xxxxxxxx"
```

```bash
curl -sS "https://api.actionbook.dev/api/profiles/$PROFILE_ID/finish" \
  -X POST \
  -H "x-api-key: $API_KEY"
```

#### Profile Login Demo

<div className="w-full aspect-video overflow-hidden rounded-xl">
  <iframe
    className="h-full w-full"
    src="https://www.loom.com/embed/f9e839d6b8174cb3ad0ccdf658e4de54"
    frameBorder="0"
    webkitallowfullscreen
    mozallowfullscreen
    allowFullScreen
  />
</div>

### Step 4: Submit Evaluate Request

```bash
curl -N "https://api.actionbook.dev/api/evaluate" \
  -X POST \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"What is the best CRM software for small businesses?\",\"profile_id\":\"$PROFILE_ID\"}"
```

#### Get Your Final AI Response

The endpoint returns a Server-Sent Events (SSE) stream. A typical response looks
like this:

```text
event: start
data: {"chat_id":null,"profile_id":"gp_1cc2f90fa88947b1"}

event: chunk
data: {"content":"The best CRM for a small business depends on budget, ease of use, features, and scalability..."}

event: chunk
data: {"content":"Top options include HubSpot, Zoho CRM, Pipedrive, Monday CRM, and Freshsales..."}

event: complete
data: {"chat_id":"69c3d535-2de4-8330-92bc-e4c408ffd6be","output":{"content":"Final answer content...","created_at":"2026-03-25T12:28:29.098Z","completed_at":"2026-03-25T12:30:45.572Z"},"metrics":{"ttft_ms":2034}}
```

`start` initializes the task, `chunk` streams partial output, and `complete`
returns the final response payload including performance `metrics`.

## API Reference

### `POST /api/profiles`

Creates a profile and returns a remote browser login URL.

#### Headers

| Name | Required | Value |
| --- | --- | --- |
| `x-api-key` | Yes | Actionbook API key |
| `Content-Type` | No | `application/json` when sending a body |

#### Response

```json
{
  "success": true,
  "data": {
    "profile_id": "gp_41f856e9997d4d5c",
    "profile_login_url": "https://app.hyperbrowser.ai/live?token=<redacted>&liveDomain=https://connect-us-east-1.hyperbrowser.ai"
  },
  "code": 0,
  "error": "",
  "message": ""
}
```

- `profile_id` values use the `gp_` prefix
- `profile_login_url` is a HyperBrowser live session URL

### `GET /api/profiles`

Returns all profiles owned by the current API key user.

#### Headers

| Name | Required | Value |
| --- | --- | --- |
| `x-api-key` | Yes | Actionbook API key |

#### Response

```json
{
  "success": true,
  "data": {
    "profiles": [
      {
        "profile_id": "gp_41f856e9997d4d5c",
        "provider": "chatgpt",
        "created_time": "2026-03-25T03:50:25.736Z",
        "last_update_time": "2026-03-25T03:52:13.640Z"
      },
      {
        "profile_id": "gp_2079c71faf974f94",
        "provider": "chatgpt",
        "created_time": "2026-03-24T17:55:01.874Z",
        "last_update_time": "2026-03-24T17:57:35.867Z"
      }
    ]
  },
  "code": 0,
  "error": "",
  "message": ""
}
```

#### Profile fields

| Field | Type | Notes |
| --- | --- | --- |
| `profile_id` | `string` | Profile ID |
| `provider` | `string` | Currently document `chatgpt` |
| `created_time` | `string` | ISO 8601 |
| `last_update_time` | `string` | ISO 8601 |

### `PUT /api/profiles/{profileId}`

Re-opens a login session for an existing profile.

#### Headers

| Name | Required | Value |
| --- | --- | --- |
| `x-api-key` | Yes | Actionbook API key |

#### Response


```json
{
  "success": true,
  "data": {
    "profile_id": "gp_41f856e9997d4d5c",
    "profile_login_url": "https://app.hyperbrowser.ai/live?token=<redacted>&liveDomain=https://connect-us-east-1.hyperbrowser.ai"
  },
  "code": 0,
  "error": "",
  "message": ""
}
```

- You still need to log in and call `POST /api/profiles/{profileId}/finish`

### `POST /api/profiles/{profileId}/finish`

Persists the profile data after login is complete.

#### Headers

| Name | Required | Value |
| --- | --- | --- |
| `x-api-key` | Yes | Actionbook API key |

#### Response

Returns a standard success envelope.

### `DELETE /api/profiles/{profileId}`

Deletes the profile and related evaluate task records.

#### Headers

| Name | Required | Value |
| --- | --- | --- |
| `x-api-key` | Yes | Actionbook API key |

#### Response

Returns a standard success envelope.

### `POST /api/evaluate`

Creates an evaluate task and returns an SSE stream.

#### Headers

| Name | Required | Value |
| --- | --- | --- |
| `x-api-key` | Yes | Actionbook API key |
| `Content-Type` | Yes | `application/json` |

#### Request body

```json
{
  "input": "What is the best CRM software for small businesses?",
  "profile_id": "gp_41f856e9997d4d5c",
  "chat_id": "chat_abc",
  "provider": "chatgpt"
}
```

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `input` | `string` | Yes | Must be non-empty |
| `profile_id` | `string` | Yes | Must belong to the current user |
| `chat_id` | `string \| null` | No | Continue an existing conversation |
| `provider` | `string` | No | Defaults to `chatgpt` |

#### Response

Headers:

```http
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
```

Events:

```text
event: start
data: {"chat_id":null,"profile_id":"gp_41f856e9997d4d5c"}

event: chunk
data: {"chat_id":"chat_abc","content":"Based on my research, "}

event: complete
data: {"chat_id":"chat_abc","output":{"content":"final answer","created_at":"2026-03-20T07:45:00.000Z","completed_at":"2026-03-20T07:45:32.000Z"},"metrics":{"ttft_ms":2034}}
```

#### `complete` event fields

| Field | Type | Notes |
| --- | --- | --- |
| `chat_id` | `string` | Conversation ID for multi-turn follow-ups |
| `output.content` | `string` | Final AI response text |
| `output.created_at` | `string` | ISO 8601 timestamp when the task was created |
| `output.completed_at` | `string` | ISO 8601 timestamp when the task finished |
| `metrics.ttft_ms` | `number` | Time to first token in milliseconds |