> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brixo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals HTTP API

> Send lightweight “signals” (tags) from your chat or agent application to Brixo — like thumbs up/down feedback on an assistant message.

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`

Use the same message ID you sent during [Python SDK instrumentation](/ingestion/python) via `message_id` to link the traced assistant message and the feedback signal.

### Conversation-level signal

`POST /v1/conversations/:id/signals`

> `:id` is a **customer-provided ID** from your system (not Brixo-generated).
>
> For message-level signals, `:id` must be the same value you sent as `message_id` during [Python SDK instrumentation](/ingestion/python).
>
> 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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`

This `msg_1042` value must match the `message_id` attached to the traced assistant message during [Python SDK instrumentation](/ingestion/python).

```json theme={null}
{
  "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`

```json theme={null}
{
  "data": {
    "type": "signals",
    "attributes": {
      "name": "feedback",
      "value": "thumbs_down",
      "user_message": "Very frustrating!"
    }
  }
}
```