RErespan
Behaviors

Create a custom behavior

Changed on

Creates a behavior from a plain-language definition. New spans are scored against it from then on; past spans are not rescored.

post/api/pulses/behaviors/custom/

Request

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

Request body

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.

namestring nullable

Display name. Optional and not unique. Blank is stored as null.

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 created behavior.

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_createCustomBehavior removed and replaced with createCustomBehavior

    • info

      api tag Behaviors added

    • info

      api tag behaviors removed

    • info

      the request property became nullable

    • info

      the request property default value neutral was added

  • b830b79cfd52Revision changes
    • info

      endpoint added