Tone Guide

The tone guide enables teams to define and govern a project's Brand Voice/Tone Guide as a first-class configuration object that reliably shapes AI responses and content operations. We'll look at how to query, create and update the tone guide.

The tone guide model

The tone guide model contains all the information about your groups, including what contacts are in the group and the group's name, description, and avatar.

Properties

Name
id
Type
uuid
Description
Unique identifier for the tone guide.
Name
project_id
Type
uuid
Description
The project identifier for the tone guide.
Name
title
Type
string
Description
The title for the tone guide, defaults to "Brand Voice".
Name
status
Type
string
Description
The lifecycle state of the tone guide, one of draft, in_review, approved, deprecated.
Name
tone_profile
Type
jsonb
Description
Structured JSON describing the tone guide.
Name
system_prompt
Type
string
Description
Compiled prompt for use by the AI, can be provided or generated from tone_profile.
Name
version
Type
number
Description
The version of the tone guide.
Name
created_at
Type
timestamp
Description
Timestamp of when the tone guide was created.
Name
created_by
Type
uuid
Description
Identifier of the user that created the tone guide.
Name
updated_at
Type
timestamp
Description
Timestamp of when the tone guide was updated.
Name
updated_by
Type
uuid
Description
Identifier of the user that updated the tone guide.
Name
approved_at
Type
timestamp
Description
Timestamp of when the tone guide was approved.
Name
approved_by
Type
uuid
Description
Identifier of the user that approved the tone guide.

GET/api/ai/tone-guide

List all tone guides

This endpoint allows you to retrieve a paginated list of all your tone guides. By default, a maximum of ten are returned.

Request

GET

/api/ai/tone-guides

curl -G https://caruuto.com/api/ai/tone-guides \
  -H "Authorization: Api-Key-v1 {apiKey}" \
  -d limit=10

Response

{
  "results": [
    {
      "id": "7fd4998d-e540-4db2-b9f0-a522963ee4a6",
      "project_id": "7febed50-94f5-4eea-a404-6e72753bf61d",
      "title": "Brand Voice",
      "status": "approved",
      "version": 1,
      "system_prompt": "",
      "tone_profile": {
        "brand_personality": ["confident", "precise", "warm"],
        "voice_principles": [
          {"do": "Use short, declarative sentences", "because": "premium clarity"},
          {"dont": "Over-explain or sound apologetic"}
        ],
        "reading_level": "intelligent_nontechnical",
        "style_rules": {
          "formality": "high",
          "humour": "dry",
          "verbosity": "concise",
          "use_oxford_comma": true
        },
        "lexicon": {
          "preferred_terms": ["member", "atelier", "bespoke"],
          "avoid_terms": ["cheap", "budget", "deal"]
        },
        "response_patterns": {
          "always_include": ["next step suggestion"],
          "never_include": ["internal policy", "competitor comparisons"]
        },
        "examples": [
          {"bad": "Hey guys! Super excited...", "good": "Welcome. Here’s what matters..."}
        ],
        "created_at": "2026-02-03 02:09:40.619645+00",
        "created_by" "e19303bc-8e10-4236-9a1b-48d79652a001"
      }
    },
    {
      "id": "e19303bc-8e10-4236-9a1b-48d79652a002",
      // ...
    }
  ]
}

POST/v1/groups

Create a group

This endpoint allows you to create a new group conversation between you and a group of your Protocol contacts.

Required attributes

Name
name
Type
string
Description
The name for the group.

Optional attributes

Name
description
Type
string
Description
The description for the group.
Name
avatar_url
Type
string
Description
The avatar image URL for the group.
Name
contacts
Type
array
Description
An array of contact objects that are members of the group.

Request

POST

/v1/groups

curl https://api.protocol.chat/v1/groups \
  -H "Authorization: Bearer {token}" \
  -d name="Plaza Hotel"

Response

{
  "id": "l7cGNIBKZiNJ6wqF",
  "name": "Plaza Hotel",
  "description": null,
  "avatar_url": null,
  "conversation_id": "ZYjVAbCE9g5XRlra",
  "contacts": [],
  "created_at": 692233200,
  "archived_at": null
}

GET/v1/groups/:id

Retrieve a group

This endpoint allows you to retrieve a group by providing the group id. Refer to the list at the top of this page to see which properties are included with group objects.

Request

GET

/v1/groups/L7cGNIBKZiNJ6wqF

curl https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "l7cGNIBKZiNJ6wqF",
  "name": "Plaza Hotel",
  "description": "World-renowned.",
  "avatar_url": "https://assets.protocol.chat/avatars/plazahotel.jpg",
  "conversation_id": "ZYjVAbCE9g5XRlra",
  "contacts": [
    {
      "username": "Hector"
      // ...
    },
    {
      "username": "Cedric"
      // ...
    },
    {
      "username": "Hester"
      // ...
    },
    {
      "username": "Cliff"
      // ...
    }
  ],
  "created_at": 692233200,
  "archived_at": null
}

PUT/v1/groups/:id

Update a group

This endpoint allows you to perform an update on a group. Examples of updates are changing the name, description, and avatar or adding and removing contacts from the group.

Optional attributes

Name
name
Type
string
Description
The new name for the group.
Name
description
Type
string
Description
The new description for the group.
Name
avatar_url
Type
string
Description
The new avatar image URL for the group.
Name
contacts
Type
array
Description
An array of contact objects that are members of the group.
Name
archived_at
Type
timestamp
Description
Timestamp of when the group was archived.

Request

PUT

/v1/groups/L7cGNIBKZiNJ6wqF

curl -X PUT https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
  -H "Authorization: Bearer {token}" \
  -d description="The finest in New York."

Response

{
  "id": "l7cGNIBKZiNJ6wqF",
  "name": "Plaza Hotel",
  "description": "The finest in New York.",
  "avatar_url": "https://assets.protocol.chat/avatars/plazahotel.jpg",
  "conversation_id": "ZYjVAbCE9g5XRlra",
  "contacts": [
    {
      "username": "Hector"
      // ...
    },
    {
      "username": "Cedric"
      // ...
    },
    {
      "username": "Hester"
      // ...
    },
    {
      "username": "Cliff"
      // ...
    }
  ],
  "created_at": 692233200,
  "archived_at": null
},

DELETE/v1/groups/:id

Delete a group

This endpoint allows you to delete groups. Note: This will permanently delete the group, including the messages — archive it instead if you want to be able to restore it later.

Request

DELETE

/v1/groups/L7cGNIBKZiNJ6wqF

curl -X DELETE https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
  -H "Authorization: Bearer {token}"