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

Private Beta

Evaluate API is currently available by request during private beta. We enable access for approved workspaces.

Apply Now

Email hello@actionbook.dev with your company, the website you want to test, and your use case.

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. All endpoints on this page require it in the x-api-key header.

export API_KEY="your_api_key"

Step 2: Create Profile

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

Example live response:

{
  "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": ""
}

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

export PROFILE_ID="gp_xxxxxxxx"

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

Step 4: Submit Evaluate Request

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:

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

{
  "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

{
  "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

{
  "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

{
  "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:

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

Events:

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

Getting Started

CLI

Advanced

What You Can Do

Request Access

Private Beta

Apply Now

Quick Start

Step 1: Get Your API Key

Step 2: Create Profile

Step 4: Submit Evaluate Request

Get Your Final AI Response

API Reference

`POST /api/profiles`

Headers

Response

`GET /api/profiles`

Headers

Response

Profile fields

`PUT /api/profiles/{profileId}`

Headers

Response

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

Headers

Response

`DELETE /api/profiles/{profileId}`

Headers

Response

`POST /api/evaluate`

Headers

Request body

Response

`complete` event fields

Getting Started

CLI

Advanced

​What You Can Do

​Request Access

Private Beta

Apply Now

​Quick Start

​Step 1: Get Your API Key

​Step 2: Create Profile

​Step 3: Complete Profile Login

​Profile Login Demo

​Step 4: Submit Evaluate Request

​Get Your Final AI Response

​API Reference

​POST /api/profiles

​Headers

​Response

​GET /api/profiles

​Headers

​Response

​Profile fields

​PUT /api/profiles/{profileId}

​Headers

​Response

​POST /api/profiles/{profileId}/finish

​Headers

​Response

​DELETE /api/profiles/{profileId}

​Headers

​Response

​POST /api/evaluate

​Headers

​Request body

​Response

​complete event fields

What You Can Do

Request Access

Quick Start

Step 1: Get Your API Key

Step 2: Create Profile

Step 3: Complete Profile Login

Profile Login Demo

Step 4: Submit Evaluate Request

Get Your Final AI Response

API Reference

`POST /api/profiles`

Headers

Response

`GET /api/profiles`

Headers

Response

Profile fields

`PUT /api/profiles/{profileId}`

Headers

Response

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

Headers

Response

`DELETE /api/profiles/{profileId}`

Headers

Response

`POST /api/evaluate`

Headers

Request body

Response

`complete` event fields