ramen ai | Documentation
arrow_back Back to Dashboard GitHub (opens in a new tab)

PaaS Endpoints

Direct REST API reference for the Evaluate and Audit endpoints.

Base URL

https://api.ramenai.dev/api/v1

All endpoints require a valid Authorization: Bearer ramen_sk_* header. See Authentication for key management.

POST /evaluate

The core governance endpoint. Evaluates a prompt against your configured guardrails and master prompts, returning a deterministic verdict.

Required scope: paas:evaluate

Request Body

{
  "prompt": "Am I having a manic episode?",
  "context": [
    { "role": "user", "content": "I haven't slept in 3 days" }
  ],
  "guardrails": ["no-medical-diagnosis"],
  "expert_id": "exp_abc123",
  "metadata": {
    "session_id": "sess_xyz",
    "user_tier": "enterprise"
  }
}
Field Type Required Description
prompt string Yes The user message or LLM output to evaluate.
context object[] No Conversation history for contextual evaluation.
guardrails string[] No Specific guardrail IDs to evaluate against. Defaults to all active guardrails.
expert_id string No Route through a specific deployed Expert.
metadata object No Arbitrary key-value pairs stored in the audit log.

Response

{
  "verdict": "BLOCK",
  "score": 0.12,
  "flags": ["no-medical-diagnosis"],
  "latency_ms": 38,
  "audit_id": "aud_7f3k9x2m4p",
  "reason": "Response contains a clinical diagnosis which violates the no-medical-diagnosis guardrail."
}

Verdict Values

Verdict Meaning Recommended Action
PASS No guardrails triggered Forward the response to the user
WARN Soft guardrail triggered Log for review, optionally allow
BLOCK Hard guardrail triggered Substitute a safe fallback response

GET /audit/:id

Retrieves the full audit record for a previous evaluation. Every evaluation is logged immutably — this endpoint provides the compliance trail.

Required scope: paas:audit

Response

{
  "id": "aud_7f3k9x2m4p",
  "timestamp": "2026-04-20T14:32:01.000Z",
  "verdict": "BLOCK",
  "score": 0.12,
  "flags": ["no-medical-diagnosis"],
  "latency_ms": 38,
  "payload_hash": "sha256:a1b2c3...",
  "workspace_id": "ws_def456",
  "expert_id": "exp_abc123",
  "metadata": {
    "session_id": "sess_xyz",
    "user_tier": "enterprise"
  }
}
info

Payload Hashing

The payload_hash is a SHA-256 hash of the original prompt. ramen ai does not store the raw prompt text — only the hash — ensuring zero data retention while maintaining a verifiable audit trail.

Rate Limits

Plan Evaluate Audit
Sandbox 100 req/min 50 req/min
Pro 1,000 req/min 500 req/min
Enterprise Custom Custom

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Error Codes

Status Code Description
401 UNAUTHORIZED Missing or invalid API key.
403 SCOPE_DENIED Key lacks the required scope.
404 NOT_FOUND Expert or audit record not found.
429 RATE_LIMITED Too many requests. Retry after X-RateLimit-Reset.
500 INTERNAL_ERROR Unexpected server error. Contact support.

Next Steps

Documentation