Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
1

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
2

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
  }'
3

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
  }
}
4

Handle errors

API errors return a non-2xx status with a structured body:
{
  "error": "Unauthorized",
  "code": "INVALID_API_KEY",
  "status": 401
}
Common status codes:
StatusCodeCause
401INVALID_API_KEYMissing or revoked API key
422VALIDATION_ERRORRequest body failed schema validation
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORUnexpected server error

​
Request body reference

FieldTypeRequiredDescription
agent_idstringYesIdentifier for the agent. Determines which reputation score is updated.
outputunknownYesThe agent’s output to evaluate. Passed to each gate but never stored.
toolstringNoName of the tool that produced the output (e.g. shell.run).
latency_msnumberNoTime taken for the agent to produce the output. Required to trigger the latency gate.
inputunknownNoOriginal 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.