Policies

Policy resources define limits and permissions for actions performed by users of an account. For example, policies can restrict the number of messages users can send in a specified time frame and block actions if limits are exceeded.

Policy object

Attributes

id

String

A unique identifier for the policy.

name

String

The name of the policy, which helps identify it.

slug

String

A human-friendly string used to access the policy.

description

String

A short description that summarizes the purpose or functionality of the policy.

isDefault

Boolean

Indicates whether this is the default policy applied to accounts unless a specific policy is assigned.

entitlements

Array of Objects

A list of entitlements that define specific actions and limits enforced by the policy.

created_at

Date

The date and time when the policy was created.

updated_at

Date

The date and time when the policy was last updated.

{
  "id": "policy_Rm4Mnheq2bfEPhBhP7SY",
  "status": "active",
  "isDefault": true,
  "name": "Standard Policy",
  "slug": "standard-policy",
  "description": "A standard policy for managing thread actions.",
  "entitlements": [
    {
      "id": "entitlement_8e2hBbhRm4MnhfEPP7SY",
      "status": "active",
      "type": "message",
      "amount": 100,
      "windowDuration": {
        "size": 600,
        "unit": "seconds"
      },
      "overageBlockDuration": {
        "size": 1000,
        "unit": "seconds"
      },
      "agents": {
        "type": "specific",
        "agentIds": [
          "agent_fEPhBhRm4Mnheq2bP7SY",
          "agent_hBhRm4Mnheq2bfEPP7SY"
        ]
      },
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

List policies

Retrieve a list of all policies, including details and limits applied to accounts.

GEThttps://api.metorial.com/policies
curl -X GET https://api.metorial.com/policies 
  -H "Authorization: Bearer metorial_sk_..."

Retrieve Policy Details

Fetch comprehensive information about a specific policy using its unique ID.

URL Parameters

policyId

String

The unique identifier for a policy.

entitlementId

String

The unique identifier for an entitlement.

GEThttps://api.metorial.com/policies/:policyId
curl -X GET "https://api.metorial.com/policies/policy_Rm4Mnheq2bfEPhBhP7SY" 
  -H "Authorization: Bearer metorial_sk_..."

Create New Policy

Define and create a new policy with the provided attributes.

Request Body

name

String

The name of the policy.

slug

String

A unique slug identifier for the policy.

description

StringOptional

Optional brief description of the policy.

POSThttps://api.metorial.com/policies
curl -X POST https://api.metorial.com/policies 
  -H "Authorization: Bearer metorial_sk_..." 
  -H "Content-Type: application/json" 
  -d '{
    "name": "New Policy",
    "slug": "new-policy",
    "description": "This is a new policy."
  }'

Update Existing Policy

Update the details of an existing policy using the provided attributes.

URL Parameters

policyId

String

The unique identifier for a policy.

entitlementId

String

The unique identifier for an entitlement.

Request Body

name

StringOptional

The updated name of the policy.

slug

StringOptional

Updated slug to access the policy by.

description

StringOptional

Optional updated description of the policy.

isDefault

BooleanOptional

Set this policy as the default for accounts without specific assignments.

PUThttps://api.metorial.com/policies
curl -X POST https://api.metorial.com/policies/policy_Rm4Mnheq2bfEPhBhP7SY 
  -H "Authorization: Bearer metorial_sk_..." 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Updated Policy",
    "slug": "updated-policy",
    "description": "This is an updated policy."
  }'

Add Policy Entitlement

Assign a new entitlement to a specified policy.

URL Parameters

policyId

String

The unique identifier for a policy.

entitlementId

String

The unique identifier for an entitlement.

Request Body

id

String

Unique identifier for the entitlement.

type

Enum

The type of entitlement, e.g., "message".

amount

Number

The allowed amount within the specified time frame.

windowDuration

Object

Defines the time window for the entitlement.

overageBlockDuration

Object

Duration blocks for overages if limits are exceeded.

agents

Object

Agent-level restrictions for the entitlement.

POSThttps://api.metorial.com/policies/:policyId/entitlements
curl -X POST https://api.metorial.com/policies/policy_Rm4Mnheq2bfEPhBhP7SY/entitlements 
  -H "Authorization: Bearer metorial_sk_..." 
  -H "Content-Type: application/json" 
  -d '{
    "type": "message",
    "amount": 100,
    "windowDuration": { "size": 600, "unit": "seconds" },
    "overageBlockDuration": { "size": 1000, "unit": "seconds" },
    "agents": {
      "type": "specific",
      "agentIds": ["agent_fEPhBhRm4Mnheq2bP7SY", "agent_hBhRm4Mnheq2bfEPP7SY"]
    }
  }'

Update Entitlement Details

Modify an existing entitlement assigned to a specific policy.

URL Parameters

policyId

String

The unique identifier for a policy.

entitlementId

String

The unique identifier for an entitlement.

Request Body

type

EnumOptional

The type of entitlement, e.g., "message".

amount

NumberOptional

Updated allowed amount within the defined window.

windowDuration

ObjectOptional

Updated time window for the entitlement.

overageBlockDuration

ObjectOptional

Updated overage block duration.

agents

ObjectOptional

Updated agent-level restrictions for the entitlement.

PUThttps://api.metorial.com/policies/:policyId/entitlements/:entitlementId
curl -X PUT https://api.metorial.com/policies/policy_Rm4Mnheq2bfEPhBhP7SY/entitlements/entitlement_8e2hBbhRm4MnhfEPP7SY


  -H "Authorization: Bearer metorial_sk_..." 
  -H "Content-Type: application/json" 
  -d '{
    "amount": 200
  }'

Delete Policy Entitlement

Permanently delete a specific entitlement from a policy.

URL Parameters

policyId

String

The unique identifier for a policy.

entitlementId

String

The unique identifier for an entitlement.

DELETEhttps://api.metorial.com/policies/:policyId/entitlements/:entitlementId
curl -X DELETE https://api.metorial.com/policies/policy_Rm4Mnheq2bfEPhBhP7SY/entitlements/entitlement_8e2hBbhRm4MnhfEPP7SY


  -H "Authorization: Bearer metorial_sk_..."