Create a custom behavior

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

Authentication

AuthorizationBearer

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.

Request

This endpoint expects an object.

descriptionstringRequired>=3 characters

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

namestring or nullOptional<=128 characters

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

polarityenumOptional

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. Defaults to neutral.

Allowed values:

Response

The created behavior.

idstring

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

namestring or null<=128 characters

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

descriptionstring

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

polarityenum

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.

Allowed values:

created_atdatetime

updated_atdatetime

Errors

400

Bad Request Error

403

Forbidden Error

429

Too Many Requests Error