Admin operations

Arbitex provides three complementary operational controls for platform administrators: alert rules that notify you when a monitored metric crosses a threshold, retention policies that automate data lifecycle management for platform tables, and quota configurations that cap token and request usage per user or group.

All endpoints in this guide require an admin role.

---

Alerts

Overview

Alert rules monitor a named metric and fire when a measured value crosses a configured threshold within a rolling time window. Each rule specifies:

• The metric type to monitor (for example, dlp_block_count or request_rate)
• A threshold value and comparison operator (for example, greater_than 50)
• A window in minutes over which the metric is evaluated
• A cooldown period that prevents the same rule from firing repeatedly within a short interval

When a rule fires, Arbitex records the event in the alert history and, if a webhook_url is configured on the rule, sends an HTTP POST to that URL with the trigger details.

Alert evaluation runs on a background schedule. You can also trigger evaluation manually at any time using the evaluate endpoint.

Alert rule fields

Field	Type	Description
name	string	Human-readable label for this alert rule
metric_type	string	The metric being monitored (e.g., dlp_block_count, request_rate)
threshold	float	The value at which the rule fires
comparison	string	Comparison operator: greater_than, less_than, greater_than_or_equal, less_than_or_equal
window_minutes	integer	Rolling window in minutes over which the metric is evaluated
webhook_url	string | null	HTTP POST target called when the rule fires; null to disable webhook delivery
enabled	boolean	Whether the rule participates in scheduled and manual evaluation
cooldown_minutes	integer	Minimum minutes that must pass before the same rule fires again

API reference

Method	Path	Description
GET	/api/alerts	List all alert rules, ordered newest first
POST	/api/alerts	Create an alert rule; returns 201 Created
PUT	/api/alerts/{rule_id}	Update an alert rule; partial update, only provided fields are changed
DELETE	/api/alerts/{rule_id}	Delete an alert rule; cascades to associated history records; returns 204
GET	/api/alerts/history	List alert trigger history; accepts limit query parameter (default 100), ordered by triggered_at descending
POST	/api/alerts/evaluate	Manually trigger alert evaluation; returns any history records created during the run

Creating an alert rule

The following example creates a rule that fires when the DLP block count exceeds 50 events within a 10-minute window, with a 15-minute cooldown to avoid alert storms.

curl -s -X POST https://api.arbitex.ai/api/alerts \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High DLP Block Rate",
    "metric_type": "dlp_block_count",
    "threshold": 50.0,
    "comparison": "greater_than",
    "window_minutes": 10,
    "webhook_url": "https://ingest.example.com/arbitex-alerts",
    "enabled": true,
    "cooldown_minutes": 15
  }'

A successful response returns 201 Created with the full rule object including the assigned rule_id.

To disable the rule temporarily without deleting it:

curl -s -X PUT https://api.arbitex.ai/api/alerts/{rule_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Alert history

Each time a rule fires, Arbitex creates a history record containing the rule name, the triggered_at timestamp, and the metric value that caused the trigger. History records are retained until the alert rule is deleted, at which point they are cascade-deleted along with the rule.

Retrieve recent history with an optional limit:

curl -s "https://api.arbitex.ai/api/alerts/history?limit=50" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Results are ordered by triggered_at descending, so the most recent trigger appears first. Use this endpoint to audit when rules fired, correlate alert activity against incident timelines, and verify that cooldown windows are behaving as expected.

Manual evaluation

Trigger a full evaluation of all enabled alert rules without waiting for the next scheduled run:

curl -s -X POST https://api.arbitex.ai/api/alerts/evaluate \
  -H "Authorization: Bearer $ADMIN_TOKEN"

The response contains an array of any alert history records created during this evaluation run. If no rules fired, the array is empty. Manual evaluation respects cooldown windows — a rule that fired recently will not fire again until its cooldown expires.

Use this endpoint after making configuration changes to rules, after an incident to check for threshold breaches, or during testing to verify that a new rule is correctly configured.

---

Retention policies

Overview

Retention policies define how long records are kept in a given platform database table before they are automatically purged. Each policy targets a single table within your tenant and specifies a retention window in days. Records older than that window are eligible for deletion when the policy runs.

Retention operations are tenant-scoped: all create, read, update, delete, and run operations apply only to policies belonging to the authenticated admin’s tenant_id. Policies from other tenants are never visible or affected.

One-policy-per-table constraint: Only one retention policy may exist per table within a tenant. Attempting to create a second policy for the same table returns 409 Conflict. To change the retention window for a table, update the existing policy rather than creating a new one.

Retention policy fields

Field	Type	Description
table_name	string	The database table this policy applies to (e.g., audit_logs)
retention_days	integer	Records older than this many days are deleted when the policy runs
enabled	boolean	Whether this policy runs on the automated schedule

API reference

Method	Path	Description
POST	/api/admin/retention-policies	Create a retention policy; returns 409 Conflict if a policy for this table already exists
GET	/api/admin/retention-policies	List all retention policies for the tenant
GET	/api/admin/retention-policies/{policy_id}	Get a single retention policy
PUT	/api/admin/retention-policies/{policy_id}	Update a policy; partial update, only provided fields are changed
DELETE	/api/admin/retention-policies/{policy_id}	Delete a policy
GET	/api/admin/retention-policies/{policy_id}/preview	Dry run: returns the count of records that would be deleted and the oldest record date
POST	/api/admin/retention-policies/{policy_id}/run	Manually trigger cleanup for a single policy
POST	/api/admin/retention-policies/run-all	Manually trigger cleanup for all enabled policies in the tenant

Standard configuration

The platform audit log is a 90-day buffer. Records older than 90 days are eligible for purge under the standard retention configuration. To implement the standard:

curl -s -X POST https://api.arbitex.ai/api/admin/retention-policies \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "audit_logs",
    "retention_days": 90,
    "enabled": true
  }'

This matches the native 90-day audit log buffer described in Audit log. Before your SIEM integration is configured and validated, consider setting enabled: false on this policy so that records are not deleted before they have been exported. Once your SIEM pipeline is confirmed to be capturing events in real time, enable the policy to keep the platform database within its intended retention window.

Preview before running

Before running a cleanup, use the preview endpoint to see exactly what would be deleted:

curl -s https://api.arbitex.ai/api/admin/retention-policies/{policy_id}/preview \
  -H "Authorization: Bearer $ADMIN_TOKEN"

The response returns:

• The count of records that would be deleted if the policy ran now
• The date of the oldest record that would be affected

This is a read-only dry run. No data is modified. Use it to confirm the scope of a cleanup before committing, particularly before running a policy for the first time or after changing the retention_days value.

Manual cleanup

Single policy:

curl -s -X POST https://api.arbitex.ai/api/admin/retention-policies/{policy_id}/run \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns a RetentionCleanupResult with the table_name and the count of records deleted.

All enabled policies:

curl -s -X POST https://api.arbitex.ai/api/admin/retention-policies/run-all \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Runs cleanup for every enabled policy in the tenant in sequence. Disabled policies are skipped. Returns a result object for each policy that ran.

Policies with enabled: true also run on an automated schedule managed by the platform. Manual runs can be used to advance a scheduled cleanup, reclaim storage immediately after changing a retention window, or run cleanup during a maintenance window outside of the normal schedule. The automated schedule and manual triggers share the same cleanup logic — results are equivalent.

---

Quotas

Overview

Quotas cap token and request usage for individual users or groups of users. Limits can be set independently for daily and monthly windows across both token volume and request count dimensions. When a user’s request would exceed any applicable limit, the gateway returns HTTP 429 before the request reaches a model provider, and a quota_exceeded webhook event fires.

User quotas vs. group quotas:

• A user quota applies to a single user’s individual usage.
• A group quota applies to the aggregate usage of all members in that group, not per-member. If the group’s combined usage reaches the group limit, all members are blocked regardless of their individual quotas.

When both a user quota and one or more group quotas apply to a request, the effective limit for each dimension is the most restrictive value across all applicable configurations. See Billing and metering for the full enforcement algorithm.

Quota config fields

Field	Type	Description
daily_token_limit	integer | null	Maximum tokens (input + output) per calendar day (UTC); null for unlimited
monthly_token_limit	integer | null	Maximum tokens per calendar month (UTC); null for unlimited
daily_request_limit	integer | null	Maximum request count per calendar day (UTC); null for unlimited
monthly_request_limit	integer | null	Maximum request count per calendar month (UTC); null for unlimited

All time windows reset at 00:00:00 UTC. Daily limits reset every day; monthly limits reset on the first of each month.

A QuotaResponse includes all QuotaConfig fields plus the current enforcement state (which limits are active, current usage relative to each limit). A QuotaCheckResult includes an allowed boolean and details about which specific limit was hit.

API reference

Method	Path	Description
GET	/api/admin/users/{user_id}/quota	Get the quota configuration for a user
PUT	/api/admin/users/{user_id}/quota	Create or update a user quota (upsert)
DELETE	/api/admin/users/{user_id}/quota	Remove quota configuration for a user (removes all limits)
GET	/api/admin/groups/{group_id}/quota	Get the quota configuration for a group
PUT	/api/admin/groups/{group_id}/quota	Create or update a group quota (upsert); applies to aggregate group usage
DELETE	/api/admin/groups/{group_id}/quota	Remove quota configuration for a group

All quota PUT operations are upserts: if no quota exists for the target, one is created; if one exists, it is replaced with the provided values.

Setting a user quota

curl -s -X PUT https://api.arbitex.ai/api/admin/users/{user_id}/quota \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_token_limit": 50000,
    "monthly_token_limit": 1000000,
    "daily_request_limit": 200,
    "monthly_request_limit": null
  }'

This sets a daily cap of 50,000 tokens and 200 requests, a monthly cap of 1,000,000 tokens, and leaves monthly request count unlimited. To read the current configuration:

curl -s https://api.arbitex.ai/api/admin/users/{user_id}/quota \
  -H "Authorization: Bearer $ADMIN_TOKEN"

To remove all limits for the user:

curl -s -X DELETE https://api.arbitex.ai/api/admin/users/{user_id}/quota \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Setting a group quota

Group quotas use the same schema. The limits apply to the combined usage of all group members, not to each member individually.

curl -s -X PUT https://api.arbitex.ai/api/admin/groups/{group_id}/quota \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_token_limit": null,
    "monthly_token_limit": 10000000,
    "daily_request_limit": 5000,
    "monthly_request_limit": 100000
  }'

This sets a group-level monthly token cap of 10 million, a daily request cap of 5,000, and a monthly request cap of 100,000 for the group’s aggregate usage. Daily token usage is left unlimited.

Use group quotas to enforce department-level or team-level budgets without needing to configure each member individually. Pair group quotas with individual user quotas to enforce both a per-person limit and a shared team ceiling.

What happens at the quota limit

When a request would exceed any applicable quota limit, the gateway blocks the request before evaluation begins and returns:

HTTP 429 Too Many Requests

{
  "error": "quota_exceeded",
  "quota_type": "daily_token_limit",
  "limit": 50000,
  "used": 50103,
  "reset_at": "2026-03-10T00:00:00+00:00"
}

The response includes a Retry-After header with the reset timestamp. Client applications should not retry until after that time.

Simultaneously, a quota_exceeded webhook event fires to any registered webhook subscriptions. The payload includes the user ID, the group ID if a group cap was the binding constraint, the quota dimension that was exceeded, the configured limit, and the usage at the time of denial. Configure a webhook on the quota_exceeded event type to feed these signals into alerting or capacity planning workflows. See Webhooks for subscription setup.

---

See also

• Billing and metering — Quota enforcement algorithm, cost-based limits, and the full quota dimension reference
• Webhooks — Subscribe to quota_exceeded and other platform events
• Audit log — 90-day retention buffer, HMAC chain verification, and SIEM integration for long-term retention
• Groups and RBAC — Managing groups that group quotas apply to