Override a behavior verdict
https://api.respan.ai/api/request-logs/{unique_id}/behaviors/{behavior_key}/Records whether a behavior happened on a span, replacing the model’s score (Happened / Not happened in the app). The span must already have a verdict for the behavior. Span-level reads use it at once; rollup counts pick it up within 10 minutes for spans from the last 48 hours.
Servers
https://api.respan.ai: Respan API Server
Authentication
RespanApiKey
Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.
HTTP scheme: bearer; format: Respan API key.
Authorization: Bearer $RESPAN_API_KEYPath parameters
unique_id string RequiredExample:
"c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b"behavior_key string Requiredrefusal) or a custom behavior’s id.Example:
"refusal"Request body
A request body is required.
application/json
$ object Required body
#/components/schemas/BehaviorOverrideRequestprob number Required in parent1 for Happened and 0 for Not happened. The behavior fires when this is 0.65 or higher.Minimum:
0Maximum:
1Example:
1OpenAPI request schema
{
"$ref": "#/components/schemas/BehaviorOverrideRequest"
}Example
{
"prob": 0
}Responses
200
The span’s new verdict.
application/json
$ object Body
#/components/schemas/BehaviorVerdictlabel integer Required in parent1 when the behavior fired (prob is 0.65 or higher), else 0.Allowed:
0, 1Example:
1prob number Required in parentExample:
1source string Required in parenthuman after an override.Example:
"human"state string Required in parentdetected at 0.65 or higher, uncertain from 0.35 up to 0.65, else not_detected.Allowed:
"detected", "uncertain", "not_detected"Example:
"detected"polarity string or null Required in parent
negative (an Issue), positive (a Win) or neutral (Info). Display metadata only; it does not change how spans are scored.polarity (allOf 1) string Schema variantnegative (an Issue), positive (a Win) or neutral (Info). Display metadata only; it does not change how spans are scored.Reference:
#/components/schemas/BehaviorPolarityAllowed:
"negative", "positive", "neutral"Example:
"negative"OpenAPI response schema
{
"$ref": "#/components/schemas/BehaviorVerdict"
}Example
{
"label": 0,
"prob": 0,
"source": "human",
"state": "not_detected",
"polarity": "neutral"
}400
prob is missing, not a number, or outside 0 to 1.
application/json
$ object Body
prob array<string> Optional
prob[] string Array itemOpenAPI response schema
{
"type": "object",
"properties": {
"prob": {
"type": "array",
"items": {
"type": "string"
}
}
}
}Example
{
"prob": [
"Ensure this value is less than or equal to 1.0."
]
}403
Forbidden: the API key is missing, invalid or expired; the key doesn’t grant logs:update (Write access does); behaviors are turned off for the organization.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Missing or invalid API key
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}Key lacks the permission
{
"detail": "This API key does not have the 'logs:update' permission."
}Behaviors are off for the organization
{
"detail": "Span Behaviors is not enabled for this organization."
}404
The span has no verdict for this behavior: it doesn’t exist, hasn’t been scored yet, or the behavior is turned off.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Not found"
}409
Another override of the same verdict is in progress. Retry.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Another override of this behavior is in progress. Retry."
}429
Rate limited. This endpoint allows 30 requests per minute per organization.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Request was throttled."
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "Override a behavior verdict",
"operationId": "overrideSpanBehavior",
"tags": [
"Behaviors"
],
"description": "Records whether a behavior happened on a span, replacing the model's score (Happened / Not happened in the app). The span must already have a verdict for the behavior. Span-level reads use it at once; rollup counts pick it up within 10 minutes for spans from the last 48 hours.",
"parameters": [
{
"name": "unique_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Span ID.",
"example": "c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b"
},
{
"name": "behavior_key",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.",
"example": "refusal"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorOverrideRequest"
},
"example": {
"prob": 0
}
}
}
},
"responses": {
"200": {
"description": "The span's new verdict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorVerdict"
},
"example": {
"label": 0,
"prob": 0,
"source": "human",
"state": "not_detected",
"polarity": "neutral"
}
}
}
},
"400": {
"description": "`prob` is missing, not a number, or outside 0 to 1.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"prob": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"prob": [
"Ensure this value is less than or equal to 1.0."
]
}
}
}
},
"403": {
"description": "Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:update` (Write access does); behaviors are turned off for the organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"examples": {
"invalidKey": {
"summary": "Missing or invalid API key",
"value": {
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
},
"missingPermission": {
"summary": "Key lacks the permission",
"value": {
"detail": "This API key does not have the 'logs:update' permission."
}
},
"behaviorsOff": {
"summary": "Behaviors are off for the organization",
"value": {
"detail": "Span Behaviors is not enabled for this organization."
}
}
}
}
}
},
"404": {
"description": "The span has no verdict for this behavior: it doesn't exist, hasn't been scored yet, or the behavior is turned off.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Not found"
}
}
}
},
"409": {
"description": "Another override of the same verdict is in progress. Retry.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Another override of this behavior is in progress. Retry."
}
}
}
},
"429": {
"description": "Rate limited. This endpoint allows 30 requests per minute per organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Request was throttled."
}
}
}
}
},
"security": [
{
"RespanApiKey": []
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"schemas": {
"BehaviorOverrideRequest": {
"type": "object",
"required": [
"prob"
],
"properties": {
"prob": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "The score to record in place of the model's. Send `1` for Happened and `0` for Not happened. The behavior fires when this is 0.65 or higher.",
"example": 1
}
}
},
"BehaviorPolarity": {
"type": "string",
"enum": [
"negative",
"positive",
"neutral"
],
"description": "Whether the behavior firing is good or bad: `negative` (an Issue), `positive` (a Win) or `neutral` (Info). Display metadata only; it does not change how spans are scored.",
"example": "negative"
},
"BehaviorVerdict": {
"type": "object",
"required": [
"label",
"prob",
"source",
"state",
"polarity"
],
"properties": {
"label": {
"type": "integer",
"enum": [
0,
1
],
"description": "`1` when the behavior fired (`prob` is 0.65 or higher), else `0`.",
"example": 1
},
"prob": {
"type": "number",
"description": "The score now on the span.",
"example": 1
},
"source": {
"type": "string",
"description": "`human` after an override.",
"example": "human"
},
"state": {
"type": "string",
"enum": [
"detected",
"uncertain",
"not_detected"
],
"description": "`detected` at 0.65 or higher, `uncertain` from 0.35 up to 0.65, else `not_detected`.",
"example": "detected"
},
"polarity": {
"allOf": [
{
"$ref": "#/components/schemas/BehaviorPolarity"
}
],
"nullable": true,
"description": "Whether the behavior firing is good or bad: `negative` (an Issue), `positive` (a Win) or `neutral` (Info). Display metadata only; it does not change how spans are scored."
}
}
}
},
"securitySchemes": {
"RespanApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Respan API key",
"description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
"x-fern-bearer": {
"name": "respanApiKey",
"env": "RESPAN_API_KEY"
}
}
}
}