> ## Documentation Index
> Fetch the complete documentation index at: https://actionbook.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.dev/dashboard). All endpoints on this page require it in the `x-api-key` header.

```bash theme={null}
export API_KEY="your_api_key"
```

### Step 2: Create Profile

```bash theme={null}
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 theme={null}
{
  "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 theme={null}
export PROFILE_ID="gp_xxxxxxxx"
```

```bash theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
```

Events:

```text theme={null}
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          |