KEkeywordsai
Behaviors

Update a custom behavior

Changed on

Changes a custom behavior's name, definition or polarity. A new definition reaches new spans within about a minute; past spans are not rescored.

patch/api/pulses/behaviors/custom/{id}/

Request

  • Base URL
    https://api.respan.ai
  • URL
    https://api.respan.ai/api/pulses/behaviors/custom/{id}/
  • Auth
    HTTP bearer

Path parameters

idstring required

Custom behavior ID.

Request body

descriptionstring

New definition. New spans are scored against it within about a minute. Past spans are not rescored.

namestring nullable

New display name. Blank or null clears it.

polarity'negative' | 'positive' | 'neutral'

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 request

{
  "description": "The assistant promises a refund, credit, or compensation that the policy in the system prompt does not allow.",
  "name": "Refund promise",
  "polarity": "negative"
}

Response

The updated behavior, without tags.

idstring required

Custom behavior ID. It is also the behavior's key in analytics, filters and span verdicts.

namestring nullable required

Display name. Optional and not unique; behaviors are identified by id.

descriptionstring required

The plain-language definition span-01 scores each span against. Say what counts and what doesn't. At least 3 characters after trimming.

polarity'negative' | 'positive' | 'neutral' required

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.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93",
  "name": "Refund promise",
  "description": "The assistant promises a refund, credit, or compensation that the policy in the system prompt does not allow.",
  "polarity": "negative",
  "created_at": "2026-09-28T17:41:09.512340Z",
  "updated_at": "2026-09-28T17:41:09.512340Z"
}

Changes

  • c30bcb383ee8Revision changes
    • breaking

      request body became required

    • breaking

      added to the request property allOf list

    • breaking

      removed the enum value negative of the request property

    • breaking

      removed the enum value neutral of the request property

    • breaking

      removed the enum value positive of the request property

    • breaking

      the request property type changed from string to no type

    • breaking

      the response property became nullable for the status

    • info

      api operation id behaviors_updateCustomBehavior removed and replaced with updateCustomBehavior

    • info

      api tag Behaviors added

    • info

      api tag behaviors removed

    • info

      the request property became nullable

  • b830b79cfd52Revision changes
    • info

      endpoint added