Skip to main content
POST /v1/evaluate runs Pecta’s gate suite against a single agent output on Pecta’s servers. This is the simplest way to add quality gates when you cannot install the @pecta/core SDK in-process — for example from a Python, Go, or Java backend. Expect 50–100 ms round-trip latency because gates execute server-side. The cloud engine runs three default gate categories — filesystem safety, PII detection, and content safety — in parallel with a 50 ms timeout budget. Each gate returns its own pass/fail result, and the overall passed field is true only when every gate passes. After evaluation, Pecta updates the agent’s rolling reputation window (last 500 evals) and returns the latest score in the same response.

​
Endpoint

POST https://api.pecta.ai/v1/evaluate

​
Authentication

Required. Pass your API key as a Bearer token: 
Authorization: Bearer pk_live_<your-key>

​
Request body

​
agent_id
string
required
Unique identifier for the agent being evaluated. Must be between 1 and 200 characters. Pecta auto-creates an agent record on the first evaluation — no prior registration needed.
​
tool
string
Name of the tool or function the agent called. Maximum 200 characters. Included in event records for filtering and analytics.
​
input
any
The input that was passed to the agent or tool. Pecta does not store this value — it is used only within the gate evaluation and then discarded. Send null or omit the field if you do not want to include it.
​
output
any
required
The agent’s output to evaluate. This is the primary value inspected by the gate suite. Pecta never persists this payload.
​
latency_ms
number
How long the agent took to produce its output, in milliseconds. Maximum 60000. Used by the latency gate and to compute the reputation latency score component.

​
Response fields

​
evaluation_id
string
Unique ID for this evaluation, generated by the gate engine.
​
passed
boolean
true when every gate passed. false when one or more gates failed.
​
gates
array
Per-gate results. Each element describes one gate’s verdict.
​
total_latency_ms
number
Total time spent running all gates, in milliseconds.
​
reputation
object
The agent’s updated reputation after this evaluation.

​
Example request

curl --request POST \
  --url https://api.pecta.ai/v1/evaluate \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "summarizer-v2",
    "tool": "generate_summary",
    "output": "The quarterly earnings report shows a 12% increase in revenue.",
    "latency_ms": 340
  }'

​
Example responses

Passed: 
{
  "evaluation_id": "ev_7kQmN3pXaLz",
  "passed": true,
  "gates": [
    { "name": "filesystem", "passed": true, "latency_ms": 2 },
    { "name": "pii",        "passed": true, "latency_ms": 3 },
    { "name": "content",    "passed": true, "latency_ms": 4 }
  ],
  "total_latency_ms": 9,
  "reputation": {
    "score": 612,
    "status": "active",
    "evaluations": 87,
    "passed": 81,
    "pass_rate": 0.9310,
    "avg_latency_ms": 310,
    "streak": 14
  }
}
Failed (PII detected): 
{
  "evaluation_id": "ev_2pRtY9wBcHq",
  "passed": false,
  "gates": [
    { "name": "filesystem", "passed": true,  "latency_ms": 2 },
    { "name": "pii",        "passed": false, "latency_ms": 5,
      "reason": "output contains email address" },
    { "name": "content",    "passed": true,  "latency_ms": 3 }
  ],
  "total_latency_ms": 10,
  "reputation": {
    "score": 584,
    "status": "active",
    "evaluations": 88,
    "passed": 81,
    "pass_rate": 0.9204,
    "avg_latency_ms": 312,
    "streak": 0
  }
}