Skip to Content

Override a behavior verdict

PATCHhttps://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.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Path parameters

Parameter Type Required Description and constraints
unique_id string Required
Span ID.
Example: "c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b"
behavior_key string Required
Behavior key: a built-in behavior’s name (for example refusal) or a custom behavior’s id.
Example: "refusal"

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
Reference: #/components/schemas/BehaviorOverrideRequest
prob number Required in parent
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.
Minimum: 0
Maximum: 1
Example: 1

OpenAPI request schema

{
  "$ref": "#/components/schemas/BehaviorOverrideRequest"
}
Example
JSON
{ "prob": 0 }

Responses

200

The span’s new verdict.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/BehaviorVerdict
label integer Required in parent
1 when the behavior fired (prob is 0.65 or higher), else 0.
Allowed: 0, 1
Example: 1
prob number Required in parent
The score now on the span.
Example: 1
source string Required in parent
human after an override.
Example: "human"
state string Required in parent
detected 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
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.
polarity (allOf 1) string Schema variant
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.
Reference: #/components/schemas/BehaviorPolarity
Allowed: "negative", "positive", "neutral"
Example: "negative"

OpenAPI response schema

{
  "$ref": "#/components/schemas/BehaviorVerdict"
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
prob array<string> Optional
-
prob[] string Array item
-

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "prob": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Missing or invalid API key
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }
Key lacks the permission
JSON
{ "detail": "This API key does not have the 'logs:update' permission." }
Behaviors are off for the organization
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Not found" }

409

Another override of the same verdict is in progress. Retry.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Another override of this behavior is in progress. Retry." }

429

Rate limited. This endpoint allows 30 requests per minute per organization.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "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"
      }
    }
  }
}