Skip to main content
POST
https://dashboard.laburen.com
/
api
/
annotations
curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "bad",
    "comment": "The agent provided incorrect information about pricing",
    "tagIds": ["clxxxxxxxxxxxxxxxxx"]
}'

{
  "id": "clxxxxxxxxxxxxxxxxx",
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "agentId": "clxxxxxxxxxxxxxxxxx",
  "organizationId": "clxxxxxxxxxxxxxxxxx",
  "comment": "The agent provided incorrect information about pricing",
  "sentiment": "bad",
  "status": "pending",
  "createdById": "clxxxxxxxxxxxxxxxxx",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "tags": [
    {
      "tag": {
        "id": "clxxxxxxxxxxxxxxxxx",
        "name": "bug"
      }
    }
  ]
}
This endpoint creates a new annotation or updates an existing one for a message. It supports:
  • Creating annotations for agent messages
  • Updating existing annotations (upsert by messageId)
  • Associating tags with annotations
  • Public agent access (no authentication required for public agents)
  • Automatic organization and agent resolution from message
Authentication is optional for public agents. If the message belongs to a public agent, you can create annotations without authentication. Otherwise, authentication is required.
Only agent messages can be annotated. Attempting to annotate a user or contact message will result in a 400 error.

​
Body

​
Required

​
messageId
string
required
The ID of the message to annotate (CUID format). The message must be from an agent (not a user or contact).
​
sentiment
string
required
Sentiment of the annotation. Valid values: good, bad.
​
comment
string
required
Comment or feedback text for the annotation. Cannot be empty or whitespace-only.

​
Optional

​
tagIds
array
Array of tag IDs (CUID format) to associate with the annotation. If provided, replaces any existing tags. If omitted or empty, removes all tags.

​
Response

​
id
string
Unique identifier of the annotation (CUID format).
​
messageId
string
ID of the message this annotation refers to.
​
conversationId
string
ID of the conversation this annotation belongs to.
​
agentId
string
ID of the agent associated with this annotation.
​
organizationId
string
ID of the organization the annotation belongs to.
​
comment
string
Comment or feedback text for the annotation.
​
sentiment
string
Sentiment of the annotation (e.g., good, bad).
​
status
string
Current status of the annotation.
​
createdById
string
ID of the user who created or last updated the annotation.
​
createdAt
string
ISO 8601 timestamp of when the annotation was created.
​
updatedAt
string
ISO 8601 timestamp of when the annotation was last updated.
​
tags
array
Tags associated with the annotation.

​
Error Responses

Status CodeTypeDescription
400Bad RequestComment is empty or whitespace-only, or attempting to annotate a non-agent message.
401UNAUTHORIZEDMissing or invalid authentication session, and the message does not belong to a public agent, or the message’s organization does not match your session.
404NOT_FOUNDMessage with the specified ID does not exist.
400INVALID_REQUESTMessage does not have an associated agent ID.
curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "bad",
    "comment": "The agent provided incorrect information about pricing",
    "tagIds": ["clxxxxxxxxxxxxxxxxx"]
}'

{
  "id": "clxxxxxxxxxxxxxxxxx",
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "agentId": "clxxxxxxxxxxxxxxxxx",
  "organizationId": "clxxxxxxxxxxxxxxxxx",
  "comment": "The agent provided incorrect information about pricing",
  "sentiment": "bad",
  "status": "pending",
  "createdById": "clxxxxxxxxxxxxxxxxx",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "tags": [
    {
      "tag": {
        "id": "clxxxxxxxxxxxxxxxxx",
        "name": "bug"
      }
    }
  ]
}