🛡️ Portarus: the gateway for AI agents Discover more →
Documentation

Portarus Docs

Everything you need to integrate Portarus: semantic security gateway, webhooks, rate limits, logs, and billing.

Getting started

What is Portarus?

Portarus is a semantic security gateway that intercepts, analyzes, and filters webhook or API traffic to stop prompt injection, duplication, and budget abuse before it reaches your stack.

  • Semantic filtering: intent-aware detection, not just keyword blocks.
  • Cost control: rate limits per tenant, per key, and per route.
  • Auditability: full logs, reasons, and trace IDs for every decision.
  • Resilience: L1 Redis cache + L2 database with circuit breaker.

Quickstart (5 minutes)

CLI cURL
  1. Create an account and grab your API Key in the dashboard.
  2. Create a gateway (slug + destination URL + secret).
  3. Send your first analysis to the semantic API.
curl -X POST https://api.portarus.com/api/analyze/risk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Block prompt injection"}'

Auth

Bearer API Key on every request.

Sandbox

Use the free plan limits to test safely.

Traceable

Every response ships a trace_id header.

API authentication

All requests must include your API Key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Find and rotate keys in your dashboard.

Gateways: create, rotate, secure

  • Create: POST /api/gateways (name, slug, destination_url, secret).
  • Rotate secret: POST /api/gateways/:id/rotate.
  • Per-tenant controls: max_rps, semantic thresholds, dedup TTL.
  • Cache: L1 Redis 24h, lazy refresh on access.

Inbound

POST /g/{base64url_id}/{hmac} with X-Gateway-Secret header.

Body is forwarded to your destination if allowed.

Outbound

Cogmus injects a _cogmus envelope with dpn.result (PASS|FLAG|HARM|null), status, messages, and meta.trace_id.

Headers: X-Gateway-Trace-Id, X-Gateway-Decision.

Rate limits by plan

  • ZERO (free): 3K webhooks/mo, 3 gateways.
  • Builder — $12/mo: 30K webhooks/mo, 15 gateways.
  • Pro — $12/mo: 100K webhooks/mo, 20 gateways.
  • Business — $119/mo: 1M webhooks/mo, 200 gateways.
  • Enterprise: Unlimited webhooks/mo, Unlimited gateways, custom SLA.

Exceeding limits returns 429 with retry-after.

Security & semantic filtering

Structural filters

  • Strict JSON schema validation.
  • Rate limiting + Lua atomic counters.
  • Dedup via SHA-256 of sender_id + content.

Semantic engine

  • Decision: ALLOW | FLAG | BLOCK.
  • Fallback policy on timeout: open or closed.
  • Reasons + risk_score returned in metadata.

Webhooks & callbacks

Receive real-time events when analyses complete or are blocked.

POST /webhook/configure
Content-Type: application/json

{
  "url": "https://...",
  "events": ["analysis.completed"]
}
  • Events: analysis.completed, analysis.blocked, gateway.resilience_mode.
  • Retry: exponential backoff, signed with your webhook secret.
  • Headers: X-Gateway-Signature (HMAC-SHA256), X-Gateway-Trace-Id.

Metadata, logs, and tracing

Every decision includes traceability for debugging and compliance.

Headers

  • X-Gateway-Trace-Id
  • X-Gateway-Decision (ALLOWED/BLOCKED)
  • X-Gateway-Reason

Payload injection

_cogmus: dpn.result (PASS|FLAG|HARM|null), dpn.score, status.processed, status.reasons[], messages, meta.trace_id.

Log retention depends on plan limits.

Validation & anomaly detection

Schema validation

POST /api/analyze/validate
Content-Type: application/json

{
  "data": { ... },
  "schema": { ... }
}

Anomaly detection

POST /api/analyze/anomaly
Content-Type: application/json

{
  "metrics": { ... },
  "baseline": { ... }
}

Use semantic analysis + anomalies to flag abuse and enforce business rules.

Plans & limits

Plan matrix

  • ZERO: 3K webhooks/mo, logs 1d, 3 gateways.
  • Builder: 30K webhooks/mo, logs 7d, 15 gateways.
  • Pro: 100K webhooks/mo, logs 10d, 20 gateways.
  • Business: 1M webhooks/mo, logs 90d, 200 gateways.
  • Enterprise: Unlimited webhooks/mo, logs up to 1 year, Unlimited gateways, negotiated SLA.

Billing notes

  • Stripe subscriptions, upgrade/downgrade prorated.
  • Overage protection: hard caps with 429 or semantic_skip.
  • Invoice PDFs available in dashboard.

Error handling

  • 400 Bad request (invalid JSON or schema).
  • 401 Unauthorized (missing/invalid API Key).
  • 403 Forbidden (gateway secret mismatch).
  • 429 Rate limit exceeded.
  • 503 Resilience mode unavailable (no cache + DB down).

Official SDKs

npm install @portarus/sdk
portarus
go get github.com/portarus/go-sdk

Support & status

  • Email: [email protected]
  • Chat: In-dashboard live chat
  • Community: Discord (coming soon)
  • Status: status.portarus.com

Ready to ship secure webhooks?

Create your account and start protecting your AI stack in minutes.

Get started Try the playground