Create a policy entry

POST

/api/workspaces/{workspaceId}/policy-entries

• Production

Creates a new policy entry in the specified workspace. Manually created policies are immediately set to ‘approved’ status and enforced by the AI. Write the rule in clear natural language — the AI interprets it during conversation processing.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

string format: uuid

The workspace to create the policy in.

Request Body

object

topic

required

The topic or domain this policy applies to.

string

>= 1 characters

Example

discount_authorization

ruleText

required

The policy rule in natural language.

string

>= 1 characters

Example

Never offer a discount above 10% without creating an attention item for manager approval.

sourceType

required

How this policy was created. Use ‘manual’ for human-authored policies.

string

>= 1 characters

Example

manual

conditions

Optional structured conditions for when this policy applies.

object

key

additional properties

Example

{
  "min_order_value": 500
}

sourceConversationId

Optional reference to the conversation that inspired this policy.

string

confidence

Confidence score, typically set by the learning loop.

number

<= 1

Responses

200

The policy entry was created and is immediately enforced by the AI.

A policy entry defines a rule that governs how the AI should behave in specific situations. Unlike KB entries (which provide factual answers), policies specify constraints, guardrails, and behavioral guidelines. For example, ‘Never offer more than 10% discount without manager approval’ or ‘Always ask for an order number before looking up shipping status’. Policies can be created manually or proposed by the learning loop.

object

id

required

Unique identifier for the policy entry.

string format: uuid

Example

pe1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this policy belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

workspaceId

required

The workspace this policy is scoped to.

string format: uuid

Example

w1a2b3c4-5678-9abc-def0-1234567890ab

topic

required

The topic or domain this policy applies to. Used by the AI to determine which policies are relevant to the current conversation.

string

Example

discount_authorization

ruleText

required

The policy rule in natural language. This is the instruction the AI follows.

string

Example

Never offer a discount above 10% without creating an attention item for manager approval. For discounts up to 10%, apply automatically if the customer has placed 3 or more orders.

conditions

Optional structured conditions that qualify when this policy applies. Can include time-based, value-based, or context-based conditions.

object | null

Example

{
  "min_order_value": 500,
  "customer_tier": "gold"
}

sourceType

required

How this policy was created. ‘manual’ means created by a human, ‘learning_loop’ means proposed by the AI after analyzing resolved conversations.

string

Example

manual

confidence

Confidence score between 0 and 1, set by the learning loop when proposing policies. Null for manually created policies.

number | null

Example

0.85

status

required

Lifecycle status. Same semantics as KB entry status — only ‘approved’ policies are enforced by the AI.

string

Allowed values: pending_review approved rejected archived

Example

approved

createdAt

required

Timestamp when the policy was created.

string format: date-time

Example

2026-02-05T09:00:00.000Z

updatedAt

required

Timestamp when the policy was last updated.

string format: date-time

Example

2026-03-18T11:30:00.000Z

422

Validation error. One or more required fields are missing or invalid.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found