Evaluate agent output via the Pecta REST API

The REST API runs Pecta quality gates server-side and returns a gate verdict in a single HTTP response. This is the right integration mode when you cannot run Node.js in-process — for example, in Python or Go services, batch pipelines, or automated testing. Gate latency is 50–100 ms end-to-end because the evaluation happens on Pecta’s infrastructure rather than inside your process. All /v1/* endpoints require an Authorization: Bearer <key> header. Use your publishable key (pk_live_...) for evaluation requests.

Get an API key

Sign in at pecta.ai, open Settings → API keys, and create a new key. Copy the pk_live_... value — it is only shown once.Store it in an environment variable:

export PECTA_API_KEY=pk_live_xxx

Send your first evaluation

POST agent output to /v1/evaluate. The minimum required fields are agent_id and output. Include tool and latency_ms to enable the latency gate and to improve dashboard visibility.

curl -X POST https://api.pecta.ai/v1/evaluate \
  -H "Authorization: Bearer $PECTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "research-bot-v2",
    "tool": "shell.run",
    "output": { "stdout": "ls -la /tmp" },
    "latency_ms": 18
  }'

import os
import httpx

response = httpx.post(
    "https://api.pecta.ai/v1/evaluate",
    headers={"Authorization": f"Bearer {os.environ['PECTA_API_KEY']}"},
    json={
        "agent_id": "research-bot-v2",
        "tool": "shell.run",
        "output": {"stdout": "ls -la /tmp"},
        "latency_ms": 18,
    },
)
result = response.json()
print(result["passed"], result["gates"])

const response = await fetch("https://api.pecta.ai/v1/evaluate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PECTA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "research-bot-v2",
    tool: "shell.run",
    output: { stdout: "ls -la /tmp" },
    latency_ms: 18,
  }),
});
const result = await response.json();
console.log(result.passed, result.gates);

Read the response

A successful evaluation returns HTTP 200 with the verdict, per-gate detail, total latency, and the agent’s current reputation score.

{
  "evaluation_id": "v7k2mQpXtR9fNwJz",
  "passed": true,
  "gates": [
    { "name": "filesystem", "passed": true, "latency_ms": 1.4 },
    { "name": "pii",        "passed": true, "latency_ms": 0.8 },
    { "name": "content",    "passed": true, "latency_ms": 0.3 }
  ],
  "total_latency_ms": 62,
  "reputation": {
    "score": 812,
    "lifecycle": "active",
    "eval_count": 124
  }
}

When a gate fails, passed is false and the failing gate includes a reason string:

{
  "evaluation_id": "a1b2c3d4e5f6g7h8",
  "passed": false,
  "gates": [
    {
      "name": "filesystem",
      "passed": false,
      "reason": "destructive rm command detected",
      "latency_ms": 1.1
    }
  ],
  "total_latency_ms": 58,
  "reputation": {
    "score": 640,
    "lifecycle": "active",
    "eval_count": 87
  }
}

Handle errors

API errors return a non-2xx status with a structured body:

{
  "error": "Unauthorized",
  "code": "INVALID_API_KEY",
  "status": 401
}

Common status codes:

Status	Code	Cause
`401`	`INVALID_API_KEY`	Missing or revoked API key
`422`	`VALIDATION_ERROR`	Request body failed schema validation
`429`	`RATE_LIMITED`	Too many requests
`500`	`INTERNAL_ERROR`	Unexpected server error

Request body reference

Field	Type	Required	Description
`agent_id`	string	Yes	Identifier for the agent. Determines which reputation score is updated.
`output`	unknown	Yes	The agent’s output to evaluate. Passed to each gate but never stored.
`tool`	string	No	Name of the tool that produced the output (e.g. `shell.run`).
`latency_ms`	number	No	Time taken for the agent to produce the output. Required to trigger the latency gate.
`input`	unknown	No	Original tool input. Used by RTB gates for request/response matching. Never stored.

Never send sensitive user data in input or output fields beyond what gates need to evaluate. Pecta does not store these fields, but minimising what you send is good practice.

Get Started

Core Concepts

Gates

RTB Gates

Dashboard

Evaluate agent output via the Pecta REST API

Request body reference

​Request body reference

Request body reference