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

# POST /v1/evaluate — cloud gate evaluation

> Submit an agent output to Pecta's cloud gate engine. Get an instant pass/fail verdict, per-gate results, and an updated reputation score in one response.

`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

<ParamField body="agent_id" type="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.
</ParamField>

<ParamField body="tool" type="string">
  Name of the tool or function the agent called. Maximum 200 characters. Included in event records for filtering and analytics.
</ParamField>

<ParamField body="input" type="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.
</ParamField>

<ParamField body="output" type="any" required>
  The agent's output to evaluate. This is the primary value inspected by the gate suite. Pecta never persists this payload.
</ParamField>

<ParamField body="latency_ms" type="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.
</ParamField>

## Response fields

<ResponseField name="evaluation_id" type="string">
  Unique ID for this evaluation, generated by the gate engine.
</ResponseField>

<ResponseField name="passed" type="boolean">
  `true` when every gate passed. `false` when one or more gates failed.
</ResponseField>

<ResponseField name="gates" type="array">
  Per-gate results. Each element describes one gate's verdict.

  <Expandable title="Gate result fields">
    <ResponseField name="gates[].name" type="string">
      Gate identifier, e.g. `"filesystem"`, `"pii"`, `"content"`.
    </ResponseField>

    <ResponseField name="gates[].passed" type="boolean">
      Whether this specific gate passed.
    </ResponseField>

    <ResponseField name="gates[].reason" type="string">
      Human-readable explanation when the gate fails. Omitted on pass.
    </ResponseField>

    <ResponseField name="gates[].latency_ms" type="number">
      Time taken by this gate, in milliseconds.
    </ResponseField>

    <ResponseField name="gates[].skipped" type="boolean">
      `true` when the gate was skipped (e.g. tmax guard exhausted). Omitted when `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_latency_ms" type="number">
  Total time spent running all gates, in milliseconds.
</ResponseField>

<ResponseField name="reputation" type="object">
  The agent's updated reputation after this evaluation.

  <Expandable title="Reputation fields">
    <ResponseField name="reputation.score" type="number">
      0–1000 score. Computed as `(pass_rate × 400) + (latency_score × 250) + (streak × 200) + (volume × 150)`. Returns `0` until the agent has at least one evaluation on record.
    </ResponseField>

    <ResponseField name="reputation.status" type="string">
      Lifecycle stage: `"new"` (0 evals), `"calibrating"` (1–49), `"active"` (50–499), or `"mature"` (500+).
    </ResponseField>

    <ResponseField name="reputation.evaluations" type="number">
      Total evaluations in the rolling window (max 500).
    </ResponseField>

    <ResponseField name="reputation.passed" type="number">
      Number of passing evaluations in the window.
    </ResponseField>

    <ResponseField name="reputation.pass_rate" type="number">
      Fraction of evaluations that passed (0–1).
    </ResponseField>

    <ResponseField name="reputation.avg_latency_ms" type="number">
      Average latency across the rolling window.
    </ResponseField>

    <ResponseField name="reputation.streak" type="number">
      Consecutive passing evaluations from the most recent event.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example request

```bash theme={null}
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:**

```json theme={null}
{
  "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):

```json theme={null}
{
  "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
  }
}
```