Beacon API

Score conversation health and detect when an agent needs help — stuck in a loop, user frustration, task too difficult or ambiguous — and decide whether to escalate.

Overview

The Beacon API analyses a conversation history and returns a health score from 0 to 100 along with a boolean indicating whether a human or supervisor agent should step in. Call it periodically during long agent runs to catch failure modes early.

It detects the following signals:

Stuck in a loop — the agent repeats the same action or error without progress
User frustration — explicit frustration, escalating impatience, or corrective tone
Task too difficult or ambiguous — agent admits failure or asks the same question repeatedly
Blocked path — required credentials, access, or context cannot be obtained

Three endpoint formats are supported so you can pass the same message shape your application already produces.

Authentication

The Beacon API uses the same Downsizing access key as all other endpoints. Pass it in the Authorization header:

Authorization: Bearer dws_YOUR_API_KEY

Find your key in the API section of your dashboard.

Endpoints

All three endpoints accept up to 1 000 000 tokens of conversation history and return the same JSON response.

Anthropic format

Pass a messages array in Anthropic /v1/messages format:

bash

curl -X POST \
  https://api.downsizing.dev/YOUR_INFERENCE_ID/anthropic/v1/beacon \
  -H "Authorization: Bearer dws_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Fix the login bug." },
      { "role": "assistant", "content": "I tried patching the auth middleware." },
      { "role": "user", "content": "Still broken. You keep doing the same thing." }
    ]
  }'

OpenAI Chat Completions format

Pass a messages array in OpenAI Chat Completions format:

bash

curl -X POST \
  https://api.downsizing.dev/YOUR_INFERENCE_ID/openai/v1/chat/beacon \
  -H "Authorization: Bearer dws_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Fix the login bug." },
      { "role": "assistant", "content": "I tried patching the auth middleware." },
      { "role": "user", "content": "Still broken. You keep doing the same thing." }
    ]
  }'

OpenAI Responses API format

Pass an input array in OpenAI Responses API format:

bash

curl -X POST \
  https://api.downsizing.dev/YOUR_INFERENCE_ID/openai/v1/responses/beacon \
  -H "Authorization: Bearer dws_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      { "type": "message", "role": "user", "content": "Fix the login bug." },
      { "type": "message", "role": "assistant", "content": "I tried patching the auth middleware." },
      { "type": "message", "role": "user", "content": "Still broken. You keep doing the same thing." }
    ]
  }'

Response

All three endpoints return the same JSON object with a numeric health score and a boolean intervention flag:

json

{
  "health_score": 92,
  "intervention_needed": false
}

json

{
  "health_score": 24,
  "intervention_needed": true
}

health_score — 0 (severely unhealthy) to 100 (perfectly healthy)
intervention_needed: false — conversation is healthy, no action needed
intervention_needed: true — a problem signal was detected; escalate or correct

If the detection model is temporarily unavailable, the API falls back to health_score: 100, intervention_needed: false so your agent loop is never blocked by scorer unavailability.

SDK examples

Anthropic SDK

python

import anthropic

client = anthropic.Anthropic(
    api_key="dws_YOUR_API_KEY",
    base_url="https://api.downsizing.dev/YOUR_INFERENCE_ID/anthropic",
)

response = client._client.post(
    "/v1/beacon",
    headers={"x-api-key": "dws_YOUR_API_KEY"},
    json={"messages": conversation_history},
)
response.raise_for_status()
if response.json()["intervention_needed"]:
    escalate_to_human()

OpenAI SDK

python

import openai

client = openai.OpenAI(
    api_key="dws_YOUR_API_KEY",
    base_url="https://api.downsizing.dev/YOUR_INFERENCE_ID/openai/v1",
)

response = client._client.post(
    "/chat/beacon",
    headers={"Authorization": "Bearer dws_YOUR_API_KEY"},
    json={"messages": conversation_history},
)
response.raise_for_status()
if response.json()["intervention_needed"]:
    escalate_to_human()

Pricing

The Beacon API is billed at $0.01 per request, charged against your pay-per-use balance. Request counts and charges are visible in the billing section of your dashboard.

← Back to docs

Previous← Routing API NextAnthropic →

Spot an error or something not working? Tell us on Discord or email docs@downsizing.dev.