List policy entries

GET

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

• Production

Returns the policy entries of a workspace, of every status, in creation order. Policies define rules and constraints for conversations, for example discount limits, required verification steps, or escalation triggers; the assistant applies the policies with status approved. To read only the policies awaiting review, use the pending endpoint. Without limit and cursor, the answer is every policy entry, as a JSON array. With either, the answer is one page: at most limit policy entries, with nextCursor when more follow. Pass nextCursor as the cursor parameter to read the next page.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

string format: uuid

The workspace to list policies for.

Query Parameters

limit

integer

>= 1 <= 100

Policy entries per page, from 1 to 100. Sending it asks for one page; with cursor and no limit, a page holds 50 policy entries.

Example

50

cursor

string

>= 1 characters <= 512 characters

Opaque cursor from a previous response’s nextCursor. The page starts after the last policy entry of that response.

Example

eyJjIjoiMjAyNi0wMS0xMFQwOTowMDowMC4wMDAwMDBaIiwiaSI6IjExMjIzMzQ0LTU1NjYtNDc4OC05OWFhLWJiY2NkZGVlZmYwMCJ9

Responses

200

Without limit and cursor, every policy entry in the workspace, as an array. With either, one page of policy entries, with nextCursor when more follow.

One of:

Array<object>

List of policy entries.

Array<object>

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 data stored with the policy, as free-form JSON. The Policy Agent receives it together with the rule text when it retrieves the policy.

object | null

Example

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

sourceType

required

How the policy came to be. manual is a policy written by a person, approved when it is created. extracted is a proposal the learning loop drafted from a resolved conversation. The API stores the value sent, and a policy created with a value other than manual starts as pending_review.

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

Where the policy stands, with the values of a knowledge base entry. approved: in use, the assistant applies it. pending_review: created for review, through the API with a sourceType other than manual; it is not applied until it is approved. proposed: drafted by oHallo, for example by the learning loop from a resolved conversation; it is not applied until it is approved, and a proposal that changes an existing policy is applied to that policy when it is approved. rejected: declined in review. archived: no longer in use, kept for the record.

string

Allowed values: pending_review approved rejected archived proposed

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

object

One page of policy entries, in creation order. Pass nextCursor as the cursor query parameter to read the next page; the last page carries no nextCursor.

object

data

required

The policy entries on this page, at most limit of them.

Array<object>

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 data stored with the policy, as free-form JSON. The Policy Agent receives it together with the rule text when it retrieves the policy.

object | null

Example

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

sourceType

required

How the policy came to be. manual is a policy written by a person, approved when it is created. extracted is a proposal the learning loop drafted from a resolved conversation. The API stores the value sent, and a policy created with a value other than manual starts as pending_review.

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

Where the policy stands, with the values of a knowledge base entry. approved: in use, the assistant applies it. pending_review: created for review, through the API with a sourceType other than manual; it is not applied until it is approved. proposed: drafted by oHallo, for example by the learning loop from a resolved conversation; it is not applied until it is approved, and a proposal that changes an existing policy is applied to that policy when it is approved. rejected: declined in review. archived: no longer in use, kept for the record.

string

Allowed values: pending_review approved rejected archived proposed

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

nextCursor

Opaque cursor for the next page. Present when more policy entries follow; omitted on the last page.

string

Example

eyJjIjoiMjAyNi0wMS0xMFQwOTowMDowMC4wMDAwMDBaIiwiaSI6IjExMjIzMzQ0LTU1NjYtNDc4OC05OWFhLWJiY2NkZGVlZmYwMCJ9

404

No workspace exists with the given workspaceId, or it is outside the API key’s brand or workspace restriction.

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

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]

422

Validation error. limit is not an integer from 1 to 100, or cursor is empty or is not a nextCursor value.

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

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]