API Reference

Decision APIs

Core endpoints for rate-limit evaluation and concurrency control.

POST /v1/check

Evaluate a rate-limit decision for a request context.

Request Body

{
  "request_id": "req-1",
  "org_id": "acme",
  "tenant_id": "retail",
  "signal_type": "http",
  "operation": "charge",
  "endpoint": "/v1/charge",
  "method": "POST",
  "user_id": "u1",
  "tags": { "env": "production" }
}

Response (200 OK)

{
  "allowed": true,
  "action": "allow",
  "reason": "within_limit",
  "matched_policy_id": "payments-limit",
  "remaining": 99,
  "retry_after": 0,
  "shadow_mode": false
}

POST /v1/acquire

Acquire a concurrency lease. Use with concurrency limiter algorithm.

Request Body

{
  "request_id": "req-2",
  "org_id": "acme",
  "signal_type": "http",
  "operation": "heavy-query",
  "user_id": "u1"
}

Response

{
  "allowed": true,
  "action": "allow",
  "reason": "lease_acquired",
  "remaining": 4
}

POST /v1/release

Release a previously acquired concurrency lease.

Request Body

{
  "request_id": "req-2",
  "org_id": "acme",
  "signal_type": "http",
  "operation": "heavy-query",
  "user_id": "u1"
}

Response

{
  "allowed": true,
  "action": "allow",
  "reason": "lease_released"
}

Policy CRUD

GET /v1/policies

List all policies.

Response

[
  {
    "policy_id": "payments-limit",
    "name": "Payments limit",
    "enabled": true,
    "priority": 100,
    "scope": { "org_id": "acme", "signal_type": "http", "operation": "charge" },
    "algorithm": { "type": "fixed_window", "limit": 100, "window": "1m" },
    "action": "deny",
    "failure_mode": "fail_open",
    "enforcement_mode": "enforce",
    "rollout_percent": 100
  }
]

POST /v1/policies

Create a new policy.

Request Body

{
  "policy_id": "payments-limit",
  "name": "Payments limit",
  "enabled": true,
  "priority": 100,
  "scope": {
    "org_id": "acme",
    "signal_type": "http",
    "operation": "charge"
  },
  "algorithm": {
    "type": "fixed_window",
    "limit": 100,
    "window": "1m"
  },
  "action": "deny",
  "failure_mode": "fail_open",
  "enforcement_mode": "enforce",
  "rollout_percent": 100
}

GET /v1/policies/{id}

Get a specific policy by ID.

PUT /v1/policies/{id}

Update an existing policy. The full policy body is required.

DELETE /v1/policies/{id}

Delete a policy by ID.

Policy Lifecycle APIs

POST /v1/policies/validate

Validate a policy definition before deployment.

Request

{
  "name": "Validation sample",
  "enabled": true,
  "scope": { "signal_type": "http", "operation": "charge" },
  "algorithm": { "type": "fixed_window", "limit": 10, "window": "1m" },
  "action": "deny",
  "rollout_percent": 50
}

Response

{ "valid": true }

POST /v1/policies/{id}/rollout

Update the rollout percentage for gradual enforcement.

{ "rollout_percent": 25 }

POST /v1/policies/{id}/rollback

Roll back to a specific previous version.

{ "version": 1 }

GET /v1/policies/{id}/audit

Get the audit trail for a policy — all changes with timestamps, action types, old/new values.

GET /v1/policies/{id}/versions

Get all historical versions of a policy for review or rollback.

Analytics

GET /v1/analytics/summary

Get a summary of decision events with tag aggregation.

Query Parameters

Example

curl http://localhost:8080/v1/analytics/summary?top=5

Sidecar / Agent Endpoints

Default port: :18080

gRPC Service

Proto definition: api/proto/rlaas.proto  |  Default port: :9090

service RateLimitService {
  rpc CheckLimit(CheckLimitRequest)  returns (CheckLimitResponse);
  rpc Acquire(AcquireRequest)        returns (AcquireResponse);
  rpc Release(ReleaseRequest)        returns (ReleaseResponse);
}

The gRPC service exposes the same decision logic as the HTTP API. Generate client stubs from the proto file for any language.

RequestContext Object

Sent as the body of decision API calls. All fields are optional except as noted.

Decision Object

Returned by decision API calls.

Policy Object

Used for policy CRUD operations.

Error Format

All error responses return a JSON body with a descriptive message:

{
  "error": "policy not found",
  "status": 404
}