AI agents

The AI agents that hold conversations with contacts: their prompt, opening messages, follow-ups, questions and goal, and switching them on or off.

Every route takes Authorization: Bearer <ACCESS_TOKEN> unless the auth line says otherwise. Ids are numbers. Errors use the shape on the errors page.

Route	Scope	What it does
`GET /v1/ai-agents`	`ai_agents.read`	The AI agents of a workspace.
`GET /v1/ai-agents/models`	`ai_agents.read`	The reply models an agent can use.
`GET /v1/ai-agents/{id}`	`ai_agents.read`	One agent with its configuration.
`POST /v1/ai-agents`	`ai_agents.write`	Create an agent. It is a draft unless you send status.
`PATCH /v1/ai-agents/{id}`	`ai_agents.write`	Change its prompt or configuration, or activate / pause it.
`POST /v1/ai-agents/{id}/duplicate`	`ai_agents.write`	A copy of an agent, as a draft.
`DELETE /v1/ai-agents/{id}`	`ai_agents.write`	Delete an agent.

List AI agents

GET https://api.bluereacher.com/v1/ai-agents

Auth: Bearer access token. Scope: ai_agents.read.

The AI agents of a workspace.

Each agent comes with its whole configuration (config_metadata). Agents are per workspace.

Parameters

Name	In	Type	Required	Description
`workspace_id`	query	number	yes	A workspace of the installer.
`status`	query	enum	no	Default all.
`search`	query	string	no	Matches the agent name.
`page`	query	number	no	Default 1.
`limit`	query	number	no	1–100, default 25. Anything else is a 400.

Request

curl -X GET "https://api.bluereacher.com/v1/ai-agents?workspace_id=7&page=1&limit=25" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": [
    {
      "id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607",
      "name": "Revive",
      "role": "Reactivate old leads for Harbour Dental and book them in for a check-up.",
      "persona": "Sam, a friendly front-desk assistant at Harbour Dental. Short, warm messages.",
      "status": "draft",
      "workspace_id": "7",
      "config_metadata": {
        "model": "gpt-4.1-mini",
        "tone": "Friendly",
        "ghl_tag": "revive-2026",
        "company_info": "Harbour Dental, Sydney. Check-ups, cleaning, whitening.",
        "initial_messages": [
          "Hi {{contact.first_name}}, it's Sam from Harbour Dental. It's been a while — would you like to book a check-up?"
        ],
        "followUps": [
          {
            "text": "Just checking in, {{contact.first_name}} — any time suit you this week?",
            "delay": {
              "days": 2,
              "hours": 0,
              "minutes": 0
            }
          }
        ],
        "qualification_enabled": true,
        "questions": [
          {
            "id": "q1",
            "text": "Is it a check-up or something hurting?"
          }
        ],
        "faqs": [
          {
            "question": "Do you take insurance?",
            "answer": "Yes, all major funds."
          }
        ],
        "config": {
          "end_goal": "Send booking link",
          "disqualify_trigger": "Not interested or moved away",
          "booking_link_text": "Here is a link to pick a time:\nhttps://example.com/book"
        }
      },
      "created_at": "2026-10-28T09:00:00.000Z",
      "updated_at": "2026-10-28T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "max_limit": 100,
    "total": 1,
    "total_pages": 1
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): ai_agents.read. This integration was granted: …`
404	workspace_id does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`
502	The AI service could not be reached	`The AI service could not be reached. Try again later.`

Response fields

ai_agent: Each item in data. Fields:

Field	Type	Description
`id`	string	Agent id. Example: `a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607`
`name`	string	Agent name. Example: `Revive`
`role`	string	What the agent is for — its job, in a sentence or two.
`persona`	string	Who it speaks as, and how.
`status`	string	`draft`, `active` (answering) or `paused`. Example: `draft`
`workspace_id`	string	The workspace it works in. Example: `7`
`config_metadata`	object	See Create AI agent.
`created_at`	string (ISO 8601)	Created.
`updated_at`	string (ISO 8601)	Last saved.

List AI models

GET https://api.bluereacher.com/v1/ai-agents/models

Auth: Bearer access token. Scope: ai_agents.read.

The reply models an agent can use.

Use an id as config_metadata.model. Models run on the account's own OpenAI (or OpenRouter) key, set on the dashboard.

Parameters

Name	In	Type	Required	Description
`workspace_id`	query	number	yes	A workspace of the installer.

Request

curl -X GET "https://api.bluereacher.com/v1/ai-agents/models?workspace_id=7" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": [
    {
      "id": "gpt-4.1-mini",
      "name": "GPT-4.1 mini",
      "provider": "openai",
      "description": "Fast and inexpensive; good for most conversations.",
      "recommended": true
    }
  ]
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): ai_agents.read. This integration was granted: …`
404	workspace_id does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`
502	The AI service could not be reached	`The AI service could not be reached. Try again later.`

Get AI agent

GET https://api.bluereacher.com/v1/ai-agents/{id}

Auth: Bearer access token. Scope: ai_agents.read.

One agent with its configuration.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	Agent id.
`workspace_id`	query	number	yes	A workspace of the installer.

Request

curl -X GET "https://api.bluereacher.com/v1/ai-agents/a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607?workspace_id=7" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": {
    "id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607",
    "name": "Revive",
    "role": "Reactivate old leads for Harbour Dental and book them in for a check-up.",
    "persona": "Sam, a friendly front-desk assistant at Harbour Dental. Short, warm messages.",
    "status": "draft",
    "workspace_id": "7",
    "config_metadata": {
      "model": "gpt-4.1-mini",
      "tone": "Friendly",
      "ghl_tag": "revive-2026",
      "company_info": "Harbour Dental, Sydney. Check-ups, cleaning, whitening.",
      "initial_messages": [
        "Hi {{contact.first_name}}, it's Sam from Harbour Dental. It's been a while — would you like to book a check-up?"
      ],
      "followUps": [
        {
          "text": "Just checking in, {{contact.first_name}} — any time suit you this week?",
          "delay": {
            "days": 2,
            "hours": 0,
            "minutes": 0
          }
        }
      ],
      "qualification_enabled": true,
      "questions": [
        {
          "id": "q1",
          "text": "Is it a check-up or something hurting?"
        }
      ],
      "faqs": [
        {
          "question": "Do you take insurance?",
          "answer": "Yes, all major funds."
        }
      ],
      "config": {
        "end_goal": "Send booking link",
        "disqualify_trigger": "Not interested or moved away",
        "booking_link_text": "Here is a link to pick a time:\nhttps://example.com/book"
      }
    },
    "created_at": "2026-10-28T09:00:00.000Z",
    "updated_at": "2026-10-28T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): ai_agents.read. This integration was granted: …`
404	workspace_id does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`
404	The agent does not exist or is in another workspace	`AI agent not found or not accessible to this token`

Response fields

ai_agent. Fields:

Field	Type	Description
`id`	string	Agent id. Example: `a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607`
`name`	string	Agent name. Example: `Revive`
`role`	string	What the agent is for — its job, in a sentence or two.
`persona`	string	Who it speaks as, and how.
`status`	string	`draft`, `active` (answering) or `paused`. Example: `draft`
`workspace_id`	string	The workspace it works in. Example: `7`
`config_metadata`	object	See Create AI agent.
`created_at`	string (ISO 8601)	Created.
`updated_at`	string (ISO 8601)	Last saved.

Create AI agent

POST https://api.bluereacher.com/v1/ai-agents

Auth: Bearer access token. Scope: ai_agents.write.

Create an agent. It is a draft unless you send status.

name and role are required. disqualify_trigger says when to stop. • execution_window — the hours it may message in.

A draft does nothing.

Parameters

Name	In	Type	Required	Description
`workspace_id`	body	number	yes	A workspace of the installer.
`name`	body	string	yes	Agent name, up to 255 characters.
`role`	body	string	yes	What the agent is for.
`persona`	body	string	no	Who it speaks as, and how.
`status`	body	enum	no	`active` runs the activation check (an opening message, a goal, and what that goal needs).
`config_metadata`	body	object	no	The configuration — see the description above.

Request

curl -X POST "https://api.bluereacher.com/v1/ai-agents" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "name": "Revive",
  "role": "Reactivate old leads for Harbour Dental and book them in for a check-up.",
  "persona": "Sam, a friendly front-desk assistant at Harbour Dental. Short, warm messages.",
  "config_metadata": {
    "model": "gpt-4.1-mini",
    "tone": "Friendly",
    "ghl_tag": "revive-2026",
    "initial_messages": [
      "Hi {{contact.first_name}}, it'\''s Sam from Harbour Dental. It'\''s been a while — would you like to book a check-up?"
    ],
    "followUps": [
      {
        "text": "Just checking in, {{contact.first_name}} — any time suit you this week?",
        "delay": {
          "days": 2,
          "hours": 0,
          "minutes": 0
        }
      }
    ],
    "config": {
      "end_goal": "Send booking link",
      "booking_link_text": "Here is a link to pick a time:\nhttps://example.com/book"
    }
  }
}'

Responses

A 201 reply (Created):

{
  "success": true,
  "message": "AI agent created",
  "data": {
    "id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607",
    "name": "Revive",
    "role": "Reactivate old leads for Harbour Dental and book them in for a check-up.",
    "persona": "Sam, a friendly front-desk assistant at Harbour Dental. Short, warm messages.",
    "status": "draft",
    "workspace_id": "7",
    "config_metadata": {
      "model": "gpt-4.1-mini",
      "tone": "Friendly",
      "ghl_tag": "revive-2026",
      "company_info": "Harbour Dental, Sydney. Check-ups, cleaning, whitening.",
      "initial_messages": [
        "Hi {{contact.first_name}}, it's Sam from Harbour Dental. It's been a while — would you like to book a check-up?"
      ],
      "followUps": [
        {
          "text": "Just checking in, {{contact.first_name}} — any time suit you this week?",
          "delay": {
            "days": 2,
            "hours": 0,
            "minutes": 0
          }
        }
      ],
      "qualification_enabled": true,
      "questions": [
        {
          "id": "q1",
          "text": "Is it a check-up or something hurting?"
        }
      ],
      "faqs": [
        {
          "question": "Do you take insurance?",
          "answer": "Yes, all major funds."
        }
      ],
      "config": {
        "end_goal": "Send booking link",
        "disqualify_trigger": "Not interested or moved away",
        "booking_link_text": "Here is a link to pick a time:\nhttps://example.com/book"
      }
    },
    "created_at": "2026-10-28T09:00:00.000Z",
    "updated_at": "2026-10-28T09:00:00.000Z"
  }
}

Status	When	Message
201	Created
400	Missing or invalid field	`role is required — what the agent does, e.g. "Reactivate old leads and book a call"`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): ai_agents.write. This integration was granted: …`
404	workspace_id does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`
502	The AI service could not be reached	`The AI service could not be reached. Try again later.`

Response fields

ai_agent. Fields:

Field	Type	Description
`id`	string	Agent id. Example: `a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607`
`name`	string	Agent name. Example: `Revive`
`role`	string	What the agent is for — its job, in a sentence or two.
`persona`	string	Who it speaks as, and how.
`status`	string	`draft`, `active` (answering) or `paused`. Example: `draft`
`workspace_id`	string	The workspace it works in. Example: `7`
`config_metadata`	object	See Create AI agent.
`created_at`	string (ISO 8601)	Created.
`updated_at`	string (ISO 8601)	Last saved.

Update AI agent

PATCH https://api.bluereacher.com/v1/ai-agents/{id}

Auth: Bearer access token. Scope: ai_agents.write.

Change its prompt or configuration, or activate / pause it.

Send only what changes. config_metadata is merged into what the agent has: the keys you send replace those keys, the others are kept, and the nested config object is merged the same way. So { "config_metadata": { "tone": "Casual" } } changes the tone and nothing else. To clear a key, send it empty ("" or []).

status: "active" switches the agent on after the activation check (400 with what is missing); paused stops it answering. An active agent uses the new wording from its next message, in conversations already running too.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	Agent id.
`workspace_id`	body	number	yes	A workspace of the installer.
`name`	body	string	no	Agent name, up to 255 characters.
`role`	body	string	no	What the agent is for.
`persona`	body	string	no	Who it speaks as, and how.
`status`	body	enum	no	`active` runs the activation check (an opening message, a goal, and what that goal needs).
`config_metadata`	body	object	no	The configuration — see the description above.

Request

curl -X PATCH "https://api.bluereacher.com/v1/ai-agents/a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "status": "active",
  "config_metadata": {
    "tone": "Casual"
  }
}'

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "AI agent updated",
  "data": {
    "id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607",
    "name": "Revive",
    "role": "Reactivate old leads for Harbour Dental and book them in for a check-up.",
    "persona": "Sam, a friendly front-desk assistant at Harbour Dental. Short, warm messages.",
    "status": "active",
    "workspace_id": "7",
    "config_metadata": {
      "model": "gpt-4.1-mini",
      "tone": "Casual",
      "ghl_tag": "revive-2026",
      "company_info": "Harbour Dental, Sydney. Check-ups, cleaning, whitening.",
      "initial_messages": [
        "Hi {{contact.first_name}}, it's Sam from Harbour Dental. It's been a while — would you like to book a check-up?"
      ],
      "followUps": [
        {
          "text": "Just checking in, {{contact.first_name}} — any time suit you this week?",
          "delay": {
            "days": 2,
            "hours": 0,
            "minutes": 0
          }
        }
      ],
      "qualification_enabled": true,
      "questions": [
        {
          "id": "q1",
          "text": "Is it a check-up or something hurting?"
        }
      ],
      "faqs": [
        {
          "question": "Do you take insurance?",
          "answer": "Yes, all major funds."
        }
      ],
      "config": {
        "end_goal": "Send booking link",
        "disqualify_trigger": "Not interested or moved away",
        "booking_link_text": "Here is a link to pick a time:\nhttps://example.com/book"
      }
    },
    "created_at": "2026-10-28T09:00:00.000Z",
    "updated_at": "2026-10-28T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
400	The activation check failed (the AI service's message says what is missing), or a bad value	`Add at least one opening message before activating this agent.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): ai_agents.write. This integration was granted: …`
404	workspace_id does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`
404	The agent does not exist or is in another workspace	`AI agent not found or not accessible to this token`

Response fields

ai_agent. Fields:

Field	Type	Description
`id`	string	Agent id. Example: `a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607`
`name`	string	Agent name. Example: `Revive`
`role`	string	What the agent is for — its job, in a sentence or two.
`persona`	string	Who it speaks as, and how.
`status`	string	`draft`, `active` (answering) or `paused`. Example: `draft`
`workspace_id`	string	The workspace it works in. Example: `7`
`config_metadata`	object	See Create AI agent.
`created_at`	string (ISO 8601)	Created.
`updated_at`	string (ISO 8601)	Last saved.

Duplicate AI agent

POST https://api.bluereacher.com/v1/ai-agents/{id}/duplicate

Auth: Bearer access token. Scope: ai_agents.write.

A copy of an agent, as a draft.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	Agent id.
`workspace_id`	body	number	yes	A workspace of the installer.

Request

curl -X POST "https://api.bluereacher.com/v1/ai-agents/a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607/duplicate" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7
}'

Responses

A 201 reply (Created):

{
  "success": true,
  "message": "AI agent duplicated",
  "data": {
    "id": "b81e0f3a-2c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "name": "Revive (copy)",
    "role": "Reactivate old leads for Harbour Dental and book them in for a check-up.",
    "persona": "Sam, a friendly front-desk assistant at Harbour Dental. Short, warm messages.",
    "status": "draft",
    "workspace_id": "7",
    "config_metadata": {
      "model": "gpt-4.1-mini",
      "tone": "Friendly",
      "ghl_tag": "revive-2026",
      "company_info": "Harbour Dental, Sydney. Check-ups, cleaning, whitening.",
      "initial_messages": [
        "Hi {{contact.first_name}}, it's Sam from Harbour Dental. It's been a while — would you like to book a check-up?"
      ],
      "followUps": [
        {
          "text": "Just checking in, {{contact.first_name}} — any time suit you this week?",
          "delay": {
            "days": 2,
            "hours": 0,
            "minutes": 0
          }
        }
      ],
      "qualification_enabled": true,
      "questions": [
        {
          "id": "q1",
          "text": "Is it a check-up or something hurting?"
        }
      ],
      "faqs": [
        {
          "question": "Do you take insurance?",
          "answer": "Yes, all major funds."
        }
      ],
      "config": {
        "end_goal": "Send booking link",
        "disqualify_trigger": "Not interested or moved away",
        "booking_link_text": "Here is a link to pick a time:\nhttps://example.com/book"
      }
    },
    "created_at": "2026-10-28T09:00:00.000Z",
    "updated_at": "2026-10-28T09:00:00.000Z"
  }
}

Status	When	Message
201	Created
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): ai_agents.write. This integration was granted: …`
404	workspace_id does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`
404	The agent does not exist or is in another workspace	`AI agent not found or not accessible to this token`

Response fields

ai_agent. Fields:

Field	Type	Description
`id`	string	Agent id. Example: `a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607`
`name`	string	Agent name. Example: `Revive`
`role`	string	What the agent is for — its job, in a sentence or two.
`persona`	string	Who it speaks as, and how.
`status`	string	`draft`, `active` (answering) or `paused`. Example: `draft`
`workspace_id`	string	The workspace it works in. Example: `7`
`config_metadata`	object	See Create AI agent.
`created_at`	string (ISO 8601)	Created.
`updated_at`	string (ISO 8601)	Last saved.

Delete AI agent

DELETE https://api.bluereacher.com/v1/ai-agents/{id}

Auth: Bearer access token. Scope: ai_agents.write.

Delete an agent.

It stops answering at once. Cannot be undone; to stop it for now, set status to paused instead.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	Agent id.
`workspace_id`	query	number	yes	A workspace of the installer.

Request

curl -X DELETE "https://api.bluereacher.com/v1/ai-agents/a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607?workspace_id=7" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "AI agent deleted",
  "data": {
    "id": "a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f607"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): ai_agents.write. This integration was granted: …`
404	workspace_id does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`
404	The agent does not exist or is in another workspace	`AI agent not found or not accessible to this token`

AI agents

On this page