Skip to main content
A signal has three essentials:
  1. What you’re tagging: a message or conversation
  2. The signal name: feedback
  3. The signal value: thumbs_up or thumbs_down
Optionally, you can include:
  • occurred_at (when the signal happened)
  • user_message (a message the user may have included with the signal)

​
Base URL

All requests should be sent to: https://api.brixo.com For example:
  • POST https://api.brixo.com/v1/messages/:id/signals
  • POST https://api.brixo.com/v1/conversations/:id/signals
All endpoint paths shown in this document are relative to this base URL.

​
Endpoints

​
Message-level signal

POST /v1/messages/:id/signals

​
Conversation-level signal

POST /v1/conversations/:id/signals
:id is a customer-provided ID from your system (not Brixo-generated). If Brixo cannot find the message/conversation, the API returns 404 Not Found.

​
Authentication

Authorization: Bearer <BRIXO_API_KEY>

​
Content-Type

Requests and error responses follow JSON:API.
  • Request header: Content-Type: application/vnd.api+json
  • Response header: Content-Type: application/vnd.api+json (for errors)

​
Request body

​
Feedback signal

{
  "data": {
    "type": "signals",
    "attributes": {
      "name": "feedback",
      "value": "thumbs_up",
      "occurred_at": "2026-02-03T14:22:10Z",
      "user_message": "Love this product!"
    }
  }
}

​
Omitting occurred_at

If occurred_at is omitted, Brixo will use the time it received the request. 
{
  "data": {
    "type": "signals",
    "attributes": {
      "name": "feedback",
      "value": "thumbs_down"
    }
  }
}

​
Attributes

​
Required

  • data.type (string) Must be "signals".
  • data.attributes.name (string) Must be "feedback".
  • data.attributes.value (string) Must be one of:
    • "thumbs_up"
    • "thumbs_down"

​
Optional

  • data.attributes.occurred_at (string, RFC3339 / ISO-8601) When the signal occurred. If omitted, server-received time is used.
  • data.attributes.user_message (string) A user message the user may have included with their feedback.

​
Response

​
Success

  • 204 No Content
No response body is returned.

​
Errors

Error responses use the JSON:API error object format: 
{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "..."
    }
  ]
}

​
Common errors

  • 400 Bad Request
    • Missing data, data.type, or data.attributes
    • data.type is not "signals"
    • name is missing or not "feedback"
    • value is missing or not one of "thumbs_up" | "thumbs_down"
    • occurred_at is present but not a valid RFC3339 timestamp
  • 401 Unauthorized
    • Missing or invalid API key
  • 404 Not Found
    • Message or conversation :id not found
  • 413 Payload Too Large
    • Request body too large

​
Examples

​
Message feedback (thumbs up)

POST /v1/messages/msg_1042/signals 
{
  "data": {
    "type": "signals",
    "attributes": {
      "name": "feedback",
      "value": "thumbs_up",
      "occurred_at": "2026-02-03T14:22:10Z",
      "user_message": "Love this product!"
    }
  }
}

​
Conversation feedback (thumbs down)

POST /v1/conversations/conv_abc123/signals 
{
  "data": {
    "type": "signals",
    "attributes": {
      "name": "feedback",
      "value": "thumbs_down",
      "user_message": "Very frustrating!"
    }
  }
}